feat(sdk): chat.headStart handover for customAgent and createSession#3963
Merged
ericallam merged 2 commits intoJun 16, 2026
Conversation
chat.headStart previously handed the warm step-1 response over only to chat.agent. Now chat.customAgent (via conversation.consumeHandover) and chat.createSession (via turn.handover) consume it too, and a resumed tool round merges into the handed-over assistant instead of throwing or duplicating it. Also adds triggerConfig support to chat.headStart() and chat.openSession() so the handover-prepare run inherits tags, queue, and other session run options. Co-authored-by: saasjesus <armin@chatarmin.com>
🦋 Changeset detectedLatest commit: 32f0536 The changes in this PR will be included in the next version bump. This PR includes changesets to release 25 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
4 tasks
Contributor
|
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 as they are similar to previous 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). (32)
WalkthroughThis PR extends 🚥 Pre-merge checks | ✅ 3 | ❌ 2❌ Failed checks (1 warning, 1 inconclusive)
✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 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 |
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
@trigger.dev/build
trigger.dev
@trigger.dev/core
@trigger.dev/python
@trigger.dev/react-hooks
@trigger.dev/redis-worker
@trigger.dev/rsc
@trigger.dev/schema-to-json
@trigger.dev/sdk
commit: |
0ski
approved these changes
Jun 16, 2026
ericallam
added a commit
that referenced
this pull request
Jun 16, 2026
…3964) ## Summary `chat.headStart` now works with the `chat.customAgent` and `chat.createSession` backends (not just `chat.agent`), and takes a `triggerConfig` option. These docs cover both. The Fast starts guide gets a "Handover with custom agents" section showing how each backend consumes the handover (`consumeHandover` returning `{ isFinal, skipped }` for custom agents, `turn.handover` for createSession), including threading `originalMessages` so a resumed tool round merges into the handed-over assistant. The `chat.headStart` API section documents `triggerConfig` (tags, queue, machine, and the rest) on the auto-triggered run. The reference picks up `ChatTurn.handover`, `turn.complete()` with no source, `chat.waitForHandover`, and a new `HeadStartHandlerOptions` table. Docs for the SDK changes in [#3963](#3963).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
chat.headStart(the warm step-1 fast path) previously handed its response over only tochat.agent. This extends handover to the other two backends:chat.customAgentconsumes it withconversation.consumeHandover({ payload })on turn 0, andchat.createSessionsurfaces it asturn.handover(callturn.complete()with no source to finalize a pure-text handover). The low-levelchat.waitForHandover()andaccumulator.applyHandover()are exported for hand-rolled loops.It also adds
triggerConfigtochat.headStart()andchat.openSession(), so the auto-triggered handover-prepare run inherits tags, queue, machine, and the other session run options the same waychat.createStartSessionAction()does. Thechat:{chatId}tag is prepended automatically. Because the session is created once on the first head-start turn (idempotent on the chat id), this is the only place those options can be set for a head-start chat's lifetime.Fix: tool-call resume
When the warm step-1 hands over a pending tool call (rather than pure text), the agent loop resumes that tool round. For it to merge cleanly the pipe threads the spliced partial as
originalMessages, so the resumed tool-output chunk attaches to the handed-over tool-call instead of throwingNo tool invocation found.MessageAccumulator.addResponsenow also dedups by id (replace-in-place), so the persisted history doesn't carry a duplicate assistant message when the resumed response reuses the partial's id.Incorporates the
triggerConfigwork from #3933 by @saasjesus, withcreateStartSessionActionextended to also forwardmaxDuration,region, andlockToVersionso the two session entry points stay consistent.Verified end-to-end against a local environment: handover (pure-text and tool-call) on both new backends, a
chat.agentregression pass, andtriggerConfigtags and queue landing on the run.