Skip to content

Commit e6618cf

Browse files
committed
docs(ai-chat): style-guide pass on the injection and action sections
Drops the banned trivializing words, replaces future tense and "there is" throat-clearing, and removes a "two things" lead-in that sat above three bullets. Merges the two bullets that stated the same prompt-cache fact, and stops claiming the injected block is appended as an array when it is merged into a single instruction.
1 parent 02e0a70 commit e6618cf

2 files changed

Lines changed: 8 additions & 15 deletions

File tree

docs/ai-chat/actions.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -98,9 +98,9 @@ onAction: async ({ action, messages }) => {
9898
},
9999
```
100100

101-
Mirror each mutation in your store, not just the additions. A `chat.history` mutation is invisible to your database, so a regenerate is a delete *and* an insert — saving the new answer without removing the old one leaves both in the canonical transcript, and the next hydration returns the two of them. (An append-only or branching store is the exception: there you write a new version and resolve the head on read.)
101+
Mirror each mutation in your store, not only the additions. A `chat.history` mutation is invisible to your database, so a regenerate is a delete *and* an insert — saving the new answer without removing the old one leaves both in the canonical transcript, and the next hydration returns the two of them. (An append-only or branching store is the exception: there you write a new version and resolve the head on read.)
102102

103-
Returning the stream instead of piping it yourself still works and still reaches the browser — you just have no message to store, so the next run will not know about it.
103+
Returning the stream instead of piping it yourself still works and still reaches the browser — but you have no message to store, so the next run does not know about it.
104104

105105
## Gating actions on HITL state
106106

docs/ai-chat/background-injection.mdx

Lines changed: 6 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -199,14 +199,13 @@ treats the content as trustworthy.
199199

200200
**`role: "system"` goes to the instructions lane.** The block is appended to the
201201
system instructions for subsequent inference calls, so it carries the same standing
202-
as your system prompt. This is the lane for context the agent should simply believe:
202+
as your system prompt. This is the lane for context the agent should believe:
203203
entitlements, plan changes, operational notices.
204204

205205
It has to work this way. On AI SDK 7 a system message inside `messages` is rejected
206206
for every provider — `standardizePrompt` throws before any provider is called, and
207-
its own advice is to use the instructions option. `Instructions` accepts
208-
`Array<SystemModelMessage>`, so the injected block is appended there rather than
209-
smuggled into the transcript.
207+
its own advice is to use the instructions option, so the injected block goes there
208+
rather than into the transcript.
210209

211210
<Warning>
212211
The instructions lane is delivered by `chat.toStreamTextOptions()`, because that
@@ -217,20 +216,14 @@ smuggled into the transcript.
217216
`messages` either way.
218217
</Warning>
219218

220-
Two things worth knowing:
221-
222219
- An injection applies to the next inference call only. The lane is drained once
223220
applied, so a block injected in `onTurnComplete` shapes the following turn and is
224221
not repeated on every turn after it.
225-
- A new instruction block changes the cached prefix, so the first call carrying it
226-
misses the prompt cache. Only the turns where something was actually injected pay
227-
that.
228222
- The injected text is merged into a single instruction rather than added as a
229223
second block, because AI SDK 5 rejects an array of system blocks while accepting
230-
one structured block. That means a cached system prompt loses its cache entry for
231-
as long as an injection is live — the prefix changed, so there is nothing to hit.
232-
If you rely on prompt caching, inject sparingly and prefer facts that go stale, so
233-
the injection clears.
224+
one structured block. Merging changes the cached prefix, so a cached system prompt
225+
gets no cache hit for as long as an injection is live. If you rely on prompt
226+
caching, inject sparingly and prefer facts that go stale, so the injection clears.
234227

235228
**Any other role joins the conversation, and is untrusted by construction.** A
236229
message injected as `user` is indistinguishable from something the user typed, and a

0 commit comments

Comments
 (0)