@trigger.dev/sdk 0.0.0-chat-prerelease-20260418083610 → 0.0.0-chat-prerelease-20260419173457

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

@@ -1,12 +1,14 @@
 import { AnyTask, Task, type inferSchemaIn, type inferSchemaOut, type TaskIdentifier, type TaskOptions, type TaskSchema, type TaskRunContext, type TaskWithSchema } from "@trigger.dev/core/v3";
-import type { ModelMessage, ToolSet, UIMessage, UIMessageChunk, UIMessageStreamOptions, LanguageModelUsage } from "ai";
+import type { FinishReason, ModelMessage, ToolSet, UIMessage, UIMessageChunk, UIMessageStreamOptions, LanguageModelUsage } from "ai";
 import { Tool, ToolCallOptions } from "ai";
 import { locals } from "./locals.js";
 import type { ResolvedPrompt } from "./prompt.js";
+import type { ResolvedSkill } from "./skill.js";
 import type { TriggerChatTaskParams, TriggerChatTaskResult } from "./chat.js";
 /** Re-export for typing `ctx` in `chat.agent` hooks without importing `@trigger.dev/core`. */
 export type { TaskRunContext } from "@trigger.dev/core/v3";
 import { CHAT_MESSAGES_STREAM_ID, CHAT_STOP_STREAM_ID } from "./chat-constants.js";
+import { type ChatStorePatchOperation } from "@trigger.dev/core/v3/chat-client";
 export type ToolCallExecutionOptions = {
     toolCallId: string;
     experimental_context?: unknown;
@@ -138,6 +140,29 @@ declare function createChatAccessToken<TTask extends AnyTask>(taskId: TaskIdenti
  */
 export declare const CHAT_STREAM_KEY = "chat";
 export { CHAT_MESSAGES_STREAM_ID, CHAT_STOP_STREAM_ID };
+/**
+ * Listener fired when the store value changes. `operations` is present for
+ * `patch()` updates and absent for `set()` (which is a full snapshot).
+ */
+export type ChatStoreChangeListener<TStore = unknown> = (value: TStore, operations?: ChatStorePatchOperation[]) => void;
+/**
+ * Replace the entire store value with `value`. Emits a `store-snapshot`
+ * chunk on the chat output stream and fires all `onChange` listeners.
+ */
+declare function chatStoreSet<TStore = unknown>(value: TStore): void;
+/**
+ * Apply RFC 6902 JSON Patch operations to the current store value.
+ * Emits a `store-delta` chunk on the chat output stream and fires all
+ * `onChange` listeners with the new value and the operations.
+ */
+declare function chatStorePatch(operations: ChatStorePatchOperation[]): void;
+/** Get the current store value. Returns `undefined` if no value has been set. */
+declare function chatStoreGet<TStore = unknown>(): TStore | undefined;
+/**
+ * Subscribe to store changes for the current run. Returns an
+ * unsubscribe function.
+ */
+declare function chatStoreOnChange<TStore = unknown>(listener: ChatStoreChangeListener<TStore>): () => void;
 /**
  * A stream writer passed to chat lifecycle callbacks (`onPreload`, `onChatStart`,
  * `onTurnStart`, `onTurnComplete`, `onCompacted`).
@@ -181,6 +206,16 @@ export type ChatTaskWirePayload<TMessage extends UIMessage = UIMessage, TMetadat
     previousRunId?: string;
     /** Override idle timeout for this run (seconds). Set by transport.preload(). */
     idleTimeoutInSeconds?: number;
+    /**
+     * Client-side `chat.store` value sent by the transport. Applied at turn
+     * start before `run()` fires, overwriting any in-memory store value on the
+     * agent (last-write-wins).
+     *
+     * The transport queues this via `setStore` / `applyStorePatch` and flushes
+     * it with the next `sendMessage`. On the agent you typically don't read
+     * this directly — it's applied into `chat.store` transparently.
+     */
+    incomingStore?: unknown;
 };
 /**
  * The payload shape passed to the `chatAgent` run function.
@@ -202,8 +237,12 @@ export type ChatTaskPayload<TClientData = unknown> = {
      * - `"submit-message"`: A new user message
      * - `"regenerate-message"`: Regenerate the last assistant response
      * - `"preload"`: Run was preloaded before the first message (only on turn 0)
+     * - `"action"`: A typed action from the frontend (see `actionSchema` + `onAction`).
+     *   The action has already been applied before `run()` fires — check `trigger === "action"`
+     *   to short-circuit the LLM call when an action doesn't need a response.
+     * - `"close"`: The chat session is being closed (internal; `run()` is not called).
      */
-    trigger: "submit-message" | "regenerate-message" | "preload" | "close";
+    trigger: "submit-message" | "regenerate-message" | "preload" | "action" | "close";
     /** The ID of the message to regenerate (only for `"regenerate-message"`) */
     messageId?: string;
     /** Custom data from the frontend (passed via `metadata` on `sendMessage()` or the transport). */
@@ -669,6 +708,21 @@ declare function setChatPrompt(resolved: ResolvedPrompt | string): void;
  * Read the stored prompt. Throws if `chat.prompt.set()` has not been called.
  */
 declare function getChatPrompt(): ChatPromptValue;
+/**
+ * Store resolved skills for the current run. Call from any hook
+ * (`onPreload`, `onChatStart`, `onTurnStart`) or `run()`.
+ */
+declare function setChatSkills(skills: ResolvedSkill[]): void;
+/** Read the stored skills. Returns `undefined` if none set. */
+declare function getChatSkills(): ResolvedSkill[] | undefined;
+/**
+ * Build the three tools we auto-inject into `streamText` when skills are
+ * set: `loadSkill`, `readFile`, `bash`. Scoped per-skill by name.
+ *
+ * Exported so callers can use the same tools outside the auto-wired path
+ * (e.g. in a `chat.createSession` loop with custom streamText).
+ */
+export declare function buildSkillTools(skills: ResolvedSkill[]): Record<string, Tool>;
 /**
  * Options for {@link toStreamTextOptions}.
  */
@@ -687,6 +741,16 @@ export type ToStreamTextOptionsOptions = {
     registry?: {
         languageModel(modelId: string): unknown;
     };
+    /**
+     * User-defined tools to merge alongside the auto-injected skill tools
+     * (`loadSkill`, `readFile`, `bash`). User tools win on name conflicts.
+     *
+     * If you don't pass `tools` here and skills are set, the returned options
+     * will include just the skill tools — spread after any `tools` you pass
+     * directly to `streamText` and they'll be replaced. Easiest: pass all
+     * your tools here.
+     */
+    tools?: Record<string, Tool>;
 };
 /**
  * Returns an options object ready to spread into `streamText()`.
@@ -861,6 +925,37 @@ export type HydrateMessagesEvent<TClientData = unknown, TUIM extends UIMessage =
     /** The ID of the previous run (if continuation). */
     previousRunId?: string;
 };
+/**
+ * Event passed to the `hydrateStore` callback.
+ *
+ * Called at turn start — before `run()` fires and before any incoming store
+ * from the wire payload is applied. Return the authoritative store value
+ * for this turn; it becomes the initial value `chat.store.get()` sees.
+ */
+export type HydrateStoreEvent<TClientData = unknown, TStore = unknown> = {
+    /** 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" | "preload";
+    /**
+     * The in-memory store value from the previous turn of this run
+     * (`undefined` on turn 0 and after continuations).
+     */
+    previousStore: TStore | undefined;
+    /**
+     * The store value the transport sent with this turn, if any.
+     * Usually set by client-side `setStore` / `applyStorePatch`.
+     */
+    incomingStore: TStore | undefined;
+    /** 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.
  */
@@ -979,6 +1074,22 @@ export type TurnCompleteEvent<TClientData = unknown, TUIM extends UIMessage = UI
     usage?: LanguageModelUsage;
     /** Cumulative token usage across all turns in this run (including this turn). */
     totalUsage: LanguageModelUsage;
+    /**
+     * Why the LLM stopped generating this turn:
+     * - `"stop"` — model generated a stop sequence (normal completion)
+     * - `"tool-calls"` — model stopped on one or more tool calls. If any tool
+     *   has no `execute` function (e.g. an `ask_user` HITL tool), the turn is
+     *   paused awaiting user input; inspect `responseMessage.parts` for tool
+     *   parts in `input-available` state to distinguish.
+     * - `"length"` — max tokens reached
+     * - `"content-filter"` — content filter stopped the model
+     * - `"error"` — model errored
+     * - `"other"` — provider-specific reason
+     *
+     * Undefined if the underlying stream didn't provide a finish reason (e.g.
+     * manual `pipeChat()` or an aborted stream).
+     */
+    finishReason?: FinishReason;
 };
 /**
  * Event passed to the `onBeforeTurnComplete` callback.
@@ -1212,6 +1323,43 @@ export type ChatAgentOptions<TIdentifier extends string, TClientDataSchema exten
      * ```
      */
     hydrateMessages?: (event: HydrateMessagesEvent<inferSchemaOut<TClientDataSchema>, TUIMessage>) => TUIMessage[] | Promise<TUIMessage[]>;
+    /**
+     * Load the `chat.store` value for this turn from your backend.
+     *
+     * The store lives in memory on the agent instance for the lifetime of
+     * the run. After a continuation (idle timeout, `chat.requestUpgrade`,
+     * max turns), a new run starts with an empty store — this hook lets
+     * you restore it from your own persistence layer.
+     *
+     * Runs at turn start, before `run()` fires. The returned value replaces
+     * the in-memory store and is emitted as a `store-snapshot` chunk so the
+     * frontend sees the initial value.
+     *
+     * If both `hydrateStore` and `incomingStore` (from the wire payload) are
+     * present, `incomingStore` wins — it represents the client's latest
+     * local state and follows AG-UI's last-write-wins policy.
+     *
+     * @example
+     * ```ts
+     * chat.agent({
+     *   id: "my-chat",
+     *   hydrateStore: async ({ chatId, previousRunId }) => {
+     *     return db.chatStore.findUnique({ where: { chatId } })?.value;
+     *   },
+     *   onTurnComplete: async ({ chatId }) => {
+     *     await db.chatStore.upsert({
+     *       where: { chatId },
+     *       update: { value: chat.store.get() },
+     *       create: { chatId, value: chat.store.get() },
+     *     });
+     *   },
+     *   run: async ({ messages, signal }) => {
+     *     return streamText({ model: openai("gpt-4o"), messages, abortSignal: signal });
+     *   },
+     * });
+     * ```
+     */
+    hydrateStore?: (event: HydrateStoreEvent<inferSchemaOut<TClientDataSchema>>) => unknown | Promise<unknown>;
     /**
      * Called at the start of every turn, after message accumulation and `onChatStart` (turn 0),
      * but before the `run` function executes.
@@ -1744,6 +1892,33 @@ declare function isStopped(): boolean;
  * ```
  */
 declare function requestUpgrade(): void;
+/**
+ * Exit the run after the current turn completes, without waiting for the
+ * next message. Unlike {@link requestUpgrade}, no upgrade-required signal
+ * is sent to the client — the turn finishes normally, `onTurnComplete`
+ * fires, and the loop exits instead of going idle.
+ *
+ * Call from `run()`, `chat.defer()`, `onBeforeTurnComplete`, or
+ * `onTurnComplete` to end the run on your own terms (budget exhausted,
+ * task complete, goal achieved, etc.).
+ *
+ * The next user message on the same `chatId` starts a fresh run via the
+ * normal continuation mechanism.
+ *
+ * @example
+ * ```ts
+ * chat.agent({
+ *   id: "one-shot-agent",
+ *   run: async ({ messages, signal }) => {
+ *     const result = streamText({ model: openai("gpt-4o"), messages, abortSignal: signal });
+ *     // Single-response agent — exit after this turn.
+ *     chat.endRun();
+ *     return result;
+ *   },
+ * });
+ * ```
+ */
+declare function endRun(): void;
 /**
  * Register a promise that runs in the background during the current turn.
  *
@@ -2208,6 +2383,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;
+    /** 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}. */
     cleanupAbortedParts: typeof cleanupAbortedParts;
     /** Register background work that runs in parallel with streaming. See {@link chatDefer}. */
@@ -2224,6 +2401,34 @@ export declare const chat: {
          */
         write(part: UIMessageChunk): void;
     };
+    /**
+     * Typed, bidirectional shared data slot for the chat.
+     *
+     * Use from `chat.agent` hooks and `run()` to share state with the client.
+     * Setting emits a `store-snapshot` chunk; patching emits `store-delta`.
+     * The value persists across turns within the same run, and can be
+     * restored after continuations via the `hydrateStore` config option.
+     *
+     * ```ts
+     * chat.store.set({ plan: ["research", "draft", "review"] });
+     * chat.store.patch([{ op: "replace", path: "/status", value: "done" }]);
+     * const current = chat.store.get();
+     * const off = chat.store.onChange((value, ops) => { ... });
+     * ```
+     */
+    store: {
+        /** Replace the store value. Emits a `store-snapshot` chunk. */
+        set: typeof chatStoreSet;
+        /**
+         * Apply RFC 6902 JSON Patch operations to the current value.
+         * Emits a `store-delta` chunk.
+         */
+        patch: typeof chatStorePatch;
+        /** Read the current store value. Returns `undefined` if never set. */
+        get: typeof chatStoreGet;
+        /** Subscribe to store changes. Returns an unsubscribe function. */
+        onChange: typeof chatStoreOnChange;
+    };
     /** Pre-built input stream for receiving messages from the transport. */
     messages: import("@trigger.dev/core/v3").RealtimeDefinedInputStream<ChatTaskWirePayload<UIMessage<unknown, import("ai").UIDataTypes, import("ai").UITools>, unknown>>;
     /** Create a managed stop signal wired to the stop input stream. See {@link createStopSignal}. */
@@ -2245,6 +2450,20 @@ export declare const chat: {
     prompt: typeof getChatPrompt & {
         set: typeof setChatPrompt;
     };
+    /**
+     * Store and retrieve resolved agent skills for the current run.
+     *
+     * - `chat.skills.set([...])` — store an array of `ResolvedSkill`s
+     * - `chat.skills()` — read the stored skills (returns undefined if none)
+     *
+     * Skills set here are automatically injected into `streamText` by
+     * `chat.toStreamTextOptions()`: skill descriptions land in the system
+     * prompt and `loadSkill` / `readFile` / `bash` tools are added to the
+     * tool set.
+     */
+    skills: typeof getChatSkills & {
+        set: typeof setChatSkills;
+    };
     /**
      * Returns an options object ready to spread into `streamText()`.
      * Reads the stored prompt and returns `{ system, experimental_telemetry, ...config }`.