@trigger.dev/sdk 4.5.0-rc.7 → 4.5.1

package/dist/commonjs/v3/ai-shared.js

@@ -128,10 +128,7 @@ function slimSubmitMessageForWire(message) {
     if (message.role !== "assistant")
         return message;
     const parts = (message.parts ?? []);
-    const advancedToolParts = parts.filter((p) => p &&
-        typeof p === "object" &&
-        isToolPartType(p.type) &&
-        isWireAdvanceableToolState(p.state));
+    const advancedToolParts = parts.filter((p) => p && typeof p === "object" && isToolPartType(p.type) && isWireAdvanceableToolState(p.state));
     if (advancedToolParts.length === 0)
         return message;
     const slimParts = advancedToolParts.map((p) => {

package/dist/commonjs/v3/ai-shared.js.map

@@ -1 +1 @@
-{"version":3,"file":"ai-shared.js","sourceRoot":"","sources":["../../../src/v3/ai-shared.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ai-shared.js","sourceRoot":"","sources":["../../../src/v3/ai-shared.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AA4OH,sDAiBC;AAoDD,4DAkCC;AA9UD;;;GAGG;AACU,QAAA,6BAA6B,GAAG,+BAAwC,CAAC;AA6LtF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,SAAgB,qBAAqB,CACnC,MAAc,EACd,KAGC;IAED,IAAI,KAAK,CAAC,OAAO,KAAK,gBAAgB;QAAE,OAAO,KAAK,CAAC;IACrD,IAAI,KAAK,CAAC,gBAAgB,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,MAAM,GAAG,KAAK,CAAC,gBAAgB,CAAC,KAAK,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACzE,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1B,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;QACd,MAAM,WAAW,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,EAAE,CAAC,CAAC;QAChE,IAAI,WAAW,KAAK,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;IACvC,CAAC;IACD,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACpB,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,SAAS,0BAA0B,CACjC,KAAc;IAEd,OAAO,CACL,KAAK,KAAK,kBAAkB;QAC5B,KAAK,KAAK,cAAc;QACxB,KAAK,KAAK,oBAAoB;QAC9B,KAAK,KAAK,eAAe,CAC1B,CAAC;AACJ,CAAC;AAED,2EAA2E;AAC3E,SAAS,cAAc,CAAC,IAAa;IACnC,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,IAAI,KAAK,cAAc,CAAC,CAAC;AAC3F,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,SAAgB,wBAAwB,CAAqC,OAAa;IACxF,IAAI,CAAC,OAAO;QAAE,OAAO,OAAO,CAAC;IAC7B,IAAI,OAAO,CAAC,IAAI,KAAK,WAAW;QAAE,OAAO,OAAO,CAAC;IACjD,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAU,CAAC;IAC7C,MAAM,iBAAiB,GAAG,KAAK,CAAC,MAAM,CACpC,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,0BAA0B,CAAC,CAAC,CAAC,KAAK,CAAC,CAC9F,CAAC;IACF,IAAI,iBAAiB,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IACnD,MAAM,SAAS,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE;QACjD,MAAM,IAAI,GAA4B;YACpC,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,UAAU,EAAE,CAAC,CAAC,UAAU;YACxB,KAAK,EAAE,CAAC,CAAC,KAAK;SACf,CAAC;QACF,IAAI,CAAC,CAAC,IAAI,KAAK,cAAc,IAAI,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAChE,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC;QAC7B,CAAC;QACD,IAAI,CAAC,CAAC,KAAK,KAAK,kBAAkB,EAAE,CAAC;YACnC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;YACvB,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS;gBAAE,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC;QAC3D,CAAC;aAAM,IAAI,CAAC,CAAC,KAAK,KAAK,cAAc,EAAE,CAAC;YACtC,IAAI,CAAC,CAAC,SAAS,KAAK,SAAS;gBAAE,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC;YAC5D,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS;gBAAE,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC;QAC3D,CAAC;aAAM,IAAI,CAAC,CAAC,KAAK,KAAK,oBAAoB,IAAI,CAAC,CAAC,KAAK,KAAK,eAAe,EAAE,CAAC;YAC3E,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS;gBAAE,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC;QAC3D,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;IACH,OAAO;QACL,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,KAAK,EAAE,SAAS;KACE,CAAC;AACvB,CAAC"}

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

@@ -1,5 +1,9 @@
-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 AnyTask, type Task, type ChatSnapshotV1, type ApiClientConfiguration, type inferSchemaIn, type inferSchemaOut, type MachinePresetName, type RealtimeDefinedInputStream, type RealtimeDefinedStream, type SessionTriggerConfig, type TaskIdentifier, type TaskOptions, type TaskRunContext, type TaskSchema, type TaskWithSchema } from "@trigger.dev/core/v3";
 import type { FinishReason, LanguageModelUsage, ModelMessage, ProviderMetadata, Tool, ToolSet, UIMessage, UIMessageChunk, UIMessageStreamOptions } from "ai";
+import { type ChatInputChunk, type ChatTaskWirePayload, type InferChatClientData, type InferChatUIMessage, type InferChatUIMessageFromTools, PENDING_MESSAGE_INJECTED_TYPE, upsertIncomingMessage } from "./ai-shared.js";
+import { locals } from "./locals.js";
+import type { ResolvedPrompt } from "./prompt.js";
+import type { ResolvedSkill } from "./skill.js";
 type ToolCallOptions = {
     toolCallId: string;
     messages?: ModelMessage[];
@@ -7,10 +11,6 @@ type ToolCallOptions = {
     experimental_context?: unknown;
     context?: unknown;
 };
-import { locals } from "./locals.js";
-import type { ResolvedPrompt } from "./prompt.js";
-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";
 export type ToolCallExecutionOptions = {
@@ -171,8 +171,6 @@ export type ChatWriter = {
     /** Merge another stream's chunks into the chat stream. */
     merge(stream: ReadableStream<UIMessageChunk>): void;
 };
-import type { ChatTaskWirePayload } from "./ai-shared.js";
-export type { ChatTaskWirePayload, ChatInputChunk } from "./ai-shared.js";
 /**
  * The payload shape passed to the `chatAgent` run function.
  *
@@ -520,7 +518,8 @@ export type PendingMessagesOptions<TUIM extends UIMessage = UIMessage> = {
  * between tool-call steps. The frontend can match on this to render
  * injection points inline in the assistant response.
  */
-export { PENDING_MESSAGE_INJECTED_TYPE, upsertIncomingMessage } from "./ai-shared.js";
+export { PENDING_MESSAGE_INJECTED_TYPE, upsertIncomingMessage };
+export type { InferChatClientData, InferChatUIMessage, InferChatUIMessageFromTools };
 /**
  * Event passed to the `prepareMessages` hook.
  */
@@ -2795,8 +2794,6 @@ declare function chatLocal<T extends Record<string, unknown>>(options: {
  * // { model?: string; userId: string }
  * ```
  */
-import type { InferChatClientData } from "./ai-shared.js";
-export type { InferChatClientData, InferChatUIMessage, InferChatUIMessageFromTools, } from "./ai-shared.js";
 /**
  * Options for {@link createChatStartSessionAction}.
  */
@@ -2839,6 +2836,12 @@ export type CreateChatStartSessionActionOptions = {
      * custom retry. Applies to both session-create and JWT-claims POSTs.
      */
     fetch?: ChatStartSessionFetchOverride;
+    /**
+     * API client config (baseURL / accessToken) to scope this action to a specific
+     * environment, for callers that can't set a global `TRIGGER_SECRET_KEY`. The
+     * returned action runs under this config.
+     */
+    apiClient?: ApiClientConfiguration;
 };
 /**
  * Params for the function returned by {@link createChatStartSessionAction}.

package/dist/commonjs/v3/ai.js

@@ -15,8 +15,11 @@ exports.buildSkillTools = buildSkillTools;
 const v3_1 = require("@trigger.dev/core/v3");
 // Runtime VALUES go through the ESM/CJS shim so the CJS build can `require`
 // ESM-only `ai@7` (see ../imports/ai-runtime.ts).
-const ai_runtime_js_1 = require("../imports/ai-runtime.js");
 const api_1 = require("@opentelemetry/api");
+const ai_runtime_js_1 = require("../imports/ai-runtime.js");
+const ai_shared_js_1 = require("./ai-shared.js");
+Object.defineProperty(exports, "PENDING_MESSAGE_INJECTED_TYPE", { enumerable: true, get: function () { return ai_shared_js_1.PENDING_MESSAGE_INJECTED_TYPE; } });
+Object.defineProperty(exports, "upsertIncomingMessage", { enumerable: true, get: function () { return ai_shared_js_1.upsertIncomingMessage; } });
 const auth_js_1 = require("./auth.js");
 const locals_js_1 = require("./locals.js");
 const metadata_js_1 = require("./metadata.js");
@@ -29,11 +32,10 @@ const metadata_js_1 = require("./metadata.js");
 // never touches `ai.ts`'s module graph, so the `node:*` builtins
 // pulled in transitively here never reach a client chunk.
 const agentSkillsRuntime_js_1 = require("./agentSkillsRuntime.js");
-const streams_js_1 = require("./streams.js");
+const aiAutoTelemetry_js_1 = require("./aiAutoTelemetry.js");
 const sessions_js_1 = require("./sessions.js");
 const shared_js_1 = require("./shared.js");
-const aiAutoTelemetry_js_1 = require("./aiAutoTelemetry.js");
-const v3_2 = require("@trigger.dev/core/v3");
+const streams_js_1 = require("./streams.js");
 const tracer_js_1 = require("./tracer.js");
 const METADATA_KEY = "tool.execute.options";
 /**
@@ -155,7 +157,9 @@ async function seedSessionInResumeCursorForCustomLoop(payload) {
         }
     }
     catch (error) {
-        v3_1.logger.warn("chat session: session.in resume cursor lookup failed; old messages may replay", { error: error instanceof Error ? error.message : String(error) });
+        v3_1.logger.warn("chat session: session.in resume cursor lookup failed; old messages may replay", {
+            error: error instanceof Error ? error.message : String(error),
+        });
     }
 }
 let readChatSnapshotImpl;
@@ -1241,8 +1245,7 @@ const handoverInput = {
             const result = await getChatSession().in.waitWithIdleTimeout(options);
             if (!result.ok)
                 return result;
-            if (result.output.kind === "handover" ||
-                result.output.kind === "handover-skip") {
+            if (result.output.kind === "handover" || result.output.kind === "handover-skip") {
                 return { ok: true, output: result.output };
             }
             // Other kinds (message, stop) are not expected during handover-prepare.
@@ -1898,19 +1901,6 @@ const chatUpgradeRequestedKey = locals_js_1.locals.create("chat.upgradeRequested
 const chatEndRunRequestedKey = locals_js_1.locals.create("chat.endRunRequested");
 /** @internal */
 const chatAgentCompactionKey = locals_js_1.locals.create("chat.agentCompaction");
-/**
- * The data part type used to signal that pending messages were injected
- * between tool-call steps. The frontend can match on this to render
- * injection points inline in the assistant response.
- */
-// `PENDING_MESSAGE_INJECTED_TYPE` lives in `./ai-shared.ts` so the chat
-// React hooks (`@trigger.dev/sdk/chat/react`) can import it without
-// dragging `ai.ts` into the browser graph. Re-exported here so
-// `@trigger.dev/sdk/ai` consumers still see it.
-var ai_shared_js_1 = require("./ai-shared.js");
-Object.defineProperty(exports, "PENDING_MESSAGE_INJECTED_TYPE", { enumerable: true, get: function () { return ai_shared_js_1.PENDING_MESSAGE_INJECTED_TYPE; } });
-Object.defineProperty(exports, "upsertIncomingMessage", { enumerable: true, get: function () { return ai_shared_js_1.upsertIncomingMessage; } });
-const ai_shared_js_2 = require("./ai-shared.js");
 /** @internal */
 const chatPendingMessagesKey = locals_js_1.locals.create("chat.pendingMessages");
 /** @internal */
@@ -1955,6 +1945,55 @@ function isStepBoundarySafe(step) {
         .map((p) => p.toolCallId));
     return ![...callIds].some((id) => !settledIds.has(id));
 }
+/**
+ * True when a model message is a `tool` message carrying a
+ * `tool-approval-response` part — the trailing row a head-start handover
+ * reshapes a pending first-turn tool call into. AI SDK's `collectToolApprovals`
+ * only inspects the conversation's last message, so this row must survive to
+ * `streamText` intact for the agent to execute the handed-over call.
+ * @internal
+ */
+function hasToolApprovalResponse(message) {
+    return (message?.role === "tool" &&
+        Array.isArray(message.content) &&
+        message.content.some((part) => part != null &&
+            typeof part === "object" &&
+            part.type === "tool-approval-response"));
+}
+/**
+ * Keep a head-start handover's tool-approval tail intact across `prepareMessages`.
+ *
+ * The handover reshapes the warm step-1's pending tool call into AI SDK's
+ * tool-approval round: a `tool-approval-request` on the assistant plus a
+ * trailing `tool` message with `tool-approval-response { approved: true }`. The
+ * agent's next `streamText` runs `collectToolApprovals`, which ONLY looks at the
+ * last message — so that tool row must stay last and unmodified for the pending
+ * call to execute. A user `prepareMessages` hook that rewrites or drops the last
+ * message (e.g. rolling a provider cache breakpoint onto it) silently breaks the
+ * resume: the agent sends a bare `tool_use` and the turn dies with
+ * "tool_use ids were found without tool_result". If the hook's input ended with
+ * that approval tail, re-assert the original tail as the last message.
+ *
+ * No-op for every normal turn — only fires when the input genuinely ended with a
+ * pending tool-approval response (i.e. a head-start resume).
+ * @internal
+ */
+function preserveToolApprovalTail(original, prepared) {
+    const originalTail = original[original.length - 1];
+    if (!hasToolApprovalResponse(originalTail))
+        return prepared;
+    // Hook left the exact tail object in place — nothing to do.
+    if (prepared[prepared.length - 1] === originalTail)
+        return prepared;
+    // Otherwise drop only the trailing approval tail the hook produced (the
+    // original moved, or a rewritten copy) and re-append the original so it is
+    // last and intact. Older approval rounds deeper in history must survive.
+    const withoutMovedOriginal = prepared.filter((m) => m !== originalTail);
+    while (hasToolApprovalResponse(withoutMovedOriginal[withoutMovedOriginal.length - 1])) {
+        withoutMovedOriginal.pop();
+    }
+    return [...withoutMovedOriginal, originalTail];
+}
 /**
  * Apply the prepareMessages hook if one is set in locals.
  * @internal
@@ -1964,7 +2003,7 @@ async function applyPrepareMessages(messages, reason) {
     if (!hook)
         return messages;
     const turnCtx = locals_js_1.locals.get(chatTurnContextKey);
-    return tracer_js_1.tracer.startActiveSpan("prepareMessages()", async () => {
+    const prepared = await tracer_js_1.tracer.startActiveSpan("prepareMessages()", async () => {
         return hook({
             messages,
             reason,
@@ -1980,6 +2019,9 @@ async function applyPrepareMessages(messages, reason) {
             "chat.prepareMessages.messageCount": messages.length,
         },
     });
+    // A user hook must never be able to break the head-start handover resume by
+    // disturbing the trailing tool-approval row (see preserveToolApprovalTail).
+    return preserveToolApprovalTail(messages, prepared);
 }
 /**
  * Resolve the `tools` option into a concrete `ToolSet` and cache it in locals so
@@ -2250,7 +2292,7 @@ async function drainSteeringQueue(config, messages, steps, queueOverride) {
         .filter((p) => p.type === "text")
         .map((p) => p.text)
         .join("") || "");
-    const previewText = messageTexts.length === 1 ? messageTexts[0].slice(0, 80) : `${queue.length} messages`;
+    const _previewText = messageTexts.length === 1 ? messageTexts[0].slice(0, 80) : `${queue.length} messages`;
     return tracer_js_1.tracer.startActiveSpan("pending message injected", async () => {
         // Transform the batch — default: concatenate all pre-converted model messages
         const injected = config.prepare
@@ -2271,7 +2313,7 @@ async function drainSteeringQueue(config, messages, steps, queueOverride) {
                     collapsed: true,
                     execute: ({ write }) => {
                         write({
-                            type: ai_shared_js_2.PENDING_MESSAGE_INJECTED_TYPE,
+                            type: ai_shared_js_1.PENDING_MESSAGE_INJECTED_TYPE,
                             id: (0, ai_runtime_js_1.generateId)(),
                             data: {
                                 messageIds: uiMessages.map((m) => m.id),
@@ -2764,7 +2806,7 @@ function chatCustomAgent(options) {
     // Register clientDataSchema so the CLI converts it to JSONSchema
     // and stores it as payloadSchema — used by the Playground UI
     if (clientDataSchema) {
-        v3_2.resourceCatalog.updateTaskMetadata(options.id, {
+        v3_1.resourceCatalog.updateTaskMetadata(options.id, {
             schema: clientDataSchema,
         });
     }
@@ -2928,7 +2970,9 @@ function chatAgent(options) {
                     const replayOutPhase = async () => {
                         const replayOutStart = Date.now();
                         try {
-                            const replayResult = await replaySessionOutTail(sessionIdForSnapshot, { lastEventId: bootSnapshot?.lastOutEventId });
+                            const replayResult = await replaySessionOutTail(sessionIdForSnapshot, {
+                                lastEventId: bootSnapshot?.lastOutEventId,
+                            });
                             replayedSettled = replayResult.settled;
                             replayedPartial = replayResult.partial;
                             replayedPartialRaw = replayResult.partialRaw;
@@ -3025,9 +3069,7 @@ function chatAgent(options) {
             //    crashed / was canceled / requested upgrade
             //  - Snapshot exists at all (catches edge cases where the wire
             //    didn't set `continuation` but a snapshot indicates prior turns)
-            const needsResumeCursor = ctx.attempt.number > 1 ||
-                payload.continuation === true ||
-                bootSnapshot !== undefined;
+            const needsResumeCursor = ctx.attempt.number > 1 || payload.continuation === true || bootSnapshot !== undefined;
             if (needsResumeCursor) {
                 try {
                     // Reuse the cursor the boot block already resolved (snapshot
@@ -3374,9 +3416,7 @@ function chatAgent(options) {
                     // Wait for the first real message — task-level idle settings win over
                     // `transport.preload(..., { idleTimeoutInSeconds })` / wire payload so
                     // `chat.agent({ idleTimeoutInSeconds, preloadIdleTimeoutInSeconds })` is authoritative.
-                    const effectivePreloadIdleTimeout = preloadIdleTimeoutInSeconds ??
-                        idleTimeoutInSeconds ??
-                        payload.idleTimeoutInSeconds;
+                    const effectivePreloadIdleTimeout = preloadIdleTimeoutInSeconds ?? idleTimeoutInSeconds ?? payload.idleTimeoutInSeconds;
                     const effectivePreloadTimeout = metadata_js_1.metadata.get(TURN_TIMEOUT_METADATA_KEY) ??
                         preloadTimeout ??
                         turnTimeout;
@@ -3621,7 +3661,9 @@ function chatAgent(options) {
                         if (lastUserMessage) {
                             turnAttributes["chat.user_message"] = lastUserMessage;
                             // Show a truncated preview of the user message as an accessory
-                            const preview = lastUserMessage.length > 80 ? lastUserMessage.slice(0, 80) + "..." : lastUserMessage;
+                            const preview = lastUserMessage.length > 80
+                                ? lastUserMessage.slice(0, 80) + "..."
+                                : lastUserMessage;
                             Object.assign(turnAttributes, (0, v3_1.accessoryAttributes)({
                                 items: [{ text: preview, variant: "normal" }],
                                 style: "codepath",
@@ -3908,8 +3950,7 @@ function chatAgent(options) {
                                     if (currentWirePayload.trigger === "submit-message" &&
                                         cleanedUIMessages.length > 0) {
                                         const lastUI = cleanedUIMessages[cleanedUIMessages.length - 1];
-                                        const matchedExisting = lastUI.id !== undefined &&
-                                            previouslyKnownMessageIds.has(lastUI.id);
+                                        const matchedExisting = lastUI.id !== undefined && previouslyKnownMessageIds.has(lastUI.id);
                                         if (!matchedExisting) {
                                             turnNewUIMessages.push(lastUI);
                                             const lastModel = (await toModelMessages([lastUI]))[0];
@@ -4244,7 +4285,8 @@ function chatAgent(options) {
                                     // We call toUIMessageStream ourselves to attach onFinish for response capture.
                                     // Pass originalMessages so the AI SDK reuses message IDs across turns
                                     // (e.g. for tool approval continuations / HITL flows).
-                                    if ((locals_js_1.locals.get(chatPipeCountKey) ?? 0) === 0 && isUIMessageStreamable(runResult)) {
+                                    if ((locals_js_1.locals.get(chatPipeCountKey) ?? 0) === 0 &&
+                                        isUIMessageStreamable(runResult)) {
                                         onFinishAttached = true;
                                         const resolvedOptions = resolveUIMessageStreamOptions();
                                         // For action turns, don't pass originalMessages: the response
@@ -4257,9 +4299,7 @@ function chatAgent(options) {
                                             // Pass originalMessages so the AI SDK reuses message IDs across
                                             // turns (e.g. for tool approval continuations / HITL flows).
                                             // Omit for action turns to force a fresh response ID.
-                                            ...(isActionTurn
-                                                ? {}
-                                                : { originalMessages: accumulatedUIMessages }),
+                                            ...(isActionTurn ? {} : { originalMessages: accumulatedUIMessages }),
                                             // Always provide generateMessageId so the start chunk carries a
                                             // messageId. Without this, the frontend and backend generate IDs
                                             // independently and they won't match for ID-based dedup.
@@ -4270,7 +4310,10 @@ function chatAgent(options) {
                                                 resolveOnFinish();
                                             },
                                         });
-                                        await pipeChat(uiStream, { signal: combinedSignal, spanName: "stream response" });
+                                        await pipeChat(uiStream, {
+                                            signal: combinedSignal,
+                                            spanName: "stream response",
+                                        });
                                     }
                                 }
                                 catch (error) {
@@ -4305,7 +4348,8 @@ function chatAgent(options) {
                                 // never reports final usage), which would block the turn loop
                                 // from ever firing onTurnComplete / writeTurnComplete.
                                 let turnUsage;
-                                if (runResult != null && typeof runResult.totalUsage?.then === "function") {
+                                if (runResult != null &&
+                                    typeof runResult.totalUsage?.then === "function") {
                                     try {
                                         turnUsage = (await Promise.race([
                                             runResult.totalUsage,
@@ -4391,7 +4435,10 @@ function chatAgent(options) {
                                     // may produce a message with an empty ID since IDs are normally
                                     // assigned by the frontend's useChat).
                                     if (!capturedResponseMessage.id) {
-                                        capturedResponseMessage = { ...capturedResponseMessage, id: (0, ai_runtime_js_1.generateId)() };
+                                        capturedResponseMessage = {
+                                            ...capturedResponseMessage,
+                                            id: (0, ai_runtime_js_1.generateId)(),
+                                        };
                                     }
                                     // Append any non-transient data parts queued via chat.response or writer.write()
                                     const queuedParts = locals_js_1.locals.get(chatResponsePartsKey);
@@ -4692,7 +4739,9 @@ function chatAgent(options) {
                                                 ? { "gen_ai.usage.total_tokens": turnUsage.totalTokens }
                                                 : {}),
                                             ...(cumulativeUsage.totalTokens != null
-                                                ? { "gen_ai.usage.cumulative_total_tokens": cumulativeUsage.totalTokens }
+                                                ? {
+                                                    "gen_ai.usage.cumulative_total_tokens": cumulativeUsage.totalTokens,
+                                                }
                                                 : {}),
                                         },
                                     });
@@ -4724,9 +4773,7 @@ function chatAgent(options) {
                                                 savedAt: Date.now(),
                                                 messages: accumulatedUIMessages,
                                                 lastOutEventId: turnCompleteResult?.lastEventId,
-                                                lastInEventId: snapshotInCursor !== undefined
-                                                    ? String(snapshotInCursor)
-                                                    : undefined,
+                                                lastInEventId: snapshotInCursor !== undefined ? String(snapshotInCursor) : undefined,
                                             });
                                         }, {
                                             attributes: {
@@ -4768,8 +4815,7 @@ function chatAgent(options) {
                             // chat.requestUpgrade() was called — exit the loop so the
                             // transport triggers a new run on the latest version.
                             // chat.endRun() — same exit, no upgrade semantics.
-                            if (locals_js_1.locals.get(chatUpgradeRequestedKey) ||
-                                locals_js_1.locals.get(chatEndRunRequestedKey)) {
+                            if (locals_js_1.locals.get(chatUpgradeRequestedKey) || locals_js_1.locals.get(chatEndRunRequestedKey)) {
                                 return "exit";
                             }
                             // Wait for the next message — stay idle briefly, then suspend
@@ -4849,7 +4895,9 @@ function chatAgent(options) {
                         // Turn error handler: write an error chunk + turn-complete to the stream
                         // so the client sees the error, then wait for the next message instead
                         // of killing the entire run. This keeps the conversation alive.
-                        if (turnError instanceof Error && turnError.name === "AbortError" && runSignal.aborted) {
+                        if (turnError instanceof Error &&
+                            turnError.name === "AbortError" &&
+                            runSignal.aborted) {
                             // Full run cancellation — exit immediately
                             throw turnError;
                         }
@@ -4945,9 +4993,7 @@ function chatAgent(options) {
                                     savedAt: Date.now(),
                                     messages: erroredUIMessages,
                                     lastOutEventId: errorTurnCompleteResult?.lastEventId,
-                                    lastInEventId: errorSnapshotInCursor !== undefined
-                                        ? String(errorSnapshotInCursor)
-                                        : undefined,
+                                    lastInEventId: errorSnapshotInCursor !== undefined ? String(errorSnapshotInCursor) : undefined,
                                 });
                             }
                             catch (error) {
@@ -4958,8 +5004,7 @@ function chatAgent(options) {
                             }
                         }
                         // chat.requestUpgrade() / chat.endRun() — exit after error turn too
-                        if (locals_js_1.locals.get(chatUpgradeRequestedKey) ||
-                            locals_js_1.locals.get(chatEndRunRequestedKey)) {
+                        if (locals_js_1.locals.get(chatUpgradeRequestedKey) || locals_js_1.locals.get(chatEndRunRequestedKey)) {
                             return;
                         }
                         // Drain remaining recovered turns before idling — a thrown
@@ -4992,12 +5037,12 @@ function chatAgent(options) {
                 // cleanup so a missing subscription doesn't throw.
                 stopSub?.off();
             }
-        }
+        },
     });
     // Register clientDataSchema so the CLI converts it to JSONSchema
     // and stores it as payloadSchema — used by the Playground UI
     if (clientDataSchema) {
-        v3_2.resourceCatalog.updateTaskMetadata(options.id, {
+        v3_1.resourceCatalog.updateTaskMetadata(options.id, {
             schema: clientDataSchema,
         });
     }
@@ -5084,7 +5129,7 @@ function createChatBuilder(config) {
         agent(options) {
             const mergedUiStream = config.uiStreamOptions && options.uiMessageStreamOptions
                 ? { ...config.uiStreamOptions, ...options.uiMessageStreamOptions }
-                : options.uiMessageStreamOptions ?? config.uiStreamOptions;
+                : (options.uiMessageStreamOptions ?? config.uiStreamOptions);
             return chatAgent({
                 ...options,
                 ...(config.clientDataSchema ? { clientDataSchema: config.clientDataSchema } : {}),
@@ -5912,7 +5957,9 @@ function createChatSession(payload, options) {
                     if (turn === 0 && currentPayload.trigger === "handover-prepare") {
                         const signal = await waitForHandover({
                             payload: currentPayload,
-                            idleTimeoutInSeconds: sessionIdleTimeoutOpt ?? currentPayload.idleTimeoutInSeconds ?? idleTimeoutInSeconds,
+                            idleTimeoutInSeconds: sessionIdleTimeoutOpt ??
+                                currentPayload.idleTimeoutInSeconds ??
+                                idleTimeoutInSeconds,
                             timeout,
                         });
                         if (!signal || signal.kind === "handover-skip" || runSignal.aborted) {
@@ -5931,7 +5978,8 @@ function createChatSession(payload, options) {
                     // arrive with the sticky boot-payload fields stripped, so running
                     // a turn immediately would invoke the model with no user input.
                     const isMessagelessContinuationBoot = currentPayload.continuation === true && !currentPayload.message;
-                    if (turn === 0 && (currentPayload.trigger === "preload" || isMessagelessContinuationBoot)) {
+                    if (turn === 0 &&
+                        (currentPayload.trigger === "preload" || isMessagelessContinuationBoot)) {
                         const result = await messagesInput.waitWithIdleTimeout({
                             idleTimeoutInSeconds: sessionIdleTimeoutOpt ?? currentPayload.idleTimeoutInSeconds ?? 30,
                             timeout,
@@ -5955,8 +6003,7 @@ function createChatSession(payload, options) {
                     // Subsequent turns: wait for the next message
                     if (turn > 0) {
                         // chat.requestUpgrade() / chat.endRun() — exit before waiting
-                        if (locals_js_1.locals.get(chatUpgradeRequestedKey) ||
-                            locals_js_1.locals.get(chatEndRunRequestedKey)) {
+                        if (locals_js_1.locals.get(chatUpgradeRequestedKey) || locals_js_1.locals.get(chatEndRunRequestedKey)) {
                             stop.cleanup();
                             return { done: true, value: undefined };
                         }
@@ -6030,7 +6077,7 @@ function createChatSession(payload, options) {
                     const incomingForAccumulator = currentPayload.message
                         ? [currentPayload.message]
                         : [];
-                    const messages = await accumulator.addIncoming(incomingForAccumulator, currentPayload.trigger, turn);
+                    const _messages = await accumulator.addIncoming(incomingForAccumulator, currentPayload.trigger, turn);
                     // Apply the head-start handover AFTER addIncoming — turn-0 addIncoming
                     // replaces accumulator state, which would wipe a pre-applied splice.
                     // Seed prior history first, then splice the warm step-1 partial.
@@ -6203,7 +6250,8 @@ function createChatSession(payload, options) {
                                             },
                                         ];
                                     if (sessionCompaction.compactUIMessages) {
-                                        accumulator.uiMessages = await sessionCompaction.compactUIMessages(compactEvent);
+                                        accumulator.uiMessages =
+                                            await sessionCompaction.compactUIMessages(compactEvent);
                                     }
                                 }
                             }
@@ -6215,7 +6263,10 @@ function createChatSession(payload, options) {
                             // Append any non-transient data parts queued via chat.response or writer.write()
                             const queuedParts = locals_js_1.locals.get(chatResponsePartsKey);
                             if (queuedParts && queuedParts.length > 0) {
-                                response = { ...response, parts: [...(response.parts ?? []), ...queuedParts] };
+                                response = {
+                                    ...response,
+                                    parts: [...(response.parts ?? []), ...queuedParts],
+                                };
                                 locals_js_1.locals.set(chatResponsePartsKey, []);
                             }
                             await accumulator.addResponse(response);
@@ -6484,6 +6535,12 @@ function createChatStartSessionAction(taskId, options) {
         if (!params.chatId) {
             throw new Error("chat.createStartSessionAction: params.chatId is required — used as the session externalId.");
         }
+        // Scope the action to `apiClient`'s env: re-enter without it so the body
+        // runs once, under that config (read via apiClientManager.accessToken/.baseURL).
+        if (options?.apiClient) {
+            const { apiClient, ...rest } = options;
+            return v3_1.apiClientManager.runWithConfig(apiClient, () => createChatStartSessionAction(taskId, rest)(params));
+        }
         // The first run boots before the user's first message lands on
         // `.in/append`, so it sees an empty `messages` array and `trigger:
         // "preload"`. This matches the pre-Sessions preload semantics:
@@ -6591,9 +6648,7 @@ function createChatStartSessionAction(taskId, options) {
 }
 function resolveChatStartBaseURL(endpoint, chatId, option) {
     const fallback = v3_1.apiClientManager.baseURL ?? "https://api.trigger.dev";
-    const raw = typeof option === "function"
-        ? option({ endpoint, chatId })
-        : option ?? fallback;
+    const raw = typeof option === "function" ? option({ endpoint, chatId }) : (option ?? fallback);
     return raw.replace(/\/$/, "");
 }
 function overrideRequestHeaders(accessToken) {