Upgrade Guide: prerelease → Sessions-as-run-manager

Documentation Index

Fetch the complete documentation index at: https://trigger.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

​

TL;DR

// Single accessToken callback, dispatches on purpose
accessToken: async ({ chatId, purpose }) => {
  if (purpose === "trigger") {
    return chat.createAccessToken<typeof myChat>("my-chat");
  }
  // purpose === "preload" — same call, same trigger token
  return chat.createAccessToken<typeof myChat>("my-chat");
};

• accessToken is now a pure session-PAT mint — called only on 401/403 to refresh. It must return a token scoped to the session, not a trigger:tasks JWT.
• startSession is a new callback that wraps a server action calling chat.createStartSessionAction(taskId). The transport invokes it on transport.preload(chatId) and lazily on the first sendMessage for any chatId without a cached PAT.
• ChatSession persistable state drops runId — store only {publicAccessToken, lastEventId?}.
• Per-call options on transport.preload(chatId, ...) are gone. Trigger config (machine, idleTimeoutInSeconds, tags, queue, maxAttempts) lives server-side in chat.createStartSessionAction(taskId, options).

​

Step 1: Replace your access-token server action with two server actions

"use server";

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

export const getChatToken = () =>
  chat.createAccessToken<typeof myChat>("my-chat");

"use server";

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

// Server-side wrapper for session creation. Idempotent on (env, chatId).
// The customer's server is the only entry point that creates Session rows;
// the browser never holds a `trigger:tasks` JWT.
export const startChatSession = chat.createStartSessionAction("my-chat");

// Pure session-PAT mint for the transport's 401/403 retry path.
export async function mintChatAccessToken(chatId: string) {
  return auth.createPublicToken({
    scopes: {
      read: { sessions: chatId },
      write: { sessions: chatId },
    },
    expirationTime: "1h",
  });
}

1. Creates the Session row for chatId (idempotent on the (env, externalId) unique pair).
2. Triggers the agent task’s first run with basePayload: {messages: [], trigger: "preload"} defaults plus any overrides you pass.
3. Returns {sessionId, runId, publicAccessToken} to the browser.

​

Step 2: Update the transport wiring

"use client";

import { useChat } from "@ai-sdk/react";
import { useTriggerChatTransport } from "@trigger.dev/sdk/chat/react";
import type { myChat } from "@/trigger/chat";
import { mintChatAccessToken, startChatSession } from "@/app/actions";

export function Chat() {
  const transport = useTriggerChatTransport<typeof myChat>({
    task: "my-chat",
    accessToken: ({ chatId }) => mintChatAccessToken(chatId),
    startSession: ({ chatId, clientData }) =>
      startChatSession({ chatId, clientData }),
  });

  const { messages, sendMessage, status } = useChat({ transport });
  // ...
}

​

Step 3: Drop transport-level trigger config

const transport = useTriggerChatTransport({
  task: "my-chat",
  accessToken: getChatToken,
  triggerConfig: { basePayload: { /* ... */ } },
  triggerOptions: { tags: [...], machine: "small-1x", maxAttempts: 3 },
});

transport.preload(chatId, { idleTimeoutInSeconds: 60, metadata: { ... } });

// Trigger config now lives in chat.createStartSessionAction
export const startChatSession = chat.createStartSessionAction("my-chat", {
  triggerConfig: {
    machine: "small-1x",
    maxAttempts: 3,
    tags: ["my-tag"],
    idleTimeoutInSeconds: 60,
  },
});

// Browser side
const transport = useTriggerChatTransport<typeof myChat>({
  task: "my-chat",
  accessToken: ({ chatId }) => mintChatAccessToken(chatId),
  startSession: ({ chatId, clientData }) =>
      startChatSession({ chatId, clientData }),
});

transport.preload(chatId);  // no second arg

​

Step 4: Use clientData for typed payload metadata

• Is passed to your startSession callback as params.clientData, where you forward it into chat.createStartSessionAction’s triggerConfig.basePayload.metadata. The agent’s first run sees it in payload.metadata (visible to onPreload / onChatStart).
• Merges into per-turn metadata on every .in/append chunk (visible to onTurnStart / inside run via turn.clientData).

const transport = useTriggerChatTransport<typeof myChat>({
  task: "my-chat",
  accessToken: ({ chatId }) => mintChatAccessToken(chatId),
  startSession: ({ chatId, clientData }) =>
      startChatSession({ chatId, clientData }),
  clientData: {
    userId: currentUser.id,
    plan: currentUser.plan,
  },
});

​

Step 5: Update your ChatSession persistence

type ChatSession = {
  runId: string;
  publicAccessToken: string;
  lastEventId?: string;
};

type ChatSession = {
  publicAccessToken: string;
  lastEventId?: string;
};

const transport = useTriggerChatTransport<typeof myChat>({
  // ...
  sessions: persistedSession
    ? { [chatId]: persistedSession }
    : {},
});

​

chat.requestUpgrade(): same call, faster handoff

• Before: the agent emitted a trigger:upgrade-required chunk on .out; the transport consumed it browser-side and triggered a new run.
• After: the agent calls endAndContinueSession server-to-server; the webapp triggers a new run and atomically swaps Session.currentRunId via optimistic locking. The browser’s existing SSE subscription keeps receiving chunks across the swap — no transport-side bookkeeping.

​

Hitting raw URLs

​

What didn’t change

• chat.agent({...}) definition — id, idleTimeoutInSeconds, clientDataSchema, actionSchema, hydrateMessages, onPreload, onChatStart, onValidateMessages, onTurnStart, onTurnComplete, onChatSuspend, run. All callbacks have the same signature and fire at the same lifecycle points.
• onAction is still defined the same way, but its semantics changed in the May 6 prerelease — actions are no longer turns, and onAction returning a StreamTextResult produces a model response.
• chat.customAgent({...}) and the chat.createSession(payload, ...) helper for building a session loop manually inside a custom agent.
• chat.defer (deferred work) and chat.history (imperative history mutations from inside onAction).
• AgentChat (server-side chat client) — agent, id, clientData, session, onTriggered, onTurnComplete, sendMessage, text().
• useTriggerChatTransport React semantics (created once, kept in a ref, callbacks updated under the hood).
• Multi-tab coordination (multiTab: true), pending messages / steering, background injection, compaction.
• Per-turn metadata flowing through sendMessage({ text }, { metadata }) to turn.metadata server-side.

​

Verifying the migration

• Eager preload. Click the button (or call transport.preload(id) programmatically) — your startSession callback should fire and a Session row + first run should be created before you send a message.
• Idle-timeout continuation. Wait past the agent’s idleTimeoutInSeconds so the run exits, then send another message — the transport’s .in/append should boot a new run on the same Session, with a SessionRun row of reason: "continuation".
• PAT refresh. Force a stale PAT in your DB (corrupt the signature) and reload — the first request should 401, your accessToken callback should fire, and the retry should succeed.

• Your accessToken callback returns a token minted via auth.createPublicToken({ scopes: { read: { sessions: chatId }, write: { sessions: chatId } } }), not chat.createAccessToken or auth.createTriggerPublicToken. The transport rejects trigger tokens now.
• Your startSession callback returns {publicAccessToken: string} — the result of chat.createStartSessionAction(taskId)({chatId, ...}) already has this shape.
• You haven’t left a stale getStartToken option on the transport; it’s not part of TriggerChatTransportOptions anymore.

​

v4.5 wire format change

​

Why the change

​

Object-store configuration

​

Custom transports

type ChatTaskWirePayload = {
  messages: UIMessage[];        // full history
  chatId: string;
  trigger: "submit-message" | "regenerate-message" | "preload" | "close" | "action";
  // ...
};

type ChatTaskWirePayload = {
  message?: UIMessage;          // singular, optional
  headStartMessages?: UIMessage[];  // chat.headStart only, "handover-prepare"
  chatId: string;
  trigger:
    | "submit-message"
    | "regenerate-message"
    | "preload"
    | "close"
    | "action"
    | "handover-prepare";
  // ...
};

​

hydrateMessages consumers

1. incomingMessages is now consistently 0-or-1-length. Previously some triggers (regenerate-message, continuation) shipped full history; now all triggers ship at most one. If you assumed incomingMessages could contain multiple messages and acted on them as a batch, the loop now runs zero or one times. Patterns like the one below work the same — they just iterate fewer messages:

hydrateMessages: async ({ incomingMessages }) => {
  for (const msg of incomingMessages) {  // 0-or-1 iterations
    for (const r of chat.history.extractNewToolResults(msg)) {
      await auditLog.record({ id: r.toolCallId, output: r.output });
    }
  }
  return await db.getMessages(chatId);
}

2. Registering hydrateMessages short-circuits snapshot+replay. The runtime trusts your hook to be the source of truth, so it doesn’t read or write the JSON snapshot or replay session.out. Zero object-store traffic. Trade-off: you own persistence end-to-end.

​

onChatStart is now once-per-chat

onChatStart: async ({ continuation, chatId, clientData }) => {
  if (continuation) return;           // ❌ no longer needed — fires only on first message ever
  await db.chat.create({ /* ... */ });
}

onChatStart: async ({ chatId, clientData }) => {
  await db.chat.create({ /* ... */ });  // ✅ guaranteed first-message-of-chat
}

​

Move chat.local init from onChatStart to onBoot

const userContext = chat.local<{ name: string; plan: string }>({ id: "userContext" });

onChatStart: async ({ clientData }) => {
  const user = await db.user.findUnique({ where: { id: clientData.userId } });
  userContext.init({ name: user.name, plan: user.plan }); // ❌ never runs on continuation
}

const userContext = chat.local<{ name: string; plan: string }>({ id: "userContext" });

onBoot: async ({ clientData }) => {
  const user = await db.user.findUnique({ where: { id: clientData.userId } });
  userContext.init({ name: user.name, plan: user.plan }); // ✅ runs on every fresh worker
}

​

Client-side setMessages doesn’t round-trip

​

Verifying the v4.5 migration

• Send a message, confirm the assistant streams a response.
• Reload mid-stream, confirm resume.
• Send 30+ turns with tool calls — .in/append body sizes stay under ~5 KB the entire time. (Pre-change baseline: payloads grew past 512 KB around turn 10-30.)
• Idle out a run, send another message — the new run reads the snapshot, replays the tail, and continues seamlessly.

• Confirm OBJECT_STORE_* env vars are set on the webapp.
• Confirm the bucket key packets/{projectRef}/{envSlug}/sessions/{sessionId}/snapshot.json exists after a successful turn.
• Or — register hydrateMessages and let your DB be the source of truth.

​

Reference

• TriggerChatTransport options
• chat.createStartSessionAction
• Backend setup
• Frontend setup
• Client Protocol — wire format reference
• Persistence and replay — snapshot model end-to-end