You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs(ai-chat): drop the remaining em dashes from the actions and injection pages
Covers the prose these pages already had, not only the new sections: the
frontmatter descriptions, code comments, the message-role table cell, the
injection-point list, and the see-also link descriptions. Each recast as a
colon, comma, parentheses, or two sentences.
Copy file name to clipboardExpand all lines: docs/ai-chat/background-injection.mdx
+13-13Lines changed: 13 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,14 +1,14 @@
1
1
---
2
2
title: "Background injection"
3
3
sidebarTitle: "Background injection"
4
-
description: "Inject context from background work into the agent's conversation — self-review, RAG augmentation, or any async analysis."
4
+
description: "Inject context from background work into the agent's conversation: self-review, RAG augmentation, or any async analysis."
5
5
---
6
6
7
7
## Overview
8
8
9
9
`chat.inject()` queues model messages for injection into the conversation. Messages are picked up at the start of the next turn or at the next `prepareStep` boundary (between tool-call steps).
10
10
11
-
This is the backend counterpart to [pending messages](/ai-chat/pending-messages) — pending messages come from the user via the frontend, while `chat.inject()` comes from your task code.
11
+
This is the backend counterpart to [pending messages](/ai-chat/pending-messages). Pending messages come from the user via the frontend, while `chat.inject()` comes from your task code.
12
12
13
13
## Basic usage
14
14
@@ -34,7 +34,7 @@ The most powerful pattern combines `chat.defer()` (background work) with `chat.i
34
34
exportconst myChat =chat.agent({
35
35
id: "my-chat",
36
36
onTurnComplete: async ({ messages }) => {
37
-
// Kick off background analysis — doesn't block the turn
37
+
// Kick off background analysis, doesn't block the turn
The self-review runs on `claude-haiku-4-5` (fast, cheap) in the background. If the user sends another message before it completes, the coaching is still injected —`chat.inject()` persists across the idle wait.
153
+
The self-review runs on `claude-haiku-4-5` (fast, cheap) in the background. If the user sends another message before it completes, the coaching is still injected, because`chat.inject()` persists across the idle wait.
154
154
155
155
## Other use cases
156
156
@@ -161,13 +161,13 @@ The self-review runs on `claude-haiku-4-5` (fast, cheap) in the background. If t
161
161
162
162
## `chat.defer` standalone
163
163
164
-
`chat.defer()` is also useful on its own, without `chat.inject()`. Any work whose timing has no resume implication — analytics, audit logs, search-index writes, cache warming — can run in parallel with streaming instead of in the critical path. All deferred promises are awaited (with a 5s timeout) before `onTurnComplete` fires.
164
+
`chat.defer()` is also useful on its own, without `chat.inject()`. Any work whose timing has no resume implication (analytics, audit logs, search-index writes, cache warming) can run in parallel with streaming instead of in the critical path. All deferred promises are awaited (with a 5s timeout) before `onTurnComplete` fires.
165
165
166
166
```ts
167
167
exportconst myChat =chat.agent({
168
168
id: "my-chat",
169
169
onTurnStart: async ({ chatId, runId }) => {
170
-
// Analytics — fire-and-forget, irrelevant to resume.
170
+
// Analytics: fire-and-forget, irrelevant to resume.
`chat.defer()` can be called from anywhere during a turn — hooks, `run()`, or nested helpers. All deferred promises are collected and awaited together before `onTurnComplete`.
179
+
`chat.defer()` can be called from anywhere during a turn: hooks, `run()`, or nested helpers. All deferred promises are collected and awaited together before `onTurnComplete`.
180
180
181
181
<Warning>
182
-
**Don't use `chat.defer()` for the message-history write in `onTurnStart`.** That write must land *before* the model starts streaming, otherwise a mid-stream page refresh will read `[]` from your DB and lose the user's message from the rendered conversation. See [Database persistence —`onTurnStart`](/ai-chat/patterns/database-persistence#onturnstart). Reserve `chat.defer` for writes whose timing has no resume implication.
182
+
**Don't use `chat.defer()` for the message-history write in `onTurnStart`.** That write must land *before* the model starts streaming, otherwise a mid-stream page refresh will read `[]` from your DB and lose the user's message from the rendered conversation. See [Database persistence:`onTurnStart`](/ai-chat/patterns/database-persistence#onturnstart). Reserve `chat.defer` for writes whose timing has no resume implication.
|**Source**| Backend task code | Frontend user input |
190
190
|**Triggered by**| Your code (e.g. `onTurnComplete` + `chat.defer()`) | User sending a message during streaming |
191
191
|**Injection point**| Start of next turn, or next `prepareStep` boundary | Next `prepareStep` boundary only |
192
-
|**Message role**| Any —`system` becomes an instruction, others join the conversation (see below) | Typically `user`|
192
+
|**Message role**| Any.`system` becomes an instruction, others join the conversation (see below) | Typically `user`|
193
193
|**Frontend visibility**| Not visible unless you write custom `data-*` chunks | Visible via `usePendingMessages` hook |
194
194
195
195
## Two lanes: trusted and untrusted
@@ -246,7 +246,7 @@ ignores it, and may contradict it in front of the user.
246
246
chat.inject(messages: ModelMessage[]): void
247
247
```
248
248
249
-
Queue model messages for injection at the next opportunity. Messages persist across the idle wait between turns — they are not reset when a new turn starts.
249
+
Queue model messages for injection at the next opportunity. Messages persist across the idle wait between turns, and are not reset when a new turn starts.
250
250
251
251
**Parameters:**
252
252
@@ -255,9 +255,9 @@ Queue model messages for injection at the next opportunity. Messages persist acr
255
255
|`messages`|`ModelMessage[]`| Model messages to inject (from the `ai` package) |
256
256
257
257
Messages are drained (consumed) when:
258
-
1. A new turn starts — before `run()` executes
259
-
2. A `prepareStep` boundary is reached — between tool-call steps during streaming
258
+
1. A new turn starts, before `run()` executes
259
+
2. A `prepareStep` boundary is reached, between tool-call steps during streaming
260
260
261
261
<Note>
262
-
`chat.inject()` writes to an in-memory queue in the current process. It works from any code running in the same task — lifecycle hooks, deferred work, tool execute functions, etc. It does not work from subtasks or other runs.
262
+
`chat.inject()` writes to an in-memory queue in the current process. It works from any code running in the same task: lifecycle hooks, deferred work, tool execute functions, etc. It does not work from subtasks or other runs.
0 commit comments