docs(ai-chat): slim-wire HITL continuations + field-level merge contract by ericallam · Pull Request #3721 · triggerdotdev/trigger.dev

ericallam · 2026-05-23T09:02:41Z

Summary

Updates the AI chat docs to match the slim-wire + field-level merge behavior shipped in #3719 and the precise .in/append cap + CORS-readable 413 shipped in #3720. No behavior changes here — code is correct in main; the docs were lagging on three patterns customers copy out of the page.

What changed

hydrateMessages examples upsert by id (in lifecycle-hooks.mdx, patterns/database-persistence.mdx, and patterns/persistence-and-replay.mdx). The previous stored.push(newMsg) pattern duplicated the assistant id on HITL continuations and caused the LLM to receive a tool call with no arguments. The new examples include the rationale inline.
onValidateMessages example filters to user messages (lifecycle-hooks.mdx). The previous example called validateUIMessages({ messages, tools }) directly, which now throws on HITL slim wires (the AI SDK schema requires input on resolved tool parts). New example shows the filter pattern, with a Warning callout explaining why.
Merge contract description updated (lifecycle-hooks.mdx). The old wording said incoming messages are "auto-merged" / "replaced"; the new description explains the actual field-level overlay (state advances only).
Approval-responded wire example slimmed (client-protocol.mdx). Shows the minimum shape the agent reads — state + approval (or output / errorText for HITL). Notes that the built-in transports ship this slim shape by default and that fuller shapes are still accepted.
/in/append 413 row and FAQ updated (client-protocol.mdx, patterns/trusted-edge-signals.mdx). Reflects the new precise S2 cap and the CORS-readable 413.
New changelog entry at the top of changelog.mdx covering all of the above.

The historical ## 512 KiB ceiling removed entry further down the changelog is left as-is (it's a snapshot of the prior transition), and the v4.5 upgrade-guide section is skipped — the merge contract is backwards compatible.

Test plan

Mintlify dev preview renders cleanly with no broken anchors
Linked references resolve (/ai-chat/lifecycle-hooks#hydratemessages, /ai-chat/lifecycle-hooks#onvalidatemessages, /ai-chat/patterns/database-persistence#alternative-hydratemessages, /ai-chat/client-protocol#step-3-send-messages-stops-and-actions, /ai-chat/patterns/large-payloads)

mintlify · 2026-05-23T09:02:44Z

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

Project	Status	Preview	Updated (UTC)
trigger	🟢 Ready	View Preview	May 23, 2026, 9:04 AM

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

changeset-bot · 2026-05-23T09:02:45Z

⚠️ No Changeset found

Latest commit: 7aeef27

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-05-23T09:02:55Z

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: 70807dad-7b80-4a86-9584-a8cb78f00bbb

📥 Commits

Reviewing files that changed from the base of the PR and between 12d40ac and 7aeef27.

📒 Files selected for processing (4)

docs/ai-chat/changelog.mdx
docs/ai-chat/lifecycle-hooks.mdx
docs/ai-chat/patterns/database-persistence.mdx
docs/ai-chat/patterns/persistence-and-replay.mdx

✅ Files skipped from review due to trivial changes (2)

docs/ai-chat/changelog.mdx
docs/ai-chat/lifecycle-hooks.mdx

📜 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). (1)

GitHub Check: Analyze (javascript-typescript)

🧰 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
docs/ai-chat/patterns/database-persistence.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
docs/ai-chat/patterns/database-persistence.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
docs/ai-chat/patterns/database-persistence.mdx

🔇 Additional comments (2)

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

181-195: LGTM!

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

134-146: LGTM!

Walkthrough

This PR updates ai-chat documentation for the May 23, 2026 (4.5.0-rc.2) release. It documents HITL continuation behavior where assistant tool-part payloads are slim (only resolved tool-part state plus minimal identity), the runtime overlays tool-state advances onto hydrated messages by id, and hydrateMessages examples switch to an id-based upsert (upsertIncomingMessage) to avoid duplicate assistant rows. It tightens tool-approval payload examples to a single slim message shape. It also clarifies /in/append sizing: documents a 1 MiB body ceiling (with S2 per-record metering guidance) and that 413 responses include CORS headers.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main documentation changes: slim-wire HITL continuations and field-level merge contract updates.
Description check	✅ Passed	The description thoroughly documents all changes, provides clear context linking to shipped behavior (`#3719`, `#3720`), and includes a comprehensive test plan with specific anchor references.
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/chat-slim-wire-merge

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

…amples

devin-ai-integration

Devin Review found 1 potential issue.

View 1 additional finding in Devin Review.

docs(ai-chat): slim-wire HITL continuations + field-level merge contract

12d40ac

mintlify Bot deployed to staging - docs May 23, 2026 09:04 View deployment

docs(ai-chat): use upsertIncomingMessage helper in hydrateMessages ex…

7aeef27

…amples

mintlify Bot deployed to staging - docs May 23, 2026 09:22 View deployment

ericallam marked this pull request as ready for review May 23, 2026 15:30

devin-ai-integration Bot reviewed May 23, 2026

View reviewed changes

Comment thread docs/ai-chat/changelog.mdx

samejr approved these changes May 23, 2026

View reviewed changes

ericallam merged commit 9f64bf4 into main May 23, 2026
20 checks passed

ericallam deleted the docs/chat-slim-wire-merge branch May 23, 2026 16:27

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(ai-chat): slim-wire HITL continuations + field-level merge contract#3721

docs(ai-chat): slim-wire HITL continuations + field-level merge contract#3721
ericallam merged 2 commits into
mainfrom
docs/chat-slim-wire-merge

ericallam commented May 23, 2026

Uh oh!

mintlify Bot commented May 23, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented May 23, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented May 23, 2026 •

edited

Loading

Uh oh!

devin-ai-integration Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

ericallam commented May 23, 2026

Summary

What changed

Test plan

Uh oh!

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

Uh oh!

Uh oh!

changeset-bot Bot commented May 23, 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 May 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Estimated code review effort

Uh oh!

devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mintlify Bot commented May 23, 2026 •

edited

Loading

changeset-bot Bot commented May 23, 2026 •

edited

Loading

coderabbitai Bot commented May 23, 2026 •

edited

Loading