fix(chat): report a failed action stream instead of committing it as finished

pipeChatAndCapture returns a stream failure rather than throwing it, so a
mid-stream failure in a response returned from onAction was committed as a
complete answer, snapshotted, and followed by a normal turn-complete with no
error — the browser saw the stream stop and the next turn built on the
truncated text. The partial is still kept; the failure is now surfaced with it.

Document that the instructions lane is delivered by chat.toStreamTextOptions(),
and that an injection applies to the next inference call only.

Author: ericallam

docs/ai-chat/background-injection.mdx

@@ -208,8 +208,20 @@ its own advice is to use the instructions option. `Instructions` accepts
 `Array<SystemModelMessage>`, so the injected block is appended there rather than
 smuggled into the transcript.
 
+<Warning>
+  The instructions lane is delivered by `chat.toStreamTextOptions()`, because that
+  is the only place the SDK can set `streamText`'s instructions for you. If your
+  `run()` calls `streamText({ model, messages, abortSignal })` without spreading
+  `chat.toStreamTextOptions()`, a `role: "system"` injection never reaches the
+  model. The conversational lane has no such requirement — it arrives through
+  `messages` either way.
+</Warning>
+
 Two things worth knowing:
 
+- An injection applies to the next inference call only. The lane is drained once
+  applied, so a block injected in `onTurnComplete` shapes the following turn and is
+  not repeated on every turn after it.
 - A new instruction block changes the cached prefix, so the first call carrying it
   misses the prompt cache. Only the turns where something was actually injected pay
   that.

packages/trigger-sdk/src/v3/ai.ts

@@ -8076,6 +8076,15 @@ function chatAgent<
                         locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
                         actionChangedHistory = true;
                       }
+
+                      /**
+                       * Reported after the partial is committed, not instead of it.
+                       * `pipeChatAndCapture` returns a stream failure rather than
+                       * throwing, so without this a mid-stream failure writes a
+                       * normal turn-complete and the truncated answer is persisted
+                       * as if it were finished — the next turn then builds on it.
+                       */
+                      if (captured.status === "error") throw captured.error;
                     } catch (error) {
                       if (
                         error instanceof Error &&

packages/trigger-sdk/test/action-stream-accumulator.test.ts

@@ -95,4 +95,78 @@ describe("a StreamTextResult returned from onAction", () => {
       await harness.close();
     }
   });
+
+  it("reports a mid-stream failure instead of committing a truncated answer as finished", async () => {
+    /**
+     * `pipeChatAndCapture` returns a stream failure as `status: "error"` rather
+     * than throwing it. Unchecked, the action commits whatever streamed, writes a
+     * normal turn-complete, and the browser just sees the stream stop — so the
+     * user reads a half-finished answer presented as complete and the next turn
+     * builds on it. The partial is still kept, as on the turn path; what changes
+     * is that the failure is surfaced alongside it.
+     */
+    let stage = 0;
+    const failsMidStream = new MockLanguageModelV3({
+      doStream: async () => ({
+        stream: new ReadableStream<LanguageModelV3StreamPart>({
+          async pull(controller) {
+            await new Promise((r) => setTimeout(r, 25));
+            if (stage === 0) {
+              controller.enqueue({ type: "text-start", id: "t1" });
+              stage++;
+              return;
+            }
+            if (stage === 1) {
+              controller.enqueue({ type: "text-delta", id: "t1", delta: "half an answer" });
+              stage++;
+              return;
+            }
+            controller.error(new Error("provider exploded mid-stream"));
+          },
+        }),
+      }),
+    });
+
+    const agent = chat.agent({
+      id: "action-stream-error",
+      actionSchema: z.discriminatedUnion("type", [z.object({ type: z.literal("regenerate") })]),
+      onAction: async ({ action, messages }) => {
+        if (action.type !== "regenerate") return;
+        chat.history.slice(0, -1);
+        return streamText({ model: failsMidStream, messages });
+      },
+      run: async ({ messages, signal }) =>
+        streamText({
+          model: new MockLanguageModelV3({
+            doStream: async () => ({ stream: textStream("first answer") }),
+          }),
+          messages,
+          abortSignal: signal,
+        }),
+    });
+
+    const harness = mockChatAgent(agent, { chatId: "action-stream-error" });
+
+    try {
+      await harness.sendMessage({
+        id: "u1",
+        role: "user",
+        parts: [{ type: "text", text: "ask" }],
+      });
+      await new Promise((r) => setTimeout(r, 40));
+
+      await harness.sendAction({ type: "regenerate" }).catch(() => {});
+      await new Promise((r) => setTimeout(r, 300));
+
+      const errors = (harness.allRawChunks as { type?: string }[]).filter(
+        (c) => c.type === "error"
+      );
+      expect(errors.length).toBeGreaterThan(0);
+
+      // The partial is still kept rather than discarded.
+      expect(harness.getSnapshot()?.messages.map(textOf).at(-1)).toContain("half an answer");
+    } finally {
+      await harness.close();
+    }
+  });
 });