docs(ai-chat): head-start persistence contract and a clearer sessions page by ericallam · Pull Request #3908 · triggerdotdev/trigger.dev

ericallam · 2026-06-11T15:51:40Z

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 messageId for the whole turn, onTurnComplete as the canonical persistence point, reasoning parts flowing into durable history, and how Head Start composes with hydrateMessages (the first-turn history arrives as incomingMessages, 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.

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.

changeset-bot · 2026-06-11T15:51:46Z

⚠️ No Changeset found

Latest commit: 864711c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

coderabbitai · 2026-06-11T15:51:59Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: d11b6ce2-7cc6-405c-b3be-42ffd095fee5

📥 Commits

Reviewing files that changed from the base of the PR and between d89c04d and 864711c.

📒 Files selected for processing (1)

docs/ai-chat/patterns/persistence-and-replay.mdx

📜 Recent review details

🧰 Additional context used

📓 Path-based instructions (1)

docs/**/*.mdx

📄 CodeRabbit inference engine (docs/CLAUDE.md)

docs/**/*.mdx: MDX documentation pages must include frontmatter with title (required), description (required), and sidebarTitle (optional) in YAML format
Use Mintlify components for structured content: , , , , , , /, /
Always import from @trigger.dev/sdk in code examples (never from @trigger.dev/sdk/v3)
Code examples must be complete and runnable where possible
Use language tags in code fences: typescript, bash, json

Files:

docs/ai-chat/patterns/persistence-and-replay.mdx

🧠 Learnings (2)

📚 Learning: 2026-03-10T12:44:14.176Z

Learnt from: nicktrn
Repo: triggerdotdev/trigger.dev PR: 3200
File: docs/config/config-file.mdx:353-368
Timestamp: 2026-03-10T12:44:14.176Z
Learning: In the trigger.dev repo, docs PRs are often companions to implementation PRs. When reviewing docs PRs (MDX files under docs/), check the PR description for any companion/related PR references and verify that the documented features exist in those companion PRs before flagging missing implementations. This ensures docs stay in sync with code changes across related PRs.

Applied to files:

docs/ai-chat/patterns/persistence-and-replay.mdx

📚 Learning: 2026-04-30T20:30:29.458Z

Learnt from: ericallam
Repo: triggerdotdev/trigger.dev PR: 3226
File: docs/ai-chat/quick-start.mdx:13-13
Timestamp: 2026-04-30T20:30:29.458Z
Learning: In this repo’s documentation MDX files (`docs/**/*.mdx`), use `ts` and `tsx` (not `typescript`) as the code-fence language tags for TypeScript/TSX snippets. Do not flag `ts`/`tsx` code-fence language tags as incorrect in any docs MDX file, since this is the site-wide Mintlify-compatible convention.

Applied to files:

docs/ai-chat/patterns/persistence-and-replay.mdx

🔇 Additional comments (1)

docs/ai-chat/patterns/persistence-and-replay.mdx (1)

145-151: LGTM!

Walkthrough

This 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)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The description covers the two key improvements with sufficient detail, but does not follow the repository's pull request template structure (missing checklist, testing section, and changelog sections).	While the content is substantive and clear, consider using the standard template with sections for Testing, Changelog, and the contribution checklist to maintain consistency with repository conventions.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the two main documentation improvements: head-start persistence contract and sessions page clarity.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/headstart-persistence-contract

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

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

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.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

mintlify · 2026-06-11T15:56:00Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
trigger	🟢 Ready	View Preview	Jun 11, 2026, 3:59 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

devin-ai-integration

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

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.

The Note further down the hydrateMessages section repeated the absolute 0-or-1-length wording the previous commit softened in the field table.

…xample Same fragile update-against-a-possibly-missing-row pattern the other hydrate examples already moved away from.

ericallam added 2 commits June 11, 2026 16:11

mintlify Bot deployed to staging - docs June 11, 2026 15:59 View deployment

ericallam marked this pull request as ready for review June 11, 2026 16:01

This comment was marked as resolved.

Sign in to view

devin-ai-integration Bot reviewed Jun 11, 2026

View reviewed changes

docs(ai-chat): soften the incomingMessages cardinality claim

b80d6c4

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.

This comment was marked as resolved.

Sign in to view

docs(ai-chat): fix the second incomingMessages cardinality claim

d89c04d

The Note further down the hydrateMessages section repeated the absolute 0-or-1-length wording the previous commit softened in the field table.

mintlify Bot deployed to staging - docs June 11, 2026 16:45 View deployment

This comment was marked as resolved.

Sign in to view

mintlify Bot deployed to staging - docs June 11, 2026 16:57 View deployment

docs(ai-chat): upsert the hydrate row in the persistence-and-replay e…

864711c

…xample Same fragile update-against-a-possibly-missing-row pattern the other hydrate examples already moved away from.

mintlify Bot deployed to staging - docs June 11, 2026 17:46 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(ai-chat): head-start persistence contract and a clearer sessions page#3908

docs(ai-chat): head-start persistence contract and a clearer sessions page#3908
ericallam wants to merge 5 commits into
mainfrom
docs/headstart-persistence-contract

ericallam commented Jun 11, 2026

Uh oh!

changeset-bot Bot commented Jun 11, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jun 11, 2026 •

edited

Loading

❌ Failed checks (1 inconclusive)

Uh oh!

mintlify Bot commented Jun 11, 2026 •

edited

Loading

Uh oh!

This comment was marked as resolved.

Uh oh!

devin-ai-integration Bot left a comment

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

ericallam commented Jun 11, 2026

Summary

Uh oh!

changeset-bot Bot commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

coderabbitai Bot commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

❌ Failed checks (1 inconclusive)

Uh oh!

mintlify Bot commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

✅ Devin Review: No Issues Found

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

changeset-bot Bot commented Jun 11, 2026 •

edited

Loading

coderabbitai Bot commented Jun 11, 2026 •

edited

Loading

mintlify Bot commented Jun 11, 2026 •

edited

Loading