docs(ai-chat): document HITL pause suspension and maxDuration

[ericallam]

Summary

Adds a "Duration and cost while paused" section to the human-in-the-loop page. It explains that a HITL pause (a no-execute tool waiting on addToolOutput) suspends the run and frees compute, so the human's thinking time does not count against maxDuration (which measures active CPU time and excludes suspended waitpoint time, the same as wait.for). Customers don't need to raise maxDuration or end the run to support long human waits.

This was a recurring point of confusion: readers assumed the pause holds the run open and burns the budget. Also updates the how-it-works pseudocode ("Agent suspends (compute freed)") and links wait.for and maxDuration on first mention.

[changeset-bot]

⚠️ No Changeset found

Latest commit: f3ab518

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]

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: 6b5e46d2-a9d6-4e09-906b-59322afd7b39

📥 Commits

Reviewing files that changed from the base of the PR and between ae08c9c and f3ab518.

📒 Files selected for processing (1)

• docs/ai-chat/patterns/human-in-the-loop.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/human-in-the-loop.mdx

🧠 Learnings (4)

📚 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/human-in-the-loop.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/human-in-the-loop.mdx

📚 Learning: 2026-06-16T13:14:09.440Z

Learnt from: ericallam
Repo: triggerdotdev/trigger.dev PR: 3964
File: docs/ai-chat/reference.mdx:482-482
Timestamp: 2026-06-16T13:14:09.440Z
Learning: When documenting or reviewing usage of `ChatTurn.complete(source?)` (in `packages/trigger-sdk/src/v3/ai.ts`), note that `source` is optional (`source?: UIMessageStreamable`). Calling `complete()` with no `source` is valid specifically for a final head-start handover (`handover.isFinal`), because the warm partial already contains the response. If examples or guidance omit `source`, ensure they are in this final-hand-over context so they remain correct.

Applied to files:

• docs/ai-chat/patterns/human-in-the-loop.mdx

📚 Learning: 2026-06-16T13:14:14.382Z

Learnt from: ericallam
Repo: triggerdotdev/trigger.dev PR: 3964
File: docs/ai-chat/reference.mdx:478-478
Timestamp: 2026-06-16T13:14:14.382Z
Learning: When reviewing RC-gated `ai-chat` docs under `docs/ai-chat/`, don’t immediately flag missing SDK type fields or implementation details just because the field isn’t present on the docs branch yet. Instead, find and cross-check the companion implementation PR that’s intended to land alongside the docs PR, and only report missing/incorrect fields if they are also absent in the companion SDK/type changes.

Applied to files:

• docs/ai-chat/patterns/human-in-the-loop.mdx

🔇 Additional comments (1)

docs/ai-chat/patterns/human-in-the-loop.mdx (1)

23-23: LGTM!

Also applies to: 39-46

---

Walkthrough

The documentation for the Human-in-the-Loop pattern in docs/ai-chat/patterns/human-in-the-loop.mdx is updated in two places. The "How it works" timeline entry for the paused state is revised to state that the agent suspends, compute is freed, and maxDuration does not tick while paused. A new "Duration and cost while paused" section is added, describing the idleTimeoutInSeconds warm window (default 30s), the subsequent suspension, the exclusion of user thinking time from billing and maxDuration, and the behavior when the suspend timeout is exceeded—where the next addToolOutput starts a fresh continuation from the resolved tool result.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description lacks the required checklist, testing section, and changelog section from the repository's template, though it does provide a comprehensive summary of the changes and their purpose.	Add the required checklist items, testing steps (e.g., 'Reviewed documentation for accuracy and clarity'), and a changelog entry following the template structure.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: documenting HITL pause suspension behavior and its relationship to maxDuration, which matches the primary focus of the documentation updates.
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/hitl-pause-duration-maxduration

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[devin-ai-integration]

✅ Devin Review: No Issues Found

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