feat(sdk): chat.headStart for fast first-turn TTFC

Adds an opt-in fast path that runs step 1 streamText in the warm
customer process (Next.js, Hono, Workers, Express, etc.) while the
trigger agent run boots in parallel. Pure-text turns finish on the
handler side; tool-call turns hand ownership to the agent at the
tool-call boundary via a `kind: "handover"` chunk on session.in.

- New @trigger.dev/sdk/chat-server subpath with chat.headStart,
  chat.openSession (escape hatch), and chat.toNodeListener (Express /
  Fastify / Koa bridge from Web Fetch handler to (req, res)).
- Wire-format: ChatInputChunk gains kind: "handover" with isFinal flag
  and partialAssistantMessage; trigger payload kind: "handover-prepare"
  for the boot-and-wait variant.
- Run-loop: handover-prepare branch waits on session.in, then either
  skips userRun (isFinal: true → pure-text) or seeds accumulators and
  resumes step 2+ from tool-output-available (isFinal: false).
- Browser: TriggerChatTransport gains an optional `headStart` URL.
  First-turn POSTs go there; turn 2+ bypasses and writes session.in.
- Tests: chat-server.test.ts (handover dispatch, isFinal routing) and
  chatHandover.test.ts (run-loop branching, hook ordering, idle-timeout
  exit, schema-only-on-handler / executes-on-agent tool round).

Author: ericallam

.changeset/chat-head-start.md

@@ -0,0 +1,34 @@
+---
+"@trigger.dev/sdk": minor
+---
+
+Add `chat.headStart` — an opt-in fast-path that runs the first turn's `streamText` step in your warm Next.js / Hono / Workers / Express handler while the trigger agent run boots in parallel. Cold-start TTFC drops by ~50% on the first message; the agent owns step 2+ (tool execution, persistence, hooks) so heavy deps stay where they belong.
+
+```ts
+// app/api/chat/route.ts (Next.js / any Web Fetch framework)
+import { chat } from "@trigger.dev/sdk/chat-server";
+import { streamText } from "ai";
+import { openai } from "@ai-sdk/openai";
+import { headStartTools } from "@/lib/chat-tools-schemas"; // schema-only
+
+export const POST = chat.headStart({
+  agentId: "ai-chat",
+  run: async ({ chat: chatHelper }) =>
+    streamText({
+      ...chatHelper.toStreamTextOptions({ tools: headStartTools }),
+      model: openai("gpt-4o-mini"),
+      system: "You are a helpful AI assistant.",
+    }),
+});
+```
+
+```tsx
+// browser — opt in by pointing the transport at your handler
+const transport = useTriggerChatTransport({
+  task: "ai-chat",
+  accessToken,
+  headStart: "/api/chat", // first-turn-only; turn 2+ bypasses the endpoint
+});
+```
+
+For Node-only frameworks (Express, Fastify, Koa, raw `node:http`) use `chat.toNodeListener(handler)` to bridge the Web Fetch handler to `(req, res)`. Adds a new `@trigger.dev/sdk/chat-server` subpath; bundle stays Web Fetch–only with no `node:*` imports.

packages/trigger-sdk/package.json

@@ -28,7 +28,8 @@
       "./ai/skills-runtime": "./src/v3/agentSkillsRuntime.ts",
       "./ai/test": "./src/v3/test/index.ts",
       "./chat": "./src/v3/chat.ts",
-      "./chat/react": "./src/v3/chat-react.ts"
+      "./chat/react": "./src/v3/chat-react.ts",
+      "./chat-server": "./src/v3/chat-server.ts"
     },
     "sourceDialects": [
       "@triggerdotdev/source"
@@ -53,6 +54,9 @@
       ],
       "chat/react": [
         "dist/commonjs/v3/chat-react.d.ts"
+      ],
+      "chat-server": [
+        "dist/commonjs/v3/chat-server.d.ts"
       ]
     }
   },
@@ -187,6 +191,17 @@
         "types": "./dist/commonjs/v3/chat-react.d.ts",
         "default": "./dist/commonjs/v3/chat-react.js"
       }
+    },
+    "./chat-server": {
+      "import": {
+        "@triggerdotdev/source": "./src/v3/chat-server.ts",
+        "types": "./dist/esm/v3/chat-server.d.ts",
+        "default": "./dist/esm/v3/chat-server.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/v3/chat-server.d.ts",
+        "default": "./dist/commonjs/v3/chat-server.js"
+      }
     }
   },
   "main": "./dist/commonjs/v3/index.js",

packages/trigger-sdk/src/v3/ai-shared.ts

@@ -16,7 +16,7 @@
  */
 
 import type { Task, AnyTask } from "@trigger.dev/core/v3";
-import type { UIMessage } from "ai";
+import type { ModelMessage, UIMessage } from "ai";
 
 /**
  * Message-part `type` value for the pending-message data part the agent
@@ -31,7 +31,21 @@ export const PENDING_MESSAGE_INJECTED_TYPE = "data-pending-message-injected" as
 export type ChatTaskWirePayload<TMessage extends UIMessage = UIMessage, TMetadata = unknown> = {
   messages: TMessage[];
   chatId: string;
-  trigger: "submit-message" | "regenerate-message" | "preload" | "close" | "action";
+  trigger:
+    | "submit-message"
+    | "regenerate-message"
+    | "preload"
+    | "close"
+    | "action"
+    /**
+     * The customer's `chat.handover` route handler kicked us off in
+     * parallel with the first-turn `streamText` running in the warm
+     * Next.js process. The run sits idle on `session.in` waiting for
+     * a `kind: "handover"` (continue from tool execution) or
+     * `kind: "handover-skip"` (handler finished pure-text, exit
+     * cleanly). See `chat.handover` in `@trigger.dev/sdk/chat-server`.
+     */
+    | "handover-prepare";
   messageId?: string;
   metadata?: TMetadata;
   /** Custom action payload when `trigger` is `"action"`. Validated against `actionSchema` on the backend. */
@@ -83,6 +97,56 @@ export type ChatInputChunk<TMessage extends UIMessage = UIMessage, TMetadata = u
       kind: "stop";
       /** Optional human-readable reason. Maps to the legacy `chat-stop` record. */
       message?: string;
+    }
+  | {
+      /**
+       * Sent by `chat.headStart` when the customer's first-turn
+       * `streamText` finishes. The agent run (currently parked in
+       * `handover-prepare`) wakes, seeds its accumulators with
+       * `partialAssistantMessage`, and runs the normal turn loop
+       * (`onChatStart` → `onTurnStart` → … → `onTurnComplete`).
+       *
+       * What happens after that depends on `isFinal`:
+       *
+       * - `isFinal: false` — step 1 ended with `finishReason:
+       *   "tool-calls"`. The partial carries the assistant's
+       *   tool-call(s) wrapped in AI SDK's tool-approval round. The
+       *   agent's `streamText` runs the approved tools and continues
+       *   from step 2.
+       * - `isFinal: true` — step 1 ended pure-text (no tool calls).
+       *   The partial carries the final assistant text. The agent
+       *   skips the LLM call entirely (the response is already
+       *   complete on the customer side) and runs `onTurnComplete`
+       *   with the partial as `responseMessage` so persistence and
+       *   any post-turn work fire normally.
+       */
+      kind: "handover";
+      /** Customer's step-1 response messages (ModelMessage form). */
+      partialAssistantMessage: ModelMessage[];
+      /**
+       * The UI messageId the customer's handler used for its step-1
+       * assistant message. The agent reuses this so any post-handover
+       * chunks (tool-output-available, step-2 text, data-* parts
+       * written by hooks) merge into the SAME assistant message on
+       * the browser side instead of starting a new one.
+       */
+      messageId?: string;
+      /**
+       * Whether the customer's step 1 is the final response. See
+       * `kind` description above for the two branches.
+       */
+      isFinal: boolean;
+    }
+  | {
+      /**
+       * Sent by `chat.headStart` only when the customer's handler
+       * ABORTS before producing a finishReason (e.g., dispatch error,
+       * stream cancelled before any tokens). The agent run exits
+       * cleanly without firing turn hooks. Normal pure-text and
+       * tool-call finishes go through `kind: "handover"` with the
+       * appropriate `isFinal` flag.
+       */
+      kind: "handover-skip";
     };
 
 /**