@trigger.dev/sdk 0.0.0-chat-prerelease-20260519091352 → 0.0.0-chat-prerelease-20260521151946

package/dist/commonjs/v3/ai.d.ts

@@ -25,7 +25,11 @@ type ChatTurnContext<TClientData = unknown> = {
 };
 export declare function __setReadChatSnapshotImplForTests(impl: ReadChatSnapshotImpl | undefined): void;
 export declare function __setWriteChatSnapshotImplForTests(impl: WriteChatSnapshotImpl | undefined): void;
+type ReplaySessionOutTailImpl = <TUIMessage extends UIMessage>(sessionId: string, options?: {
+    lastEventId?: string;
+}) => Promise<ReplaySessionOutTailResult<TUIMessage>>;
 export declare function __setReplaySessionOutTailImplForTests(impl: ReplaySessionOutTailImpl | undefined): void;
+export declare function __setReplaySessionInTailImplForTests(impl: ReplaySessionInTailImpl | undefined): void;
 type ToolResultContent = Array<{
     type: "text";
     text: string;
@@ -896,6 +900,123 @@ export type BootEvent<TClientData = unknown> = {
     /** Whether this run was triggered as a preload. */
     preloaded: boolean;
 };
+/**
+ * A tool call extracted from the partial assistant message of a dead run.
+ * Surfaced on `RecoveryBootEvent.pendingToolCalls` so the customer can
+ * decide how to repair the chain (synthesize a result, drop the partial,
+ * etc.).
+ */
+export type RecoveryPendingToolCall = {
+    /** The AI SDK tool call id. */
+    toolCallId: string;
+    /** The tool name (the `tool-${name}` suffix). */
+    toolName: string;
+    /** The input the model produced for the tool call. */
+    input: unknown;
+    /** The part index inside `partialAssistant.parts` for in-place edits. */
+    partIndex: number;
+};
+/**
+ * Event passed to the `onRecoveryBoot` callback.
+ *
+ * Fires once at boot when a continuation run inherits in-flight state from
+ * a dead predecessor (cancel / crash / OOM / deploy eviction / graceful
+ * `chat.requestUpgrade`). The runtime reads both `session.in` and
+ * `session.out` past the last `turn-complete` cursor and surfaces the
+ * recovered pieces here so the customer can shape the conversational
+ * chain before the first turn fires.
+ *
+ * Does NOT fire when there's nothing to recover (clean continuation after
+ * `chat.endRun()` with no buffered user messages, fresh chat, OOM retry
+ * after a successful turn-complete with no in-flight tail).
+ *
+ * Does NOT fire when `hydrateMessages` is registered (the customer owns
+ * persistence; recovery decisions live in their own DB query).
+ */
+export type RecoveryBootEvent<TUIM extends UIMessage = UIMessage> = {
+    /** Task run context — same as `task({ run })` second-argument `ctx`. */
+    ctx: TaskRunContext;
+    /** The unique identifier for the chat session. */
+    chatId: string;
+    /** The Trigger.dev run ID for this run boot. */
+    runId: string;
+    /** Public id of the prior run that died. */
+    previousRunId: string;
+    /**
+     * Best-effort cause of the predecessor's death. Currently always
+     * `"unknown"` — the run engine doesn't yet plumb the real reason
+     * into the continuation payload. Future SDK versions will narrow
+     * this. Don't branch behavior on it yet.
+     */
+    cause: "cancelled" | "crashed" | "unknown";
+    /**
+     * The conversation chain that was successfully persisted by the
+     * predecessor's last `onTurnComplete`. Empty if the predecessor died
+     * before turn 1 ever completed.
+     */
+    settledMessages: TUIM[];
+    /**
+     * User messages that arrived on `session.in` past the cursor — i.e.
+     * the message(s) the predecessor was processing or had queued when
+     * it died. The runtime's default is to re-dispatch each as a fresh
+     * turn after the chain is restored. Return a different list via
+     * `recoveredTurns` to skip / reorder / collapse them.
+     */
+    inFlightUsers: TUIM[];
+    /**
+     * The trailing assistant message the predecessor was streaming when
+     * it died — the orphan whose `turn-complete` never fired. Undefined
+     * if the predecessor died before any assistant output reached
+     * `session.out` (cancel-before-first-token, snapshot-only path).
+     */
+    partialAssistant: TUIM | undefined;
+    /**
+     * Tool calls extracted from `partialAssistant.parts` that the model
+     * had started but the tool runtime never resolved. Empty when
+     * `partialAssistant` is undefined or carries no `input-available`
+     * tool parts.
+     */
+    pendingToolCalls: RecoveryPendingToolCall[];
+    /**
+     * Lazy session.out writer — identical to the `writer` passed to
+     * `onTurnStart` / `onTurnComplete` / `onChatStart`. Use this to emit
+     * a recovery signal (e.g. a `data-chat-recovery` UIMessage chunk)
+     * BEFORE the first recovered turn fires so the bridge can render a
+     * "recovering..." banner. Lazy: no overhead if unused.
+     */
+    writer: ChatWriter;
+};
+/**
+ * Return shape for the `onRecoveryBoot` callback. Every field is optional —
+ * omit one to accept the default.
+ */
+export type RecoveryBootResult<TUIM extends UIMessage = UIMessage> = {
+    /**
+     * The chain the new run boots with. Replaces the default
+     * (`settledMessages`). Use this to keep the partial assistant in
+     * context, mutate its tool parts to inject synthesized results,
+     * collapse history, etc.
+     *
+     * Ignored when `hydrateMessages` is registered (the hydrate hook
+     * runs per-turn and overwrites the chain).
+     */
+    chain?: TUIM[];
+    /**
+     * The user messages to re-dispatch as fresh turns after the chain is
+     * restored. Default: `inFlightUsers` (re-process every in-flight
+     * user). Return `[]` to suppress all of them; return a filtered /
+     * reordered subset to skip specific ones.
+     */
+    recoveredTurns?: TUIM[];
+    /**
+     * Awaitable run AFTER the writer flushes and BEFORE the first
+     * recovered turn fires. Use for blocking persistence (e.g. write the
+     * partial assistant to your DB so a follow-up turn can reference
+     * it). Errors bubble — wrap your own try/catch if you want to soft-
+     * fail.
+     */
+    beforeBoot?: () => Promise<void>;
+};
 /**
  * Event passed to the `onChatStart` callback.
  *
@@ -1337,6 +1458,40 @@ export type ChatAgentOptions<TIdentifier extends string, TClientDataSchema exten
      * ```
      */
     onBoot?: (event: BootEvent<inferSchemaOut<TClientDataSchema>>) => Promise<void> | void;
+    /**
+     * Recovery boot hook — fires once on a continuation run that inherited
+     * in-flight state from a dead predecessor (cancel / crash / OOM /
+     * deploy eviction / `chat.requestUpgrade()`). The runtime reads both
+     * stream tails past the last `turn-complete` cursor and hands the
+     * customer the recovered pieces (settled chain, in-flight users,
+     * partial assistant, pending tool calls) so the chain can be shaped
+     * before the first recovered turn fires.
+     *
+     * Does NOT fire when there's nothing to recover — e.g. a clean
+     * continuation after `chat.endRun()` with no buffered user, a fresh
+     * chat, or an OOM retry on top of a complete snapshot.
+     *
+     * Does NOT fire when `hydrateMessages` is registered — that hook owns
+     * the per-turn chain and overlapping recovery decisions belong in the
+     * customer's DB.
+     *
+     * Defaults (returned when the hook is omitted or returns no field):
+     *   - `chain` = `settledMessages` (drop the orphan partial)
+     *   - `recoveredTurns` = `inFlightUsers` (re-dispatch every user)
+     *
+     * @example
+     * ```ts
+     * onRecoveryBoot: async ({ partialAssistant, inFlightUsers, writer, cause }) => {
+     *   writer.write({
+     *     type: "data-chat-recovery",
+     *     id: generateId(),
+     *     data: { cause, partial: partialAssistant?.id },
+     *   });
+     *   return {}; // accept defaults: drop partial, re-dispatch users
+     * }
+     * ```
+     */
+    onRecoveryBoot?: (event: RecoveryBootEvent<TUIMessage>) => Promise<RecoveryBootResult<TUIMessage> | void> | RecoveryBootResult<TUIMessage> | void;
     /**
      * Called when a preloaded run starts, before the first message arrives.
      *
@@ -2436,9 +2591,17 @@ export type CreateChatStartSessionActionOptions = {
 /**
  * Params for the function returned by {@link createChatStartSessionAction}.
  */
-export type ChatStartSessionParams = {
+export type ChatStartSessionParams<TChat extends AnyTask = AnyTask> = {
     /** Conversation id (mapped to the Session's `externalId`). */
     chatId: string;
+    /**
+     * Typed client data — folded into the first run's `payload.metadata` so
+     * `onPreload`, `onChatStart`, etc. see the same `clientData` shape on the
+     * first turn as subsequent turns get via the transport's `clientData`
+     * option. Typed via the agent's `clientDataSchema` when the action is
+     * parameterised with `createStartSessionAction<typeof myChat>(...)`.
+     */
+    clientData?: InferChatClientData<TChat>;
     /**
      * Per-call trigger config. Shallow-merged over the action's default
      * `triggerConfig`. `basePayload` is the customer's wire payload (for
@@ -2446,7 +2609,11 @@ export type ChatStartSessionParams = {
      * which the runtime injects automatically).
      */
     triggerConfig?: Partial<SessionTriggerConfig>;
-    /** Pass-through metadata folded into the session row. */
+    /**
+     * Opaque session-level metadata stored on the Session row. Separate from
+     * the per-turn `clientData` above. Use this when you want to attach
+     * server-side metadata that doesn't go through the agent's `clientDataSchema`.
+     */
     metadata?: Record<string, unknown>;
 };
 /**
@@ -2472,29 +2639,33 @@ export type ChatStartSessionResult = {
  * Wrap in a Next.js server action (or any server-side handler) so the
  * customer's secret key never crosses to the browser.
  *
+ * Parameterise the action with `<typeof yourChatAgent>` to type the
+ * `clientData` field against your agent's `clientDataSchema`.
+ *
  * @example
  * ```ts
  * // actions.ts
  * "use server";
  * import { chat } from "@trigger.dev/sdk/ai";
+ * import type { myChat } from "@/trigger/chat";
  *
- * export const startChatSession = chat.createStartSessionAction("my-chat", {
- *   triggerConfig: { machine: "small-1x" },
- * });
+ * export const startChatSession = chat.createStartSessionAction<typeof myChat>(
+ *   "my-chat",
+ *   { triggerConfig: { machine: "small-1x" } }
+ * );
  * ```
  *
- * Then in the browser:
+ * Then in the browser, threading the typed `clientData` from the transport:
  * ```tsx
- * const transport = useTriggerChatTransport({
+ * const transport = useTriggerChatTransport<typeof myChat>({
  *   task: "my-chat",
- *   accessToken: async ({ chatId }) => {
- *     const { publicAccessToken } = await startChatSession({ chatId });
- *     return publicAccessToken;
- *   },
+ *   accessToken: ({ chatId }) => mintChatAccessToken(chatId),
+ *   startSession: ({ chatId, clientData }) =>
+ *     startChatSession({ chatId, clientData }),
  * });
  * ```
  */
-declare function createChatStartSessionAction(taskId: string, options?: CreateChatStartSessionActionOptions): (params: ChatStartSessionParams) => Promise<ChatStartSessionResult>;
+declare function createChatStartSessionAction<TChat extends AnyTask = AnyTask>(taskId: string, options?: CreateChatStartSessionActionOptions): (params: ChatStartSessionParams<TChat>) => Promise<ChatStartSessionResult>;
 export declare const chat: {
     /** Create a chat agent. See {@link chatAgent}. */
     agent: typeof chatAgent;