@trigger.dev/sdk 0.0.0-chat-prerelease-20260414181032 → 0.0.0-chat-prerelease-20260415152704

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

@@ -170,9 +170,11 @@ export type ChatWriter = {
 export type ChatTaskWirePayload<TMessage extends UIMessage = UIMessage, TMetadata = unknown> = {
     messages: TMessage[];
     chatId: string;
-    trigger: "submit-message" | "regenerate-message" | "preload" | "close";
+    trigger: "submit-message" | "regenerate-message" | "preload" | "close" | "action";
     messageId?: string;
     metadata?: TMetadata;
+    /** Custom action payload when `trigger` is `"action"`. Validated against `actionSchema` on the backend. */
+    action?: unknown;
     /** Whether this run is continuing an existing chat whose previous run ended. */
     continuation?: boolean;
     /** The run ID of the previous run (only set when `continuation` is true). */
@@ -838,6 +840,27 @@ export type ChatStartEvent<TClientData = unknown> = {
     /** Stream writer — write custom `UIMessageChunk` parts to the chat stream. Lazy: no overhead if unused. */
     writer: ChatWriter;
 };
+/**
+ * Event passed to the `hydrateMessages` callback.
+ */
+export type HydrateMessagesEvent<TClientData = unknown, TUIM extends UIMessage = UIMessage> = {
+    /** The unique identifier for the chat session. */
+    chatId: string;
+    /** The turn number (0-indexed). */
+    turn: number;
+    /** The trigger type for this turn. */
+    trigger: "submit-message" | "regenerate-message" | "action";
+    /** Validated incoming UI messages from the wire payload (what the frontend sent). Empty for actions. */
+    incomingMessages: TUIM[];
+    /** The accumulated UI messages before this turn (empty on turn 0). */
+    previousMessages: TUIM[];
+    /** Parsed client data from the transport metadata. */
+    clientData?: TClientData;
+    /** Whether this run is continuing from a previous run. */
+    continuation: boolean;
+    /** The ID of the previous run (if continuation). */
+    previousRunId?: string;
+};
 /**
  * Event passed to the `onValidateMessages` callback.
  */
@@ -851,6 +874,23 @@ export type ValidateMessagesEvent<TUIM extends UIMessage = UIMessage> = {
     /** The trigger type for this turn. */
     trigger: "submit-message" | "regenerate-message" | "preload" | "close";
 };
+/**
+ * Event passed to the `onAction` callback.
+ */
+export type ActionEvent<TAction = unknown, TClientData = unknown, TUIM extends UIMessage = UIMessage> = {
+    /** The parsed and validated action payload. */
+    action: TAction;
+    /** The unique identifier for the chat session. */
+    chatId: string;
+    /** The turn number (0-indexed). */
+    turn: number;
+    /** Parsed client data from the transport metadata. */
+    clientData?: TClientData;
+    /** The accumulated UI messages (after hydration, if set). */
+    uiMessages: TUIM[];
+    /** The accumulated model messages (after hydration, if set). */
+    messages: ModelMessage[];
+};
 /**
  * Event passed to the `onTurnStart` callback.
  */
@@ -1014,7 +1054,7 @@ export type ChatResumeEvent<TClientData = unknown, TUIM extends UIMessage = UIMe
     /** Custom data from the frontend. */
     clientData?: TClientData;
 };
-export type ChatAgentOptions<TIdentifier extends string, TClientDataSchema extends TaskSchema | undefined = undefined, TUIMessage extends UIMessage = UIMessage> = Omit<TaskOptions<TIdentifier, ChatTaskWirePayload<TUIMessage, inferSchemaIn<TClientDataSchema>>, unknown>, "run"> & {
+export type ChatAgentOptions<TIdentifier extends string, TClientDataSchema extends TaskSchema | undefined = undefined, TUIMessage extends UIMessage = UIMessage, TActionSchema extends TaskSchema | undefined = undefined> = Omit<TaskOptions<TIdentifier, ChatTaskWirePayload<TUIMessage, inferSchemaIn<TClientDataSchema>>, unknown>, "run"> & {
     /**
      * Schema for validating `clientData` from the frontend.
      * Accepts Zod, ArkType, Valibot, or any supported schema library.
@@ -1035,6 +1075,42 @@ export type ChatAgentOptions<TIdentifier extends string, TClientDataSchema exten
      * ```
      */
     clientDataSchema?: TClientDataSchema;
+    /**
+     * Schema for validating custom actions sent via `transport.sendAction()`.
+     *
+     * When the frontend sends `trigger: "action"`, the `action` payload is
+     * parsed against this schema before reaching `onAction`. Invalid actions
+     * throw and abort the turn.
+     *
+     * @example
+     * ```ts
+     * import { z } from "zod";
+     *
+     * 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);
+     *   },
+     *   run: async ({ messages, signal }) => { ... },
+     * });
+     * ```
+     */
+    actionSchema?: TActionSchema;
+    /**
+     * Called when the frontend sends a custom action via `transport.sendAction()`.
+     *
+     * Fires after message hydration (if set) but before `onTurnStart` and `run()`.
+     * Use `chat.history.*` to modify the conversation state — the LLM will respond
+     * to the modified state.
+     */
+    onAction?: (event: ActionEvent<[
+        TActionSchema
+    ] extends [TaskSchema] ? inferSchemaOut<TActionSchema> : unknown, inferSchemaOut<TClientDataSchema>, TUIMessage>) => Promise<void> | void;
     /**
      * The run function for the chat task.
      *
@@ -1100,6 +1176,42 @@ export type ChatAgentOptions<TIdentifier extends string, TClientDataSchema exten
      * ```
      */
     onValidateMessages?: (event: ValidateMessagesEvent<TUIMessage>) => TUIMessage[] | Promise<TUIMessage[]>;
+    /**
+     * Load the full message history from your backend on every turn,
+     * replacing the built-in linear accumulator.
+     *
+     * When set, the returned messages become the accumulated state for this turn.
+     * The normal accumulation logic (append for submit, replace for regenerate)
+     * is skipped entirely — the hook is the source of truth.
+     *
+     * After the hook returns, any incoming wire messages with matching IDs are
+     * auto-merged (handles tool approval responses transparently).
+     *
+     * Use cases:
+     * - Backend trust: prevent clients from injecting fabricated history
+     * - Branching conversations (DAGs): load only the active branch
+     * - Rollback/undo: exclude undone messages from history
+     *
+     * @example
+     * ```ts
+     * chat.agent({
+     *   id: "my-chat",
+     *   hydrateMessages: async ({ chatId, trigger, incomingMessages }) => {
+     *     // Persist the new message
+     *     const newMsg = incomingMessages[incomingMessages.length - 1];
+     *     if (newMsg && trigger === "submit-message") {
+     *       await db.chatMessages.create({ chatId, message: newMsg });
+     *     }
+     *     // Return the full authoritative history
+     *     return db.chatMessages.findMany({ where: { chatId } });
+     *   },
+     *   run: async ({ messages, signal }) => {
+     *     return streamText({ model: openai("gpt-4o"), messages, abortSignal: signal });
+     *   },
+     * });
+     * ```
+     */
+    hydrateMessages?: (event: HydrateMessagesEvent<inferSchemaOut<TClientDataSchema>, TUIMessage>) => TUIMessage[] | Promise<TUIMessage[]>;
     /**
      * Called at the start of every turn, after message accumulation and `onChatStart` (turn 0),
      * but before the `run` function executes.
@@ -1394,7 +1506,7 @@ type ChatCustomAgentOptions<TIdentifier extends string, TClientDataSchema extend
     clientDataSchema?: TClientDataSchema;
 };
 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>(options: ChatAgentOptions<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>(options: ChatAgentOptions<TIdentifier, TClientDataSchema, TUIMessage, TActionSchema>): Task<TIdentifier, ChatTaskWirePayload<TUIMessage, inferSchemaIn<TClientDataSchema>>, unknown>;
 /**
  * Optional config for {@link chat.withUIMessage}. `streamOptions` become default
  * static `toUIMessageStream()` settings; inner `chat.agent({ uiMessageStreamOptions })`
@@ -1451,7 +1563,7 @@ export interface ChatBuilder<TUIMessage extends UIMessage = UIMessage, TClientDa
      * and omitted from options. Otherwise, it can still be set directly in options
      * (backwards compatible).
      */
-    agent: [TClientDataSchema] extends [undefined] ? <TId extends string, TInfer extends TaskSchema | undefined = undefined>(options: ChatAgentOptions<TId, TInfer, TUIMessage>) => Task<TId, ChatTaskWirePayload<TUIMessage, inferSchemaIn<TInfer>>, unknown> : <TId extends string>(options: Omit<ChatAgentOptions<TId, TClientDataSchema, TUIMessage>, "clientDataSchema">) => Task<TId, ChatTaskWirePayload<TUIMessage, inferSchemaIn<TClientDataSchema>>, unknown>;
+    agent: [TClientDataSchema] extends [undefined] ? <TId extends string, TInfer extends TaskSchema | undefined = undefined, TAction extends TaskSchema | undefined = undefined>(options: ChatAgentOptions<TId, TInfer, TUIMessage, TAction>) => Task<TId, ChatTaskWirePayload<TUIMessage, inferSchemaIn<TInfer>>, unknown> : <TId extends string, TAction extends TaskSchema | undefined = undefined>(options: Omit<ChatAgentOptions<TId, TClientDataSchema, TUIMessage, TAction>, "clientDataSchema">) => Task<TId, ChatTaskWirePayload<TUIMessage, inferSchemaIn<TClientDataSchema>>, unknown>;
     /**
      * Create a custom agent with manual lifecycle control.
      *
@@ -2145,6 +2257,25 @@ export declare const chat: {
      * converts to `ModelMessage[]` internally.
      */
     setMessages: typeof setChatMessages;
+    /**
+     * Imperative API for modifying the accumulated message history.
+     * Supports rollback, remove, replace, slice, and full replacement.
+     * Can be called from any hook or `run()`.
+     */
+    history: {
+        /** Read the current accumulated UI messages (copy). */
+        all(): UIMessage[];
+        /** Replace all accumulated messages. Same as `chat.setMessages()`. */
+        set(messages: UIMessage[]): void;
+        /** Remove a specific message by ID. */
+        remove(messageId: string): void;
+        /** Keep messages up to and including the given ID (undo/rollback). */
+        rollbackTo(messageId: string): void;
+        /** Replace a specific message by ID (edit). */
+        replace(messageId: string, message: UIMessage): void;
+        /** Keep only messages in the given range. */
+        slice(start: number, end?: number): void;
+    };
     /** Check if it's safe to compact messages (no in-flight tool calls). */
     isCompactionSafe: typeof isCompactionSafe;
     /** Returns a `prepareStep` function that handles context compaction automatically. */