Skip to content

Commit 3246d12

Browse files
committed
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.
1 parent 1f7fb5e commit 3246d12

2 files changed

Lines changed: 21 additions & 21 deletions

File tree

docs/ai-chat/actions.mdx

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: "Actions"
33
sidebarTitle: "Actions"
4-
description: "Custom commands sent from the frontend that mutate chat state without consuming a turn undo, rollback, edit, regenerate."
4+
description: "Custom commands sent from the frontend that mutate chat state without consuming a turn: undo, rollback, edit, regenerate."
55
---
66

77
## Overview
@@ -119,10 +119,10 @@ onAction: async ({ action, messages, signal }) => {
119119
## Sending actions from the frontend
120120

121121
```ts
122-
// Browser TriggerChatTransport
122+
// Browser: TriggerChatTransport
123123
const stream = await transport.sendAction(chatId, { type: "undo" });
124124

125-
// Server AgentChat
125+
// Server: AgentChat
126126
const stream = await agentChat.sendAction({ type: "rollback", targetMessageId: "msg-3" });
127127
```
128128

@@ -134,8 +134,8 @@ The action payload is validated against `actionSchema` on the backend; invalid a
134134

135135
## See also
136136

137-
- [`chat.history`](/ai-chat/backend#chat-history) the imperative API actions use to mutate state
138-
- [Sending actions from the frontend](/ai-chat/frontend#sending-actions) `transport.sendAction` ergonomics
139-
- [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages) fires before `onAction` when set
140-
- [Branching conversations](/ai-chat/patterns/branching-conversations) pairs action handlers with backend-controlled history
141-
- [Human-in-the-loop](/ai-chat/patterns/human-in-the-loop) gating fresh actions while a tool is waiting
137+
- [`chat.history`](/ai-chat/backend#chat-history): the imperative API actions use to mutate state
138+
- [Sending actions from the frontend](/ai-chat/frontend#sending-actions): `transport.sendAction` ergonomics
139+
- [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages): fires before `onAction` when set
140+
- [Branching conversations](/ai-chat/patterns/branching-conversations): pairs action handlers with backend-controlled history
141+
- [Human-in-the-loop](/ai-chat/patterns/human-in-the-loop): gating fresh actions while a tool is waiting

docs/ai-chat/background-injection.mdx

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
---
22
title: "Background injection"
33
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."
55
---
66

77
## Overview
88

99
`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).
1010

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.
1212

1313
## Basic usage
1414

@@ -34,7 +34,7 @@ The most powerful pattern combines `chat.defer()` (background work) with `chat.i
3434
export const myChat = chat.agent({
3535
id: "my-chat",
3636
onTurnComplete: async ({ messages }) => {
37-
// Kick off background analysis doesn't block the turn
37+
// Kick off background analysis, doesn't block the turn
3838
chat.defer(
3939
(async () => {
4040
const analysis = await analyzeConversation(messages);
@@ -150,7 +150,7 @@ export const myChat = chat.agent({
150150
});
151151
```
152152

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 `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.
154154

155155
## Other use cases
156156

@@ -161,13 +161,13 @@ The self-review runs on `claude-haiku-4-5` (fast, cheap) in the background. If t
161161

162162
## `chat.defer` standalone
163163

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.
165165

166166
```ts
167167
export const myChat = chat.agent({
168168
id: "my-chat",
169169
onTurnStart: async ({ chatId, runId }) => {
170-
// Analytics fire-and-forget, irrelevant to resume.
170+
// Analytics: fire-and-forget, irrelevant to resume.
171171
chat.defer(analytics.track("turn_started", { chatId, runId }));
172172
},
173173
run: async ({ messages, signal }) => {
@@ -176,10 +176,10 @@ export const myChat = chat.agent({
176176
});
177177
```
178178

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`.
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`.
180180

181181
<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.
183183
</Warning>
184184

185185
## How it differs from pending messages
@@ -189,7 +189,7 @@ export const myChat = chat.agent({
189189
| **Source** | Backend task code | Frontend user input |
190190
| **Triggered by** | Your code (e.g. `onTurnComplete` + `chat.defer()`) | User sending a message during streaming |
191191
| **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` |
193193
| **Frontend visibility** | Not visible unless you write custom `data-*` chunks | Visible via `usePendingMessages` hook |
194194

195195
## Two lanes: trusted and untrusted
@@ -246,7 +246,7 @@ ignores it, and may contradict it in front of the user.
246246
chat.inject(messages: ModelMessage[]): void
247247
```
248248

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.
250250

251251
**Parameters:**
252252

@@ -255,9 +255,9 @@ Queue model messages for injection at the next opportunity. Messages persist acr
255255
| `messages` | `ModelMessage[]` | Model messages to inject (from the `ai` package) |
256256

257257
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
260260

261261
<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.
263263
</Note>

0 commit comments

Comments
 (0)