fix(chat): consume injected instructions per turn, not per options build

Draining the lane on read handed the injection to whichever
chat.toStreamTextOptions() call ran first and dropped it from the rest. A
run() that builds options twice, a classifier pass and then the answer, sent
the instruction to nobody if it passed the second one to streamText, with no
error anywhere. Consumption is now keyed on the turn, so every build in the
turn carries the same instructions and the turn after it carries none. A
hand-rolled loop with no turn context still drains on read.

Author: ericallam

.changeset/inject-system-to-instructions.md

@@ -4,4 +4,4 @@
 
 `chat.inject()` with `role: "system"` now works. It previously put the system message into the conversation, which AI SDK 7 rejects for every provider: the next turn died with a generic "An error occurred." and persisted an empty assistant message, so the agent looked like it had stopped answering. System-role context is now appended to the model's instructions, which is also the only way to inject context the agent treats as trusted.
 
-Two things to know. Instructions are delivered by `chat.toStreamTextOptions()`, so a `run()` that calls `streamText` without spreading it does not receive a system-role injection. The conversational lane has no such requirement. And an injection applies to the next inference call only, rather than repeating on every turn that follows it.
+Two things to know. Instructions are delivered by `chat.toStreamTextOptions()`, so a `run()` that calls `streamText` without spreading it does not receive a system-role injection. The conversational lane has no such requirement. And an injection applies to the next turn only, rather than repeating on every turn that follows it. Every inference call in that turn sees it, so a `run()` that builds options more than once gets the same instructions each time.

docs/ai-chat/background-injection.mdx

@@ -216,9 +216,11 @@ rather than into the transcript.
   `messages` either way.
 </Warning>
 
-- 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.
+- An injection applies to the next turn only. A block injected in `onTurnComplete`
+  shapes the following turn and is cleared after it, so it is not repeated on every
+  turn from then on. Within that turn it is consumed once rather than once per read,
+  so a `run()` that builds options more than once sees the same instructions in
+  every build.
 - The injected text is merged into a single instruction rather than added as a
   second block, because AI SDK 5 rejects an array of system blocks while accepting
   one structured block. Merging changes the cached prefix, so a cached system prompt

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

@@ -2712,6 +2712,10 @@ const chatBackgroundQueueKey = locals.create<ModelMessage[]>("chat.backgroundQue
 const chatInjectedInstructionsKey = locals.create<SystemModelMessage[]>(
   "chat.injectedInstructions"
 );
+/** The turn that consumed the instructions lane, so a second read in the same turn still sees it. */
+const chatInstructionsConsumedTurnKey = locals.create<number | undefined>(
+  "chat.injectedInstructionsConsumedTurn"
+);
 
 /**
  * Run-scoped pipe counter. Stored in locals so concurrent runs in the
@@ -4732,8 +4736,28 @@ function toStreamTextOptions(options?: ToStreamTextOptionsOptions): Record<strin
    */
   const injectedInstructions = locals.get(chatInjectedInstructionsKey);
   if (injectedInstructions && injectedInstructions.length > 0) {
-    const injectedText = injectedInstructions
-      .splice(0)
+    /**
+     * Consumed once per turn, not once per read. A `run()` that builds options
+     * twice, a cheap classifier pass and then the answer, has to see the
+     * injection in both: draining on read hands it to whichever call ran first
+     * and drops it from the rest without saying so. Outside a turn there is no
+     * turn to scope that to, so the lane drains on read there instead.
+     */
+    const currentTurn = locals.get(chatTurnContextKey)?.turn;
+    const consumedTurn = locals.get(chatInstructionsConsumedTurnKey);
+
+    let blocks: SystemModelMessage[];
+    if (currentTurn === undefined) {
+      blocks = injectedInstructions.splice(0);
+    } else if (consumedTurn !== undefined && consumedTurn !== currentTurn) {
+      injectedInstructions.length = 0;
+      blocks = [];
+    } else {
+      locals.set(chatInstructionsConsumedTurnKey, currentTurn);
+      blocks = injectedInstructions;
+    }
+
+    const injectedText = blocks
       .map((block) => (typeof block.content === "string" ? block.content : ""))
       .filter(Boolean)
       .join("\n\n");

packages/trigger-sdk/test/inject-system-instructions.test.ts

@@ -232,4 +232,61 @@ describe("chat.inject with a system role", () => {
       await harness.close();
     }
   });
+
+  it("carries the injection into every options build in the turn, not only the first", async () => {
+    /**
+     * A `run()` that builds options twice, a classifier pass and then the
+     * answer, has to see the injection in both. Consuming on read hands it to
+     * whichever call ran first and drops it from the rest, silently.
+     */
+    const model = new MockLanguageModelV3({
+      doStream: async () => ({ stream: textStream("ok") }),
+    });
+
+    const seen: { first: boolean; second: boolean }[] = [];
+    let injectedOnce = false;
+
+    const agent = chat.agent({
+      id: "inject-system-two-builds",
+      onTurnComplete: async () => {
+        if (injectedOnce) return;
+        injectedOnce = true;
+        chat.inject([{ role: "system", content: "SENTINEL-BOTH-BUILDS" }]);
+      },
+      run: async ({ messages, signal }) => {
+        const first = chat.toStreamTextOptions();
+        const second = chat.toStreamTextOptions();
+        const has = (o: { system?: unknown }) =>
+          JSON.stringify(o.system ?? null).includes("SENTINEL-BOTH-BUILDS");
+        seen.push({ first: has(first), second: has(second) });
+        return streamText({ ...second, model, messages, abortSignal: signal });
+      },
+    });
+
+    const harness = mockChatAgent(agent, { chatId: "inject-system-two-builds" });
+
+    try {
+      await harness.sendMessage({ id: "u1", role: "user", parts: [{ type: "text", text: "one" }] });
+      await new Promise((r) => setTimeout(r, 40));
+
+      await harness.sendMessage({ id: "u2", role: "user", parts: [{ type: "text", text: "two" }] });
+      await new Promise((r) => setTimeout(r, 40));
+
+      await harness.sendMessage({
+        id: "u3",
+        role: "user",
+        parts: [{ type: "text", text: "three" }],
+      });
+      await new Promise((r) => setTimeout(r, 40));
+
+      // Turn 1 predates the injection, turn 2 carries it in both builds, turn 3 is clear again.
+      expect(seen).toEqual([
+        { first: false, second: false },
+        { first: true, second: true },
+        { first: false, second: false },
+      ]);
+    } finally {
+      await harness.close();
+    }
+  });
 });