Changelog

​

v4.5.0-rc.1 — two bug fixes

npx trigger.dev@4.5.0-rc.1 update              # npm
pnpm dlx trigger.dev@4.5.0-rc.1 update         # pnpm
yarn dlx trigger.dev@4.5.0-rc.1 update         # yarn
bunx trigger.dev@4.5.0-rc.1 update             # bun

​

Fixes

• Agent Skills silently missing in trigger dev for projects whose task files read process.env at module top level (e.g. a third-party SDK client initialized at import). Skill folders now bundle into .trigger/skills/ reliably regardless of which env vars are set when the CLI launches. (#3690)
• COULD_NOT_FIND_EXECUTOR when a task’s definition is loaded via await import(...) from inside another task’s run() — common when lazy-loading sub-agent tasks. Runtime workers now register such tasks with a sentinel file context, and the catalog logs a one-time warning per task id. (#3688)

​

v4.5.0-rc.0 — AI Agents graduate from chat-prerelease

pnpm add @trigger.dev/sdk@rc

​

What’s in the box

• chat.agent — multi-turn AI chat backends as durable Trigger.dev tasks. Lifecycle hooks, recovery from cancel/crash/OOM, version upgrades, all in. See Overview and Quick Start.
• Sessions — the durable bi-directional stream primitive that backs chat.agent. Use it directly for any pattern that needs durable bi-directional streaming across runs. See Sessions.
• useTriggerChatTransport — a custom AI SDK ChatTransport for useChat. No API routes. See Frontend.
• Head Start — opt-in route handler that runs the first streamText step in your warm server while the agent boots in parallel. Cuts cold-start TTFC roughly in half. See Fast starts.
• AI Prompts — code-defined, deploy-versioned templates with dashboard overrides for text + model. Integrates with chat.agent via chat.prompt.set() + chat.toStreamTextOptions(). See Prompts.
• ai.toolExecute — wire any Trigger subtask in as the execute of an AI SDK tool(). See Sub-agents.

​

Compatibility

​

Docs

​

Recovery boot — context-preserving continuation after cancel / crash / OOM

import { chat } from "@trigger.dev/sdk/ai";

export const myChat = chat.agent({
  id: "my-chat",
  onRecoveryBoot: async ({ partialAssistant, inFlightUsers, writer, cause, previousRunId }) => {
    writer.write({
      type: "data-chat-recovery",
      data: { cause, previousRunId, partialPresent: partialAssistant !== undefined },
      transient: true,
    });
    // return nothing → smart default applies
  },
  run: async ({ messages, signal }) => streamText({ model, messages, abortSignal: signal }),
});

​

session.out is now bounded — header-form control records + per-turn trim

​

What changed on the wire

headers:
  ["trigger-control", "turn-complete"]
  ["public-access-token", "eyJ..."]   // optional, refreshed JWT on turn-complete
body: ""

headers:
  ["trigger-control", "upgrade-required"]
body: ""

​

Custom transport implementers

import { controlSubtype } from "@trigger.dev/core/v3";

const control = controlSubtype(record.headers);
if (control === "turn-complete") {
  // refresh token from record.headers, end turn, etc.
}

​

Sessions dashboard snapshot read

​

Breaking surface

• Custom transports parsing chunk.type for turn-complete / upgrade-required must switch to the trigger-control header check.
• Snapshot consumers should import ChatSnapshotV1 / ChatSnapshotV1Schema from @trigger.dev/core/v3 (now an exported shape, not SDK-internal).

​

Docs

• Records on session.out — full filter rule for data / control / command records.
• Resuming a stream — explicit single-turn vs multi-turn-away semantics.
• turn-complete control record and upgrade-required control record — replaced the old chunk-shape docs.

​

512 KiB /in/append ceiling removed for long chats — slim wire + S3 snapshot

// Before — full history shipped on every send
{ messages: [u1, a1, u2, a2, /* ... 30 turns ... */, u31], chatId, trigger: "submit-message" }

// After — only the new turn
{ message: u31, chatId, trigger: "submit-message" }

​

What changed

• ChatTaskWirePayload: messages: UIMessage[] is removed. Replaced by message?: UIMessage (singular, optional) and a dedicated headStartMessages?: UIMessage[] field used only by chat.headStart first-turn handover.
• Run boot: when hydrateMessages is not registered, the runtime reads packets/{projectRef}/{envSlug}/sessions/{sessionId}/snapshot.json from object storage and replays any session.out chunks landed since the snapshot’s cursor. Snapshot writes happen after every onTurnComplete, awaited so they survive an idle suspend.
• hydrateMessages short-circuit: registering the hook skips snapshot read/write and replay entirely. Customer is the source of truth for history, same as today.
• hydrateMessages.incomingMessages: now consistently 0-or-1-length across every trigger type. Previously regenerate-message and continuations occasionally shipped full history; they now ship none.
• onChatStart is now once-per-chat: fires only on the chat’s very first user message; does NOT fire on continuation runs (post-endRun, post-waitpoint-timeout, post-chat.requestUpgrade) or on OOM-retry attempts. The continuation and previousRunId fields on ChatStartEvent are now @deprecated (always false / undefined when the hook fires). Drop any if (continuation) return; gates from onChatStart — they’re now unreachable. For per-turn setup that runs on continuations too, move to onTurnStart.
• Continuation boot payload: the server now strips message / messages / trigger from the cached basePayload on continuation runs, and the SDK enters a new continuation-wait branch that waits silently on session.in for the next user message. Fixes a phantom-turn bug where stale boot-payload fields were replayed on every resume.
• OOM-retry boot: uses the snapshot’s lastOutTimestamp as the session.in cutoff, saving one stream subscription per retry.
• Built-in transports: TriggerChatTransport, AgentChat, mid-stream pending-message handling, and chat.headStart route handler all updated to the slim shape. Existing customer code calling transport.sendMessage(...) / agentChat.sendMessage(...) is unaffected — the change is below those surfaces.

​

Object store configuration

​

Breaking surface

• Custom transports: any code constructing ChatTaskWirePayload directly must drop messages and use message. See the rewritten Client Protocol.
• Client-side setMessages no longer round-trips: full-history mutations on the client never reached the agent before this release either, but the slim wire makes that explicit. Use server-side chat.history.set() inside onTurnStart for compaction.
• Custom server-to-server senders: code calling apiClient.appendToSessionInput(sessionId, ...) or hitting /realtime/v1/sessions/{id}/in/append directly must switch to the slim shape.

​

Docs

• Rewritten Client Protocol — slim payload, new headStartMessages field, new “How history is rebuilt” and “Head-start protocol caveat” sections.
• New Persistence and replay — end-to-end walkthrough of the snapshot model, OOM-retry interaction, crash semantics, hydrateMessages short-circuit.
• New Tool result auditing — the extractNewToolResults + onTurnComplete / hydrateMessages pattern for HITL audit logging.
• v4.5 section of the upgrade guide — migration steps for custom transports and hydrateMessages consumers.
• hydrateMessages, onChatStart — clarifications on the new incomingMessages and messages shapes.

​

chat.history read primitives for HITL flows

// Refuse a regenerate while a tool call is awaiting an answer
onAction: async ({ action }) => {
  if (action.type === "regenerate") {
    if (chat.history.getPendingToolCalls().length > 0) return;
    chat.history.slice(0, -1);
  }
},

// Side-effect once per net-new tool result on incoming wire messages
hydrateMessages: async ({ incomingMessages }) => {
  for (const msg of incomingMessages) {
    for (const r of chat.history.extractNewToolResults(msg)) {
      await auditLog.record({ id: r.toolCallId, output: r.output, errorText: r.errorText });
    }
  }
  return incomingMessages;
},

​

Fix: HITL addToolOutput resume preserves the assistant message id

​

chat.agent actions are no longer turns

​

Migration

// before
onAction: async ({ action }) => {
  if (action.type === "regenerate") {
    runState.skipModelCall = false;
    chat.history.slice(0, -1);
  }
},
run: async ({ messages, signal }) => {
  if (runState.skipModelCall) return;
  return streamText({ model, messages, abortSignal: signal });
},

// after
onAction: async ({ action, messages, signal }) => {
  if (action.type === "regenerate") {
    chat.history.slice(0, -1);
    return streamText({ model, messages, abortSignal: signal });
  }
},
run: async ({ messages, signal }) =>
  streamText({ model, messages, abortSignal: signal }),

​

Fix: duplicate turn after chat.agent idle-suspends

​

chat.headStart — fast first-turn for chat.agent

​

Setup

import { chat } from "@trigger.dev/sdk/chat-server";
import { streamText } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { headStartTools } from "@/lib/chat-tools/schemas";

export const POST = chat.headStart({
  agentId: "my-chat",
  run: async ({ chat: helper }) =>
    streamText({
      ...helper.toStreamTextOptions({ tools: headStartTools }),
      model: anthropic("claude-sonnet-4-6"),
      system: "You are a helpful assistant.",
    }),
});

const transport = useTriggerChatTransport({
  task: "my-chat",
  accessToken: ({ chatId }) => mintChatAccessToken(chatId),
  startSession: ({ chatId, taskId, clientData }) =>
    startChatSession({ chatId, taskId, clientData }),
  headStart: "/api/chat",
});

​

Bundle isolation

​

Compared to Preload

​

Works on every runtime

import express from "express";
import { chat } from "@trigger.dev/sdk/chat-server";

const handler = chat.headStart({ agentId: "my-chat", run: ... });

const app = express();
app.post("/api/chat", chat.toNodeListener(handler));

​

Docs

• New Head Start guide — bundle isolation, schema/execute split, route handler setup, transport option, lifecycle, limitations.
• Reference — headStart transport option.

​

Resilient SSE reconnection

​

chat.agent now runs on Sessions

• Output chunks stream on session.out (was a run-scoped streams.writer("chat")).
• Client messages and stops land on session.in as a ChatInputChunk tagged union (was two run-scoped streams.input definitions).
• Wire endpoints moved from /realtime/v1/streams/{runId}/... to /realtime/v1/sessions/{sessionId}/.... See the rewritten Client Protocol.

• Cross-run resume is free. A chat you were in yesterday resumes against the same sessionId today, even if the original run long since exited. No more lost conversations when a run idle-times-out.
• Inbox views via sessions.list({type: "chat.agent"}). Enumerate every chat in your environment, filter by tag or status.
• TriggerChatTaskResult.sessionId + ChatTaskRunPayload.sessionId — you can reach into the raw session via sessions.open(payload.sessionId) for advanced cases (writing from a sub-agent, custom transport).
• Dashboard Agent tab resolves via sessionId and stays in sync with the live stream across runs.

​

X-Session-Settled — fast reconnect on idle chats

​

Migration

​

Docs

• Rewritten Client Protocol — full wire format for the new /realtime/v1/sessions/{sessionId}/... endpoints, JWT scopes, S2 direct-write credentials, and Last-Event-ID resume.
• Database persistence pattern — new chatId-keyed ChatSession shape (no more runId) and a warning on the onTurnComplete race that requires a single atomic write of messages + lastEventId.
• Reference — added chat.createStartSessionAction, chat.createAccessToken, ChatInputChunk, TriggerChatTaskResult.sessionId, ChatTaskRunPayload.sessionId. The old run-scoped stream-ID constants are gone.
• Refreshed Backend, Frontend, Server Chat, Quick start, Overview, Types, Error handling, and Testing for the session-based wiring.

​

Agent Skills

​

chat.endRun() — exit on your own terms

chat.agent({
  id: "one-shot",
  run: async ({ messages, signal }) => {
    chat.endRun();
    return streamText({ model: openai("gpt-4o"), messages, abortSignal: signal });
  },
});

​

finishReason on turn-complete events

onTurnComplete: async ({ finishReason, responseMessage }) => {
  if (finishReason === "tool-calls") {
    // Paused — assistant message has a pending tool call waiting for user input
    await persistCheckpoint(responseMessage);
  } else {
    await persistCompleted(responseMessage);
  }
};

​

User-initiated compaction pattern

​

Human-in-the-loop pattern page

​

Offline test harness for chat.agent

import { mockChatAgent } from "@trigger.dev/sdk/ai/test";
import { MockLanguageModelV3 } from "ai/test";
import { myAgent } from "./my-agent";

const harness = mockChatAgent(myAgent, {
  chatId: "test-1",
  clientData: {
    model: new MockLanguageModelV3({
      /* ... */
    }),
  },
});

const turn = await harness.sendMessage({
  id: "u1",
  role: "user",
  parts: [{ type: "text", text: "hi" }],
});
expect(turn.chunks).toContainEqual(expect.objectContaining({ type: "text-delta", delta: "hello" }));
await harness.close();

​

Dependency injection via locals

import { dbKey } from "./db";

const harness = mockChatAgent(agent, {
  chatId: "test-1",
  setupLocals: ({ set }) => {
    set(dbKey, testDb);
  },
});

​

runInMockTaskContext — lower-level test harness

​

Multi-tab coordination

const transport = useTriggerChatTransport({ task: "my-chat", multiTab: true, accessToken });
const { messages, setMessages } = useChat({ id: chatId, transport });
const { isReadOnly } = useMultiTabChat(transport, chatId, messages, setMessages);

​

Error stack truncation

​

Fix: resume: true hangs on completed turns

​

hydrateMessages — backend-controlled message history

chat.agent({
  id: "my-chat",
  hydrateMessages: async ({ chatId, trigger, incomingMessages }) => {
    const stored = await db.getMessages(chatId);
    if (trigger === "submit-message" && incomingMessages.length > 0) {
      stored.push(incomingMessages[incomingMessages.length - 1]!);
      await db.persistMessages(chatId, stored);
    }
    return stored;
  },
});

​

chat.history — imperative message mutations

chat.history.rollbackTo(messageId); // Undo — keep up to this message
chat.history.remove(messageId); // Remove one message
chat.history.replace(id, newMsg); // Edit a message
chat.history.slice(0, -2); // Remove last 2 messages
chat.history.all(); // Read current state

​

Custom actions — actionSchema + onAction

chat.agent({
  id: "my-chat",
  actionSchema: z.discriminatedUnion("type", [
    z.object({ type: z.literal("undo") }),
    z.object({ type: z.literal("rollback"), targetMessageId: z.string() }),
  ]),
  onAction: async ({ action }) => {
    if (action.type === "undo") chat.history.slice(0, -2);
    if (action.type === "rollback") chat.history.rollbackTo(action.targetMessageId);
  },
});

​

chat.response — persistent data parts

// Persists to responseMessage.parts — available in onTurnComplete
chat.response.write({ type: "data-handover", data: { context: summary } });

// Transient — streams to frontend only, not in responseMessage
writer.write({ type: "data-progress", data: { percent: 50 }, transient: true });

​

Tool approvals

const sendEmail = tool({
  description: "Send an email. Requires human approval.",
  inputSchema: z.object({ to: z.string(), subject: z.string(), body: z.string() }),
  needsApproval: true,
  execute: async ({ to, subject, body }) => {
    /* ... */
  },
});

​

transport.stopGeneration(chatId)

const stop = useCallback(() => {
  transport.stopGeneration(chatId);
  aiStop(); // also update useChat state
}, [transport, chatId, aiStop]);

​

generateMessageId support

​

Bug fixes

• onTurnComplete not called: Fixed turnCompleteResult?.lastEventId TypeError that silently skipped onTurnComplete when writeTurnCompleteChunk returned undefined in dev.
• Stop during streaming: Added 2s timeout on onFinishPromise so onBeforeTurnComplete and onTurnComplete fire even when the AI SDK’s onFinish doesn’t fire after abort.
• toStreamTextOptions without chat.prompt.set(): prepareStep injection (compaction, steering, background context) now works even when the user passes system directly to streamText instead of using chat.prompt.set().
• Background queue vs tool approvals: Background context injection is now skipped when the last accumulated message is a tool message, preventing it from breaking streamText’s collectToolApprovals.