@trigger.dev/sdk 4.5.12 → 4.5.14

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

@@ -171,6 +171,10 @@ export type ChatWriter = {
     /** Merge another stream's chunks into the chat stream. */
     merge(stream: ReadableStream<UIMessageChunk>): void;
 };
+type ChatCustomAgentClientDataErrorHandler = (event: {
+    error: unknown;
+    payload: ChatTaskWirePayload;
+}) => Promise<void> | void;
 /**
  * The payload shape passed to the `chatAgent` run function.
  *
@@ -257,6 +261,26 @@ export type ChatTaskRunPayload<TClientData = unknown, TTools extends ToolSet = T
      */
     tools: TTools;
 };
+/**
+ * One message record delivered through {@link chat.messages}.
+ *
+ * `id` is the append's stable idempotency key and `seqNum` is its monotonic
+ * sequence on the Session `.in` channel. Both remain stable if the record is
+ * delivered again after a reconnect.
+ */
+export type ChatMessageRecord = Readonly<{
+    id: string;
+    seqNum: number;
+    payload: ChatTaskWirePayload;
+}>;
+export type ChatMessages = RealtimeDefinedInputStream<ChatTaskWirePayload> & {
+    /** Whether the local buffer head is a message that can be consumed immediately. */
+    hasPending(): Promise<boolean>;
+    /** Consume one message record, or return `undefined` when the optional timeout elapses. */
+    next(options?: {
+        timeoutInSeconds?: number;
+    }): Promise<ChatMessageRecord | undefined>;
+};
 /**
  * Signal received by a `handover-prepare` agent run waiting on
  * `session.in`. Either the customer's first-turn `streamText` finished
@@ -294,9 +318,8 @@ export type HandoverSignal = {
  * For the common case prefer `accumulator.consumeHandover()`, which also seeds
  * `payload.headStartMessages` and applies the partial for you.
  *
- * Must be called at turn 0 before any `chat.messages.waitWithIdleTimeout` —
- * that facade consumes and discards non-message chunks, which would swallow the
- * handover signal.
+ * Safe to call at any point in turn 0: the handover signal has its own route,
+ * so a message facade waiting at the same time cannot take it.
  */
 declare function waitForHandover(options: {
     /** The run's wire payload (only `trigger` / `idleTimeoutInSeconds` are read). */
@@ -1101,8 +1124,11 @@ export type RecoveryBootEvent<TUIM extends UIMessage = UIMessage> = {
     /**
      * 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
+     * it died. The runtime's default re-dispatches each as a fresh turn
+     * after the chain is restored, except when a `partialAssistant` is
+     * present AND there are two or more of them: the first is then
+     * spliced into the chain (as the question the partial was answering)
+     * rather than dispatched. Return a different list via
      * `recoveredTurns` to skip / reorder / collapse them.
      */
     inFlightUsers: TUIM[];
@@ -1146,8 +1172,12 @@ export type RecoveryBootResult<TUIM extends UIMessage = UIMessage> = {
     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 /
+     * restored. Default: `inFlightUsers.slice(1)` when a
+     * `partialAssistant` is present and there are two or more in-flight
+     * users (the first one is spliced into the chain instead), otherwise
+     * `inFlightUsers` — including the single-user case, where the
+     * interrupted user is re-dispatched and the orphan partial is
+     * dropped. Return `[]` to suppress all of them; return a filtered /
      * reordered subset to skip specific ones.
      */
     recoveredTurns?: TUIM[];
@@ -1665,8 +1695,13 @@ export type ChatAgentOptions<TIdentifier extends string, TClientDataSchema exten
      * 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)
+     *   - With two or more in-flight users, the partial and the user it
+     *     was answering are spliced into the chain:
+     *     `chain` = `[...settledMessages, inFlightUsers[0], partialAssistant]`
+     *     and `recoveredTurns` = `inFlightUsers.slice(1)`.
+     *   - Otherwise `chain` = `settledMessages` (drop the orphan partial)
+     *     and `recoveredTurns` = `inFlightUsers` (re-dispatch every user)
+     *     — so a single interrupted user is answered on the new run.
      *
      * @example
      * ```ts
@@ -2077,8 +2112,48 @@ export type ChatAgentOptions<TIdentifier extends string, TClientDataSchema exten
  * });
  * ```
  */
-type ChatCustomAgentOptions<TIdentifier extends string, TClientDataSchema extends TaskSchema | undefined = undefined, TUIMessage extends UIMessage = UIMessage> = Omit<TaskOptions<TIdentifier, ChatTaskWirePayload<TUIMessage, inferSchemaIn<TClientDataSchema>>, unknown>, "triggerSource" | "agentConfig"> & {
+type ChatCustomAgentOptions<TIdentifier extends string, TClientDataSchema extends TaskSchema | undefined = undefined, TUIMessage extends UIMessage = UIMessage> = Omit<TaskOptions<TIdentifier, ChatTaskWirePayload<TUIMessage, inferSchemaIn<TClientDataSchema>>, unknown>, "triggerSource" | "agentConfig" | "run"> & {
+    /**
+     * Schema for validating `metadata` from the frontend.
+     *
+     * The initial payload and later `chat.messages` frames are parsed before
+     * user code receives them. Invalid submitted turns and async reads write an
+     * error chunk followed by `turn-complete`. Messageless boots and active
+     * subscriptions use `onClientDataValidationError` and the task log because
+     * there is no submitted turn to complete or a response may still be streaming.
+     * This validates `metadata` only; raw `action` payloads remain `unknown`.
+     */
     clientDataSchema?: TClientDataSchema;
+    /**
+     * Called when a custom-agent input fails `clientDataSchema` validation.
+     *
+     * Submitted turns and async reads also write an error chunk followed by
+     * `turn-complete`. Messageless boots and active `chat.messages.on()`
+     * subscriptions are reported through this callback and the task log only.
+     *
+     * `payload.metadata` is typed `unknown`: this callback only fires when
+     * the metadata failed to parse, so it can be any shape the client sent.
+     */
+    onClientDataValidationError?: (event: {
+        error: unknown;
+        payload: ChatTaskWirePayload<TUIMessage, unknown>;
+    }) => Promise<void> | void;
+    /**
+     * When a frame that arrived mid-turn fails `clientDataSchema` validation,
+     * decides when the terminal error reaches the client.
+     *
+     * - `"turn-end"` (default) waits until the turn has closed. A terminal error
+     *   written into a live response can close it, so this keeps a bad client
+     *   send from truncating an answer the user is already reading.
+     * - `"arrival"` writes it as soon as validation fails, which surfaces the
+     *   problem sooner at the cost of ending the response in progress.
+     *
+     * `onClientDataValidationError` and the task log fire on arrival either way;
+     * this only governs the stream-visible error. The frame is never delivered as
+     * a turn in either mode.
+     */
+    clientDataReportErrorAt?: "turn-end" | "arrival";
+    run: TaskOptions<TIdentifier, ChatTaskWirePayload<TUIMessage, inferSchemaOut<TClientDataSchema>>, unknown>["run"];
 };
 declare function chatCustomAgent<TIdentifier extends string, TClientDataSchema extends TaskSchema | undefined = undefined, TUIMessage extends UIMessage = UIMessage>(options: ChatCustomAgentOptions<TIdentifier, TClientDataSchema, TUIMessage>): Task<TIdentifier, ChatTaskWirePayload<TUIMessage, inferSchemaIn<TClientDataSchema>>, unknown>;
 declare function chatAgent<TIdentifier extends string, TClientDataSchema extends TaskSchema | undefined = undefined, TUIMessage extends UIMessage = UIMessage, TActionSchema extends TaskSchema | undefined = undefined, TTools extends ToolSet = ToolSet>(options: ChatAgentOptions<TIdentifier, TClientDataSchema, TUIMessage, TActionSchema, TTools>): Task<TIdentifier, ChatTaskWirePayload<TUIMessage, inferSchemaIn<TClientDataSchema>>, unknown>;
@@ -2111,9 +2186,29 @@ export type ChatWithUIMessageConfig<TUIM extends UIMessage = UIMessage> = {
 export interface ChatBuilder<TUIMessage extends UIMessage = UIMessage, TClientDataSchema extends TaskSchema | undefined = undefined> {
     /** Fix the UI message type. Returns a new builder preserving all accumulated state. */
     withUIMessage<TUIM extends UIMessage = UIMessage>(config?: ChatWithUIMessageConfig<TUIM>): ChatBuilder<TUIM, TClientDataSchema>;
-    /** Fix the client data schema. Returns a new builder preserving all accumulated state. */
+    /**
+     * Fix the client data schema, and how validation failures are handled.
+     * Returns a new builder preserving all accumulated state.
+     */
     withClientData<TSchema extends TaskSchema>(config: {
         schema: TSchema;
+        /**
+         * When a frame that arrived mid-turn fails validation, decides when the
+         * client-visible error is written.
+         *
+         * `"turn-end"` (default) waits for the turn to close, so a bad send cannot
+         * truncate an answer already being read. `"arrival"` writes it as soon as
+         * validation fails, ending the response in progress.
+         *
+         * `onValidationError` and the task log fire on arrival either way, and the
+         * frame is never delivered as a turn.
+         */
+        reportErrorAt?: "turn-end" | "arrival";
+        /** Called when an input fails validation. Composes with the task-level hook. */
+        onValidationError?: (event: {
+            error: unknown;
+            payload: ChatTaskWirePayload<TUIMessage, unknown>;
+        }) => Promise<void> | void;
     }): ChatBuilder<TUIMessage, TSchema>;
     /** Register a builder-level `onBoot` hook. Runs before the task-level hook if both are set. */
     onBoot(fn: (event: BootEvent<inferSchemaOut<TClientDataSchema>>) => Promise<void> | void): ChatBuilder<TUIMessage, TClientDataSchema>;
@@ -2151,7 +2246,7 @@ export interface ChatBuilder<TUIMessage extends UIMessage = UIMessage, TClientDa
      * Builder hooks (`onPreload`, `onChatStart`, etc.) are not applied —
      * those are managed-lifecycle concepts handled by `.agent()`.
      */
-    customAgent: [TClientDataSchema] extends [undefined] ? <TId extends string>(options: ChatCustomAgentOptions<TId, undefined, TUIMessage>) => Task<TId, ChatTaskWirePayload<TUIMessage, undefined>, unknown> : <TId extends string>(options: ChatCustomAgentOptions<TId, TClientDataSchema, TUIMessage>) => Task<TId, ChatTaskWirePayload<TUIMessage, inferSchemaIn<TClientDataSchema>>, unknown>;
+    customAgent: [TClientDataSchema] extends [undefined] ? <TId extends string>(options: ChatCustomAgentOptions<TId, undefined, TUIMessage>) => Task<TId, ChatTaskWirePayload<TUIMessage, undefined>, unknown> : <TId extends string>(options: Omit<ChatCustomAgentOptions<TId, TClientDataSchema, TUIMessage>, "clientDataSchema">) => Task<TId, ChatTaskWirePayload<TUIMessage, inferSchemaIn<TClientDataSchema>>, unknown>;
 }
 /**
  * Fix the UI message type for a chat task (AI SDK `UIMessage` generics) while
@@ -2195,6 +2290,8 @@ declare function withUIMessage<TUIM extends UIMessage = UIMessage>(config?: Chat
  */
 declare function withClientData<TSchema extends TaskSchema>(config: {
     schema: TSchema;
+    reportErrorAt?: "turn-end" | "arrival";
+    onValidationError?: ChatCustomAgentClientDataErrorHandler;
 }): ChatBuilder<UIMessage, TSchema>;
 /**
  * Override the turn timeout for subsequent turns in the current run.
@@ -2321,6 +2418,37 @@ declare function isStopped(): boolean;
  * ```
  */
 declare function requestUpgrade(): void;
+/**
+ * Hand off the current custom agent Session to a fresh run.
+ *
+ * This is the low-level handoff for a fully hand-rolled
+ * `chat.customAgent()` loop. This method rejects while a
+ * `chat.createSession()` iterator is active. Close the iterator before calling
+ * it. If `return()` races an active `next()`, it waits for that read to settle
+ * before releasing the handoff guard. Call only between turns and after
+ * detaching input listeners for the old run. If the old run completed its
+ * current turn, persist its state and call {@link chatWriteTurnComplete} before
+ * handing off.
+ * Do not write a new turn boundary after input that the continuation run should
+ * process has been dispatched: the boundary acknowledges that input.
+ *
+ * The server starts the continuation run but does not stop this run, so return
+ * from the task immediately after awaiting this function. The promise rejects
+ * if the server cannot complete the handoff.
+ *
+ * Pending Session input that the old run has not consumed remains on the
+ * durable `.in` stream and is delivered to the continuation run.
+ *
+ * @example
+ * ```ts
+ * // Detach any chat.messages.on() subscriptions you created.
+ * await persistMessages();
+ * await chat.writeTurnComplete();
+ * await chat.endAndContinue();
+ * return;
+ * ```
+ */
+declare function endAndContinue(): Promise<void>;
 /**
  * Exit the run after the current turn completes, without waiting for the
  * next message. Unlike {@link requestUpgrade}, no upgrade-required signal
@@ -2460,10 +2588,14 @@ declare function createStopSignal(): {
  * task instead of round-tripping them back from the client:
  * - `lastEventId` — the turn-complete control record's seq_num on
  *   `session.out`; where the next turn's output stream resumes.
- * - `sessionInEventId` — the committed-consume cursor on `session.in` as of
- *   this turn-complete, letting a raw loop correlate the boundary with the
- *   exact input record it acknowledged. Trigger owns input-cursor recovery,
- *   so this is for correlation / out-of-sync detection, not required.
+ * - `sessionInEventId` — the safe-to-resume-from cursor on `session.in` as of
+ *   this turn-complete. It is the highest sequence that can be resumed past
+ *   without skipping an unhandled message, so it is held back behind any
+ *   message still buffered unconsumed and is NOT necessarily the sequence of
+ *   the record this turn answered. Trigger owns input-cursor recovery, so this
+ *   is for correlation / out-of-sync detection, not required. Treat it as a
+ *   lower bound: a value below the record you just handled is expected, not a
+ *   sign of a lost turn.
  *
  * Either is `undefined` when the corresponding cursor isn't available.
  *
@@ -2655,7 +2787,7 @@ export type ChatSessionOptions = {
     /** Configure mid-execution message injection — same options as `chat.agent({ pendingMessages })`. */
     pendingMessages?: PendingMessagesOptions;
 };
-export type ChatTurn = {
+export type ChatTurn<TClientData = unknown> = {
     /** Turn number (0-indexed). */
     number: number;
     /** Chat session ID. */
@@ -2663,7 +2795,7 @@ export type ChatTurn = {
     /** What triggered this turn. */
     trigger: string;
     /** Client data from the transport (`metadata` field on the wire payload). */
-    clientData: unknown;
+    clientData: TClientData;
     /** Full accumulated model messages — pass directly to `streamText`. */
     readonly messages: ModelMessage[];
     /** Full accumulated UI messages — use for persistence. */
@@ -2758,7 +2890,7 @@ export type ChatTurn = {
  * });
  * ```
  */
-declare function createChatSession(payload: ChatTaskWirePayload, options: ChatSessionOptions): AsyncIterable<ChatTurn>;
+declare function createChatSession<TClientData = unknown>(payload: ChatTaskWirePayload<UIMessage, TClientData>, options: ChatSessionOptions): AsyncIterable<ChatTurn<TClientData>>;
 /**
  * A Proxy-backed, run-scoped data object that appears as `T` to users.
  * Includes helper methods for initialization, dirty tracking, and serialization.
@@ -2991,6 +3123,8 @@ export declare const chat: {
     isStopped: typeof isStopped;
     /** Request that the run exits after the current turn so the next message starts on the latest version. See {@link requestUpgrade}. */
     requestUpgrade: typeof requestUpgrade;
+    /** Hand off a custom agent Session to a fresh run. See {@link endAndContinue}. */
+    endAndContinue: typeof endAndContinue;
     /** Exit the run after the current turn completes, without any upgrade signal. See {@link endRun}. */
     endRun: typeof endRun;
     /** Clean up aborted parts from a UIMessage. See {@link cleanupAbortedParts}. */
@@ -3010,7 +3144,7 @@ export declare const chat: {
         write(part: UIMessageChunk): void;
     };
     /** Pre-built input stream for receiving messages from the transport. */
-    messages: RealtimeDefinedInputStream<ChatTaskWirePayload>;
+    messages: ChatMessages;
     /** Create a managed stop signal wired to the stop input stream. See {@link createStopSignal}. */
     createStopSignal: typeof createStopSignal;
     /** Signal the frontend that the current turn is complete. See {@link chatWriteTurnComplete}. */