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

package/dist/commonjs/v3/agentSkillsRuntime.js

@@ -56,25 +56,42 @@ function truncate(s, limit) {
     return s.slice(0, limit) + `\n…[truncated ${s.length - limit} bytes]`;
 }
 /**
- * Path-traversal guard: confirm `relative` resolves inside `root`.
- * Throws if it escapes via `..` or an absolute prefix. Returns the
- * absolute resolved path.
+ * Path-traversal guard: confirm `relative` resolves inside `root`,
+ * even after symlinks are followed. Throws if it escapes via `..`, an
+ * absolute prefix, or a symlink that points outside. Returns the
+ * resolved real path.
+ *
+ * `fs.realpath` only works on paths that exist, so when the resolved
+ * path doesn't exist yet (e.g. writing a new file) we fall back to
+ * the lexical check — a non-existent path can't traverse a symlink
+ * to escape since the symlink doesn't exist either.
  */
-function safeJoinInside(root, relative) {
+async function safeJoinInside(root, relative) {
     if (nodePath.isAbsolute(relative)) {
         throw new Error(`Path must be relative to the skill directory: ${relative}`);
     }
-    const resolved = nodePath.resolve(root, relative);
-    const normalized = nodePath.resolve(root) + nodePath.sep;
-    if (resolved !== nodePath.resolve(root) && !resolved.startsWith(normalized)) {
+    const realRoot = await fs.realpath(nodePath.resolve(root));
+    const resolved = nodePath.resolve(realRoot, relative);
+    let real = resolved;
+    try {
+        real = await fs.realpath(resolved);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            throw err;
+        }
+        // Path doesn't exist yet; fall through with the lexical resolve.
+    }
+    const normalized = realRoot + nodePath.sep;
+    if (real !== realRoot && !real.startsWith(normalized)) {
         throw new Error(`Path escapes the skill directory: ${relative}`);
     }
-    return resolved;
+    return real;
 }
 async function readFileInSkill({ skillPath, relativePath, }) {
     let absolute;
     try {
-        absolute = safeJoinInside(skillPath, relativePath);
+        absolute = await safeJoinInside(skillPath, relativePath);
     }
     catch (err) {
         return { error: err.message };
@@ -100,19 +117,42 @@ async function runBashInSkill({ skillPath, command, abortSignal, }) {
             resolvePromise({ error: err.message });
             return;
         }
+        // Cap stdout/stderr accumulation at the byte budget so an
+        // LLM-generated command (`cat /dev/zero`, `yes`) can't OOM the
+        // worker. Track total seen length separately so the truncation
+        // notice still reports how much was dropped.
         let stdout = "";
         let stderr = "";
+        let stdoutSeen = 0;
+        let stderrSeen = 0;
+        const limit = DEFAULT_BASH_OUTPUT_BYTES;
         child.stdout?.on("data", (chunk) => {
-            stdout += chunk.toString();
+            const text = chunk.toString();
+            stdoutSeen += text.length;
+            if (stdout.length >= limit)
+                return;
+            const remaining = limit - stdout.length;
+            stdout += text.length > remaining ? text.slice(0, remaining) : text;
         });
         child.stderr?.on("data", (chunk) => {
-            stderr += chunk.toString();
+            const text = chunk.toString();
+            stderrSeen += text.length;
+            if (stderr.length >= limit)
+                return;
+            const remaining = limit - stderr.length;
+            stderr += text.length > remaining ? text.slice(0, remaining) : text;
         });
         child.once("close", (code) => {
+            const stdoutFinal = stdoutSeen > stdout.length
+                ? `${stdout}\n…[truncated ${stdoutSeen - stdout.length} bytes]`
+                : stdout;
+            const stderrFinal = stderrSeen > stderr.length
+                ? `${stderr}\n…[truncated ${stderrSeen - stderr.length} bytes]`
+                : stderr;
             resolvePromise({
                 exitCode: code,
-                stdout: truncate(stdout, DEFAULT_BASH_OUTPUT_BYTES),
-                stderr: truncate(stderr, DEFAULT_BASH_OUTPUT_BYTES),
+                stdout: stdoutFinal,
+                stderr: stderrFinal,
             });
         });
         child.once("error", (err) => {

package/dist/commonjs/v3/agentSkillsRuntime.js.map

@@ -1 +1 @@
-{"version":3,"file":"agentSkillsRuntime.js","sourceRoot":"","sources":["../../../src/v3/agentSkillsRuntime.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agentSkillsRuntime.js","sourceRoot":"","sources":["../../../src/v3/agentSkillsRuntime.ts"],"names":[],"mappings":"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"}

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

@@ -24,9 +24,31 @@ export declare const PENDING_MESSAGE_INJECTED_TYPE: "data-pending-message-inject
 /**
  * The wire payload shape sent by `TriggerChatTransport`.
  * Uses `metadata` to match the AI SDK's `ChatRequestOptions` field name.
+ *
+ * Slim wire: at most ONE message per record. The agent runtime
+ * reconstructs prior history at run boot from a durable S3 snapshot +
+ * `session.out` replay (or `hydrateMessages` if registered). The wire is
+ * delta-only — see plan `vivid-humming-bonbon.md`.
  */
 export type ChatTaskWirePayload<TMessage extends UIMessage = UIMessage, TMetadata = unknown> = {
-    messages: TMessage[];
+    /**
+     * The single message being delivered on this trigger. Set for:
+     *   - `submit-message`: the new user message OR a tool-approval-responded
+     *     assistant message (with `state: "approval-responded"` tool parts).
+     *   - `regenerate-message`: omitted (the agent slices its own history).
+     *   - `preload` / `close` / `action`: omitted.
+     *   - `handover-prepare`: omitted (use `headStartMessages` instead).
+     */
+    message?: TMessage;
+    /**
+     * Bespoke escape hatch for `chat.headStart`. The customer's HTTP route
+     * handler ships full `UIMessage[]` history at the very first turn — before
+     * any snapshot exists. The route handler isn't subject to the
+     * `MAX_APPEND_BODY_BYTES` cap on `/in/append` because it goes through the
+     * customer's own HTTP endpoint. Used ONLY by `trigger: "handover-prepare"`.
+     * Ignored on every other trigger.
+     */
+    headStartMessages?: TMessage[];
     chatId: string;
     trigger: "submit-message" | "regenerate-message" | "preload" | "close" | "action"
     /**
@@ -58,16 +80,6 @@ export type ChatTaskWirePayload<TMessage extends UIMessage = UIMessage, TMetadat
      * required once the legacy run-scoped stream path is removed.
      */
     sessionId?: string;
-    /**
-     * 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;
 };
 /**
  * One chunk on the chat input stream. `kind` discriminates the variants —
@@ -148,7 +160,7 @@ export type ChatInputChunk<TMessage extends UIMessage = UIMessage, TMetadata = u
  */
 export type InferChatClientData<TTask extends AnyTask> = TTask extends Task<string, ChatTaskWirePayload<any, infer TMetadata>, any> ? TMetadata : unknown;
 /**
- * Extracts the UI message type from a chat task (wire payload `messages` items).
+ * Extracts the UI message type from a chat task (wire payload `message` items).
  *
  * @example
  * ```ts

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

@@ -1,4 +1,4 @@
-import { AnyTask, type RealtimeDefinedInputStream, type RealtimeDefinedStream, Task, type inferSchemaIn, type inferSchemaOut, type TaskIdentifier, type TaskOptions, type TaskSchema, type TaskRunContext, type TaskWithSchema } from "@trigger.dev/core/v3";
+import { AnyTask, type MachinePresetName, type RealtimeDefinedInputStream, type RealtimeDefinedStream, Task, type inferSchemaIn, type inferSchemaOut, type TaskIdentifier, type TaskOptions, type TaskSchema, type TaskRunContext, type TaskWithSchema } from "@trigger.dev/core/v3";
 import type { FinishReason, ModelMessage, ToolSet, UIMessage, UIMessageChunk, UIMessageStreamOptions, LanguageModelUsage } from "ai";
 import { Tool, ToolCallOptions } from "ai";
 import { locals } from "./locals.js";
@@ -7,7 +7,6 @@ import type { ResolvedSkill } from "./skill.js";
 import { type SessionTriggerConfig } from "@trigger.dev/core/v3";
 /** Re-export for typing `ctx` in `chat.agent` hooks without importing `@trigger.dev/core`. */
 export type { TaskRunContext } from "@trigger.dev/core/v3";
-import { type ChatStorePatchOperation } from "@trigger.dev/core/v3/chat-client";
 export type ToolCallExecutionOptions = {
     toolCallId: string;
     experimental_context?: unknown;
@@ -24,6 +23,9 @@ type ChatTurnContext<TClientData = unknown> = {
     continuation: boolean;
     clientData?: TClientData;
 };
+export declare function __setReadChatSnapshotImplForTests(impl: ReadChatSnapshotImpl | undefined): void;
+export declare function __setWriteChatSnapshotImplForTests(impl: WriteChatSnapshotImpl | undefined): void;
+export declare function __setReplaySessionOutTailImplForTests(impl: ReplaySessionOutTailImpl | undefined): void;
 type ToolResultContent = Array<{
     type: "text";
     text: string;
@@ -132,29 +134,6 @@ export declare const ai: {
  * ```
  */
 declare function createChatAccessToken<TTask extends AnyTask>(taskId: TaskIdentifier<TTask>): Promise<string>;
-/**
- * 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`).
@@ -874,15 +853,68 @@ export type PreloadEvent<TClientData = unknown> = {
     /** Stream writer — write custom `UIMessageChunk` parts to the chat stream. Lazy: no overhead if unused. */
     writer: ChatWriter;
 };
+/**
+ * Event passed to the `onBoot` callback.
+ *
+ * Fires once at the start of every run boot — for the initial first-message
+ * run, for preloaded runs, AND for reactive continuation runs (post-cancel,
+ * post-crash, post-`endRun`, `chat.requestUpgrade`, OOM-retry attempts).
+ * Does NOT fire when the SAME run resumes from snapshot via the
+ * idle-window suspend/resume path — use `onChatResume` for that.
+ *
+ * Use this for per-process setup that needs to run every time a fresh
+ * worker picks up the chat: initialize `chat.local` state, open
+ * per-process resources (DB connections, sandboxes, etc.), or
+ * re-hydrate customer state from your DB on continuation.
+ *
+ * Ordering:
+ *   - First message of a chat: `onBoot` → `onChatStart` → `onTurnStart` → `run()`
+ *   - Preloaded run:           `onBoot` → `onPreload` → (wait) → `onChatStart` → ...
+ *   - Continuation run:        `onBoot` → (wait for first message) → `onTurnStart` → `run()`
+ *                              (`onChatStart` does NOT fire on continuation runs)
+ */
+export type BootEvent<TClientData = unknown> = {
+    /** 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;
+    /** A scoped access token for this chat run. Persist this for frontend reconnection. */
+    chatAccessToken: string;
+    /** Custom data from the frontend (passed via `metadata` on `sendMessage()` or the transport). */
+    clientData: TClientData;
+    /**
+     * True when this run is a reactive continuation — the prior run died
+     * (cancel / crash / `endRun` / `requestUpgrade` / OOM retry) and this
+     * fresh worker is taking over the chat. Branch on this to re-load
+     * customer-owned state from your DB.
+     */
+    continuation: boolean;
+    /** Public id of the prior run when `continuation` is true. */
+    previousRunId?: string;
+    /** Whether this run was triggered as a preload. */
+    preloaded: boolean;
+};
 /**
  * Event passed to the `onChatStart` callback.
+ *
+ * Fires exactly once per chat, on the very first user message of the chat's
+ * lifetime. Does NOT fire on continuation runs (post-`endRun`,
+ * post-waitpoint-timeout, `chat.requestUpgrade`) or on OOM-retry attempts —
+ * those are runs of an already-started chat.
  */
 export type ChatStartEvent<TClientData = unknown> = {
     /** Task run context — same as `task({ run })` second-argument `ctx`. */
     ctx: TaskRunContext;
     /** The unique identifier for the chat session. */
     chatId: string;
-    /** The initial model-ready messages for this conversation. */
+    /**
+     * The initial model-ready messages for this conversation. Typically just
+     * the first user message (or empty if `chat.headStart` is in play and the
+     * seed message is supplied elsewhere). Since this hook only fires for the
+     * chat's very first message, there's no prior history to load here.
+     */
     messages: ModelMessage[];
     /** Custom data from the frontend (passed via `metadata` on `sendMessage()` or the transport). */
     clientData: TClientData;
@@ -890,9 +922,17 @@ export type ChatStartEvent<TClientData = unknown> = {
     runId: string;
     /** A scoped access token for this chat run. Persist this for frontend reconnection. */
     chatAccessToken: string;
-    /** Whether this run is continuing an existing chat (previous run timed out or was cancelled). False for brand new chats. */
+    /**
+     * @deprecated Always `false` — `onChatStart` no longer fires on continuation
+     * runs. Kept for backward compatibility; remove your `continuation` checks
+     * from `onChatStart` and rely on the contract (this hook fires exactly once
+     * per chat, on the very first message).
+     */
     continuation: boolean;
-    /** The run ID of the previous run (only set when `continuation` is true). */
+    /**
+     * @deprecated Always `undefined` — `onChatStart` no longer fires on
+     * continuation runs.
+     */
     previousRunId?: string;
     /** Whether this run was preloaded before the first message. */
     preloaded: boolean;
@@ -920,37 +960,6 @@ 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.
  */
@@ -1109,6 +1118,23 @@ export type ChatSuspendEvent<TClientData = unknown, TUIM extends UIMessage = UIM
     runId: string;
     /** Custom data from the frontend. */
     clientData?: TClientData;
+} | {
+    /**
+     * Suspend is happening on a continuation run that booted with no incoming
+     * message (post-`endRun`, post-waitpoint-timeout, etc.) and is waiting
+     * for the next session.in record before running any turn. Distinct from
+     * `phase: "preload"` — the chat already started; `onPreload` has not
+     * fired and will not fire on this run.
+     */
+    phase: "continuation";
+    /** Task run context. */
+    ctx: TaskRunContext;
+    /** The chat session ID. */
+    chatId: string;
+    /** The Trigger.dev run ID. */
+    runId: string;
+    /** Custom data from the frontend. */
+    clientData?: TClientData;
 } | {
     /** Suspend is happening after a completed turn, waiting for the next message. */
     phase: "turn";
@@ -1142,6 +1168,22 @@ export type ChatResumeEvent<TClientData = unknown, TUIM extends UIMessage = UIMe
     runId: string;
     /** Custom data from the frontend. */
     clientData?: TClientData;
+} | {
+    /**
+     * First message arrived after continuation-wait suspension. Distinct
+     * from `phase: "preload"` — the chat already started; this is a new
+     * run picking up after a prior run ended (`endRun`, waitpoint timeout,
+     * etc.).
+     */
+    phase: "continuation";
+    /** Task run context. */
+    ctx: TaskRunContext;
+    /** The chat session ID. */
+    chatId: string;
+    /** The Trigger.dev run ID. */
+    runId: string;
+    /** Custom data from the frontend. */
+    clientData?: TClientData;
 } | {
     /** Next message arrived after turn suspension. */
     phase: "turn";
@@ -1160,7 +1202,40 @@ 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, TActionSchema extends TaskSchema | undefined = undefined> = 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" | "retry"> & {
+    /**
+     * Fallback machine preset to use when an attempt fails with an
+     * out-of-memory (OOM) error. Setting this enables a single OOM retry:
+     * the next attempt boots on the larger machine, and the chat picks
+     * up via the standard continuation path (same `chatId` / Session,
+     * accumulator rebuilds via `hydrateMessages` or post-`onTurnStart`
+     * persisted state).
+     *
+     * Set `machine` (top-level `TaskOptions`) to control the *default*
+     * machine the agent runs on. `oomMachine` is the *retry-only* swap.
+     *
+     * Note: an OOM retry restarts the entire turn from the top — the
+     * model call and any in-flight tool executes re-run on the larger
+     * machine. Make tool executes idempotent or persist results before
+     * returning if you can't tolerate re-execution.
+     *
+     * Generic `retry` options are not exposed on `chat.agent` because
+     * arbitrary retries against an LLM-driven loop tend to be expensive
+     * and side-effecting. If you need richer retry semantics, drop down
+     * to `chat.task` (the raw primitive).
+     *
+     * @example
+     * ```ts
+     * chat.agent({
+     *   id: "my-chat",
+     *   machine: "small-1x",
+     *   oomMachine: "medium-2x",
+     *   run: async ({ messages, signal }) =>
+     *     streamText({ model, messages, abortSignal: signal }),
+     * });
+     * ```
+     */
+    oomMachine?: MachinePresetName;
     /**
      * Schema for validating `clientData` from the frontend.
      * Accepts Zod, ArkType, Valibot, or any supported schema library.
@@ -1233,6 +1308,35 @@ export type ChatAgentOptions<TIdentifier extends string, TClientDataSchema exten
      * the stream is automatically piped to the frontend.
      */
     run: (payload: ChatTaskRunPayload<inferSchemaOut<TClientDataSchema>>) => Promise<unknown>;
+    /**
+     * Called once at the start of every run boot — for the initial run, for
+     * preloaded runs, AND for reactive continuation runs (post-cancel /
+     * crash / `endRun` / `requestUpgrade` / OOM retry).
+     *
+     * Use this for per-process setup that needs to run every time a fresh
+     * worker picks up the chat: initialize `chat.local` state, open
+     * per-process resources, or re-hydrate customer state from your DB
+     * on continuation. Branch on `continuation` to decide whether to load
+     * existing state vs. start fresh.
+     *
+     * Fires BEFORE `onPreload` (preloaded path) and `onChatStart`
+     * (first-message path), so `chat.local` is safe to read in those hooks.
+     *
+     * Does NOT fire when the same run resumes from snapshot via the
+     * idle-window suspend/resume path — use `onChatResume` for that.
+     *
+     * @example
+     * ```ts
+     * onBoot: async ({ chatId, clientData, continuation }) => {
+     *   const user = await db.user.findFirst({ where: { id: clientData.userId } });
+     *   userContext.init({ name: user.name, plan: user.plan });
+     *   if (continuation) {
+     *     // re-hydrate any per-chat in-memory state from your DB
+     *   }
+     * }
+     * ```
+     */
+    onBoot?: (event: BootEvent<inferSchemaOut<TClientDataSchema>>) => Promise<void> | void;
     /**
      * Called when a preloaded run starts, before the first message arrives.
      *
@@ -1249,9 +1353,16 @@ export type ChatAgentOptions<TIdentifier extends string, TClientDataSchema exten
      */
     onPreload?: (event: PreloadEvent<inferSchemaOut<TClientDataSchema>>) => Promise<void> | void;
     /**
-     * Called on the first turn (turn 0) of a new run, before the `run` function executes.
+     * Called exactly once per chat, on the very first user message of the
+     * chat's lifetime. Does NOT fire on continuation runs (post-`endRun`,
+     * post-waitpoint-timeout, `chat.requestUpgrade`) or on OOM-retry attempts —
+     * those are runs of an already-started chat.
      *
-     * Use this to create the chat record in your database when a new conversation starts.
+     * Use this for one-time chat-setup work — creating the Chat DB row,
+     * initializing per-chat in-memory state, minting resources tied to the
+     * chat's lifetime. Safe to assume no prior history exists here.
+     *
+     * For per-turn work, use `onTurnStart`.
      *
      * @example
      * ```ts
@@ -1323,43 +1434,6 @@ 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.
@@ -1688,6 +1762,8 @@ export interface ChatBuilder<TUIMessage extends UIMessage = UIMessage, TClientDa
     withClientData<TSchema extends TaskSchema>(config: {
         schema: TSchema;
     }): 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>;
     /** Register a builder-level `onPreload` hook. Runs before the task-level hook if both are set. */
     onPreload(fn: (event: PreloadEvent<inferSchemaOut<TClientDataSchema>>) => Promise<void> | void): ChatBuilder<TUIMessage, TClientDataSchema>;
     /** Register a builder-level `onChatStart` hook. Runs before the task-level hook if both are set. */
@@ -2255,8 +2331,11 @@ export type ChatLocal<T extends Record<string, unknown>> = T & {
 /**
  * Creates a per-run typed data object accessible from anywhere during task execution.
  *
- * Declare at module level, then initialize inside a lifecycle hook (e.g. `onChatStart`)
- * using `chat.initLocal()`. Properties are accessible directly via the Proxy.
+ * Declare at module level, then initialize inside `onBoot` (recommended — fires
+ * on every fresh worker including continuation runs). Do NOT initialize in
+ * `onChatStart` alone: `onChatStart` only fires on the chat's very first
+ * message, so `chat.local` would be uninitialized on continuation runs and
+ * `run()` would throw.
  *
  * Multiple locals can coexist — each gets its own isolated run-scoped storage.
  *
@@ -2273,7 +2352,7 @@ export type ChatLocal<T extends Record<string, unknown>> = T & {
  *
  * export const myChat = chat.agent({
  *   id: "my-chat",
- *   onChatStart: async ({ clientData }) => {
+ *   onBoot: async ({ clientData }) => {
  *     const prefs = await db.prefs.findUnique({ where: { userId: clientData.userId } });
  *     userPrefs.init(prefs ?? { theme: "dark", language: "en" });
  *     gameState.init({ score: 0, streak: 0 });
@@ -2314,6 +2393,22 @@ export type { InferChatClientData, InferChatUIMessage } from "./ai-shared.js";
 /**
  * Options for {@link createChatStartSessionAction}.
  */
+/**
+ * Discriminator for per-endpoint `baseURL` / `fetch` callbacks on
+ * `createChatStartSessionAction`.
+ *
+ * - `"sessions"` — `POST /api/v1/sessions` (session create + first run trigger).
+ * - `"auth"` — `POST /api/v1/auth/jwt/claims` (only fired when
+ *   `tokenTTL` is set; otherwise the publicAccessToken from session create
+ *   is reused as-is).
+ */
+export type ChatStartSessionEndpoint = "sessions" | "auth";
+export type ChatStartSessionEndpointContext = {
+    endpoint: ChatStartSessionEndpoint;
+    chatId: string;
+};
+export type ChatStartSessionBaseURLResolver = (ctx: ChatStartSessionEndpointContext) => string;
+export type ChatStartSessionFetchOverride = (url: string, init: RequestInit, ctx: ChatStartSessionEndpointContext) => Promise<Response>;
 export type CreateChatStartSessionActionOptions = {
     /** TTL for the session-scoped public access token. @default "1h" */
     tokenTTL?: string | number | Date;
@@ -2322,6 +2417,21 @@ export type CreateChatStartSessionActionOptions = {
      * Per-call `params.triggerConfig` shallow-merges on top.
      */
     triggerConfig?: Partial<SessionTriggerConfig>;
+    /**
+     * Override the Trigger.dev API base URL. String applies to both
+     * `/api/v1/sessions` and `/api/v1/auth/jwt/claims`; function picks per
+     * endpoint. When unset, falls back to `apiClientManager.baseURL`
+     * (typically the `TRIGGER_API_URL` env var). Set this to route session
+     * create through a trusted edge proxy that injects server-side signal
+     * into `basePayload.metadata` before forwarding upstream.
+     */
+    baseURL?: string | ChatStartSessionBaseURLResolver;
+    /**
+     * Per-request fetch override. Receives the resolved URL, RequestInit,
+     * and endpoint context. Use for header injection, proxy routing, or
+     * custom retry. Applies to both session-create and JWT-claims POSTs.
+     */
+    fetch?: ChatStartSessionFetchOverride;
 };
 /**
  * Params for the function returned by {@link createChatStartSessionAction}.
@@ -2432,34 +2542,6 @@ 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: RealtimeDefinedInputStream<ChatTaskWirePayload>;
     /** Create a managed stop signal wired to the stop input stream. See {@link createStopSignal}. */