Vouch request: add triggerConfig to chat.headStart (handover-prepare tagging)

[saasjesus]

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!

[ericallam]

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. openHandoverSession is the one session-entry path that creates the session without tags, and because createSession is idempotent on (env, externalId = chatId), the head-start call on turn 0 is what fixes the session's triggerConfig for its whole lifetime. So tagging there is the correct fix, not just a convenience: a createStartSessionAction call on a later turn can't retroactively tag a session head-start already created, which is exactly the "no agentic-run: filter until after handover, if ever" you're seeing.

A few pointers for the PR:

• Mirror the merge logic in createChatStartSessionAction (packages/trigger-sdk/src/v3/ai.ts): the triggerConfig assembly that prepends the auto chat:{chatId} tag and shallow-merges basePayload / 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.
• Where to change: add triggerConfig?: Partial<SessionTriggerConfig> to HeadStartHandlerOptions, thread it through headStart into openHandoverSession, and fold it into the createSession call. Heads up that chat-server.ts has a hard bundle-isolation constraint (the route-handler bundle must stay lightweight), but SessionTriggerConfig is a type-only import so that's fine; just don't pull anything heavy in.
• Tests: chat-server.test.ts already asserts on the createSession request body (body.triggerConfig.basePayload.*), so extend that pattern to cover the merged tags / queue / etc.
• Changeset: 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!

[saasjesus]

Thanks @ericallam, created the new draft PR: #3933