docs(ai-chat): correct chat.agent reference drift#3892
Conversation
Fix transport.preload signature (no per-call idle option), clarify that onValidateMessages only fires on turns carrying incoming messages, soften the turn-complete token-refresh wording since the header is optional, document the onTurnComplete error field and finishReason, and correct the idle-timeout default to 30 seconds.
|
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
📜 Recent review details⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
WalkthroughThis PR updates documentation across five AI chat API guides to reflect current implementation behavior. Changes clarify that turn completion events include an 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
The built-in clients generate a high-entropy id per send (UUID in the browser, full-length nanoid server-side), not a short id.
| | `usage` | `LanguageModelUsage \| undefined` | Token usage for this turn | | ||
| | `totalUsage` | `LanguageModelUsage` | Cumulative token usage across all turns | | ||
| | `finishReason` | `FinishReason \| undefined` | Why the LLM stopped (`"stop"`, `"tool-calls"`, `"error"`, …) | | ||
| | `error` | `unknown` | Set when the turn threw; `responseMessage` is then undefined or partial | |
There was a problem hiding this comment.
🟡 Documentation references non-existent error field on TurnCompleteEvent
The reference docs add error: unknown as a field of TurnCompleteEvent, but this field does not exist in the actual TypeScript type definition at packages/trigger-sdk/src/v3/ai.ts:4175-4243. The type ends with finishReason?: FinishReason and has no error property. Additionally, when a turn throws (the catch block at packages/trigger-sdk/src/v3/ai.ts:7527), onTurnComplete is not invoked at all — the error handler writes an error chunk to the stream and waits for the next message, skipping the turn-complete hooks entirely. Users following this documentation will destructure a field that is always undefined.
Prompt for agents
The TurnCompleteEvent type in packages/trigger-sdk/src/v3/ai.ts:4175-4243 does not have an `error` field. Either (a) remove the `error` row from the reference table and the corresponding documentation in error-handling.mdx, or (b) if this is intended new behavior, add the `error` field to the TurnCompleteEvent type and update the turn error handler (ai.ts:7527-7597) to invoke onTurnComplete with the error before waiting for the next message. The same issue appears in docs/ai-chat/error-handling.mdx lines 134, 137, and 143-144.
Was this helpful? React with 👍 or 👎 to provide feedback.
| onTurnComplete: async ({ chatId, uiMessages, responseMessage, stopped, error }) => { | ||
| // Persist the messages regardless of error state | ||
| await db.chat.update({ | ||
| where: { id: chatId }, | ||
| data: { | ||
| messages: uiMessages, | ||
| // Mark the chat as errored if no response message | ||
| lastTurnStatus: responseMessage ? "ok" : stopped ? "stopped" : "errored", | ||
| // `error` is set when the turn threw | ||
| lastTurnStatus: error ? "errored" : stopped ? "stopped" : "ok", |
There was a problem hiding this comment.
🟡 Error-handling doc example destructures non-existent error field from onTurnComplete event
The updated code example destructures error from the onTurnComplete callback and uses it to determine lastTurnStatus. However, TurnCompleteEvent (defined at packages/trigger-sdk/src/v3/ai.ts:4175-4243) has no error field — the destructured value will always be undefined, so lastTurnStatus will never be "errored". The previous code (responseMessage ? "ok" : stopped ? "stopped" : "errored") was at least a heuristic that worked; the new code is strictly broken for detecting errors. The accompanying prose at line 134 ("error carries the thrown value") is also incorrect per the current codebase — onTurnComplete is not called on errored turns at all (packages/trigger-sdk/src/v3/ai.ts:7527-7597).
Prompt for agents
The onTurnComplete code example destructures `error` from the event and uses `error ? "errored" : ...` to set lastTurnStatus. But TurnCompleteEvent (packages/trigger-sdk/src/v3/ai.ts:4175-4243) has no `error` field, and onTurnComplete is not called on errored turns (see the catch block at ai.ts:7527). Either revert to the previous heuristic (`responseMessage ? "ok" : stopped ? "stopped" : "errored"`), or first add the `error` field to TurnCompleteEvent in the SDK and update the turn error handler to call onTurnComplete with the error. Also fix the prose at line 134 which claims `error` carries the thrown value.
Was this helpful? React with 👍 or 👎 to provide feedback.
| `onTurnComplete` fires after every turn — successful **or** errored. On an errored turn `responseMessage` is undefined or partial and `error` carries the thrown value (with `finishReason` set to `"error"`). Use this to mark the turn as failed: | ||
|
|
||
| ```ts | ||
| onTurnComplete: async ({ chatId, uiMessages, responseMessage, stopped }) => { | ||
| onTurnComplete: async ({ chatId, uiMessages, responseMessage, stopped, error }) => { | ||
| // Persist the messages regardless of error state | ||
| await db.chat.update({ | ||
| where: { id: chatId }, | ||
| data: { | ||
| messages: uiMessages, | ||
| // Mark the chat as errored if no response message | ||
| lastTurnStatus: responseMessage ? "ok" : stopped ? "stopped" : "errored", | ||
| // `error` is set when the turn threw | ||
| lastTurnStatus: error ? "errored" : stopped ? "stopped" : "ok", |
There was a problem hiding this comment.
🚩 Documentation may be pre-documenting a planned error field on TurnCompleteEvent
The error field additions across reference.mdx and error-handling.mdx could be intentional documentation written ahead of the corresponding SDK code changes (a common pattern when docs and code PRs are split). If so, this PR should either be merged after the SDK PR that adds the error field, or the two should be coordinated. Currently, the SDK at packages/trigger-sdk/src/v3/ai.ts:4175-4243 does not have this field, and the turn error handler at line 7527 does not invoke onTurnComplete on errors.
Was this helpful? React with 👍 or 👎 to provide feedback.
Summary
Accuracy fixes across the AI chat docs: drop the non-existent per-call option from
transport.preload, clarify thatonValidateMessagesonly fires on turns carrying incoming messages, soften the turn-complete token-refresh wording (the header is optional), document the newonTurnCompleteerrorfield andfinishReason, and correct the idle-timeout default to 30 seconds.