Repository navigation
Vouch request: add triggerConfig to chat.headStart (handover-prepare tagging) #3915
Description
Why do you want to contribute?
We’re building on Trigger.dev at chatarmin.com — customer-support AI agents on the v4.5 AI chat stack (chat.agent, Sessions, Head Start).
How we use Trigger today
- chat.agent — agents-v2.browser-chat task: turn loop, hooks (onTurnStart / onTurnComplete), compaction, HITL-style flows.
- chat.headStart() — first message for setup / test / triage: step 1 streams in our Fastify API while the handover-prepare run boots in parallel.
- chat.createStartSessionAction — turn 2+ for the same chat (preload path).
- AgentChat — live ticket turns (agent_trigger) via server-side dispatch.
- We tag runs (chat:…, org:…, agentic-run:…, mode:…) on session start and live dispatch for dashboard filtering and incident debugging.
What we want to contribute
A small SDK PR: triggerConfig on HeadStartHandlerOptions (tags, queue, etc.) — same shape as createStartSessionAction. Today openHandoverSession calls createSession with only basePayload + idleTimeoutInSeconds, so handover-prepare runs aren’t tagged. That made a recent chat.handover: idle timeout painful to correlate in the Trigger dashboard (no agentic-run: filter until after handover, if ever).
Planned change: packages/trigger-sdk/src/v3/chat-server.ts + tests in chat-server.test.ts — mirror the existing createChatStartSessionAction merge logic (including auto chat:{chatId} tag prefix).
We’re on @trigger.dev/sdk@4.5.0-rc.5, happy to follow your contributing guidelines and keep the PR to this single feature.
Prior contributions or relevant experience
We are in Slack with Eric and basically flagged all the issues which are being fixed with this PR now: #3907
Happy to contribute further to trigger.dev!
Activity
ericallam commentedon Jun 12, 2026
Welcome, and thanks for the detailed writeup (and for flagging the reports that became #3907). You're approved as a contributor, and I've added you to our list in #3917, so once that lands your PRs will clear the contributor check.
You've got the gap exactly right.
openHandoverSessionis the one session-entry path that creates the session without tags, and becausecreateSessionis idempotent on(env, externalId = chatId), the head-start call on turn 0 is what fixes the session'striggerConfigfor its whole lifetime. So tagging there is the correct fix, not just a convenience: acreateStartSessionActioncall on a later turn can't retroactively tag a session head-start already created, which is exactly the "noagentic-run:filter until after handover, if ever" you're seeing.A few pointers for the PR:
createChatStartSessionAction(packages/trigger-sdk/src/v3/ai.ts): thetriggerConfigassembly that prepends the autochat:{chatId}tag and shallow-mergesbasePayload/machine/queue/maxAttempts/idleTimeoutInSeconds. Keep the head-start version consistent with that one (including how the auto chat tag counts against the tag cap) so both entry points behave identically.triggerConfig?: Partial<SessionTriggerConfig>toHeadStartHandlerOptions, thread it throughheadStartintoopenHandoverSession, and fold it into thecreateSessioncall. Heads up thatchat-server.tshas a hard bundle-isolation constraint (the route-handler bundle must stay lightweight), butSessionTriggerConfigis a type-only import so that's fine; just don't pull anything heavy in.chat-server.test.tsalready asserts on thecreateSessionrequest body (body.triggerConfig.basePayload.*), so extend that pattern to cover the merged tags / queue / etc.pnpm run changeset:add, patch level.Two process notes from CONTRIBUTING.md: please open the PR as a draft first (external non-draft PRs get auto-closed, so you can clear CodeRabbit and CI before review), and keep it to this single feature.
Looking forward to the PR!
chore: vouch saasjesus as a contributor (#3917)
saasjesus commentedon Jun 12, 2026
Thanks @ericallam, created the new draft PR: #3933
matt-aitken commentedon Oct 7, 2026
We have a new Vouch policy, please see the discussion here: #5010