docs(ai-chat): head-start persistence contract and a clearer sessions page#3908
Conversation
Adds a persistence section to the fast starts page covering the stable assistant messageId across the handover, onTurnComplete as the canonical persistence point, reasoning parts surviving into durable history, and how Head Start composes with hydrateMessages. Switches the hydrate hook examples to upsert their conversation row, since head-start first turns run without a preload to create it.
The opening defined a Session as a durable, task-bound, bi-directional I/O channel pair, which reads as jargon and omits run orchestration entirely. The page now leads with the plain mental model (a pair of durable streams: input carries user messages, output carries everything the agent produces) plus the Session's role orchestrating runs, adds a diagram, a minimal runnable example, and a Sessions-and-runs section covering the one-session-many-runs lifecycle.
|
|
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)
📜 Recent review details🧰 Additional context used📓 Path-based instructions (1)docs/**/*.mdx📄 CodeRabbit inference engine (docs/CLAUDE.md)
Files:
🧠 Learnings (2)📚 Learning: 2026-03-10T12:44:14.176ZApplied to files:
📚 Learning: 2026-04-30T20:30:29.458ZApplied to files:
🔇 Additional comments (1)
WalkthroughThis PR updates AI-chat docs: it documents hydrateMessages firing after head-start handover (receiving first-turn history as incomingMessages), adds head-start persistence guarantees and a warning that hydrate hooks must upsert, and changes hydrateMessages examples to use db.chat.upsert. Separately, Sessions docs are rewritten to define durable .in/.out streams, include a session message-flow diagram, minimal code examples, and run lifecycle details. 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
ESLint install timed out. The project may have too many dependencies for the sandbox. 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. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
The head-start addition contradicted the absolute 0-or-1-length wording in the same cell. Now reads as usually 0-or-1 with the head-start first turn called out as the exception.
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
The Note further down the hydrateMessages section repeated the absolute 0-or-1-length wording the previous commit softened in the field table.
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
…xample Same fragile update-against-a-possibly-missing-row pattern the other hydrate examples already moved away from.
2 participants
Summary
Two documentation improvements for the AI chat docs.
Head-start persistence contract. The fast starts page now documents what your hooks can rely on across a head-start handover: one stable assistant
messageIdfor the whole turn,onTurnCompleteas the canonical persistence point, reasoning parts flowing into durable history, and how Head Start composes withhydrateMessages(the first-turn history arrives asincomingMessages, and the runtime splices the warm partial onto the hydrated chain, deduplicated by id). The hydrate examples on the lifecycle hooks and database persistence pages now upsert their conversation row, since head-start first turns run without a preload to create it.Sessions page. The page opened with "a durable, task-bound, bi-directional I/O channel pair", which reads as jargon and omitted run orchestration entirely. It now leads with the plain mental model (a pair of durable streams: input carries user messages, output carries everything the agent produces) plus the Session's role orchestrating runs, a diagram, a minimal runnable example, and a section on the one-session-many-runs lifecycle.
Documents behavior shipping in #3907.