@trigger.dev/sdk 4.8.0 → 4.8.2

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

@@ -21,6 +21,12 @@ import type { InferUITools, ToolSet, UIDataTypes, UIMessage } from "ai";
  * injects when a follow-up message arrives mid-turn.
  */
 export declare const PENDING_MESSAGE_INJECTED_TYPE: "data-pending-message-injected";
+/**
+ * Message-part `type` value marking where `chat.inject` messages drained
+ * mid-turn reached the model. Separate from the pending-message type so
+ * clients that render injection markers do not render these.
+ */
+export declare const BACKGROUND_INJECTION_TYPE: "data-background-injected";
 import type { ChatTaskWirePayload } from "./chat.js";
 export type { ChatTaskWirePayload, ChatInputChunk } from "./chat.js";
 /**

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

@@ -16,7 +16,7 @@
  * import from `ai.ts`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_EOF_RESUBSCRIBES = exports.PENDING_MESSAGE_INJECTED_TYPE = void 0;
+exports.MAX_EOF_RESUBSCRIBES = exports.BACKGROUND_INJECTION_TYPE = exports.PENDING_MESSAGE_INJECTED_TYPE = void 0;
 exports.upsertIncomingMessage = upsertIncomingMessage;
 exports.slimSubmitMessageForWire = slimSubmitMessageForWire;
 exports.chatRunTags = chatRunTags;
@@ -26,6 +26,12 @@ exports.waitBeforeEofResubscribe = waitBeforeEofResubscribe;
  * injects when a follow-up message arrives mid-turn.
  */
 exports.PENDING_MESSAGE_INJECTED_TYPE = "data-pending-message-injected";
+/**
+ * Message-part `type` value marking where `chat.inject` messages drained
+ * mid-turn reached the model. Separate from the pending-message type so
+ * clients that render injection markers do not render these.
+ */
+exports.BACKGROUND_INJECTION_TYPE = "data-background-injected";
 /**
  * Upsert an incoming wire message into the customer's DB-backed chain
  * inside a `hydrateMessages` hook. Returns `true` iff the chain was

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":"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"}

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

@@ -2,6 +2,7 @@ import { type AnyTask, type Task, type ApiClientConfiguration, type inferSchemaI
 import type { streamText as aiStreamTextSignature, FinishReason, LanguageModelUsage, ModelMessage, SystemModelMessage, ProviderMetadata, Tool, ToolSet, UIMessage, UIMessageChunk, UIMessageStreamOptions } from "ai";
 import { chatEvent } from "./webhooks.js";
 import { type TranscriptLoadResult, type TranscriptChannelBinding, type TranscriptStorage } from "./transcriptStorage.js";
+import type { ChatStream } from "./chat-client.js";
 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";
@@ -211,6 +212,48 @@ declare function createChatWatchToken(externalId: string, options?: {
  * ```
  */
 declare function chatDeferBeforeOutput(promiseOrFn: Promise<unknown> | (() => Promise<unknown>)): void;
+/** Options for {@link forwardSubAgent}. */
+export type ForwardSubAgentOptions = {
+    /** The parent tool call the sub-agent runs inside: `toolCallId` from the tool's `execute` options. */
+    toolCallId: string;
+    /**
+     * How long chunks are held so they are written together. `0` writes each
+     * chunk on its own.
+     * @default 50
+     */
+    flushIntervalMs?: number;
+};
+/**
+ * Stream a sub-agent's reply to the frontend from inside a parent tool call,
+ * and resolve with the sub-agent's final message once it finishes.
+ *
+ * Each chunk the sub-agent streams is written once to the parent chat as a
+ * transient `data-subagent` part, so the bytes written grow with the length of
+ * the reply. Render it while it runs with `useSubAgentMessages` from
+ * `@trigger.dev/sdk/chat/react`. The tool's output is the final message, which
+ * persists with the parent's history the way a tool result always does.
+ *
+ * Prefer this over yielding `stream.messages()` snapshots as preliminary tool
+ * results: every snapshot repeats the whole message so far, so that pattern
+ * writes bytes in proportion to the square of the reply length.
+ *
+ * Call it inside a `chat.agent` (or `chat.customAgent`) run.
+ *
+ * @example
+ * ```ts
+ * const research = tool({
+ *   description: "Delegate research to the research agent.",
+ *   inputSchema: z.object({ topic: z.string() }),
+ *   execute: async ({ topic }, { toolCallId, abortSignal }) => {
+ *     const agent = new AgentChat<typeof researchAgent>({ agent: "research-agent" });
+ *     const stream = await agent.sendMessage(topic, { abortSignal });
+ *     return await chat.forwardSubAgent(stream, { toolCallId });
+ *   },
+ *   toModelOutput: ({ output }) => ({ type: "text", value: lastText(output) }),
+ * });
+ * ```
+ */
+declare function forwardSubAgent<TUIMessage extends UIMessage = UIMessage>(stream: ChatStream | ReadableStream<UIMessageChunk>, options: ForwardSubAgentOptions): Promise<TUIMessage | undefined>;
 /**
  * A stream writer passed to chat lifecycle callbacks (`onPreload`, `onChatStart`,
  * `onTurnStart`, `onTurnComplete`, `onCompacted`).
@@ -4078,6 +4121,8 @@ export declare const chat: {
          */
         write(part: UIMessageChunk): void;
     };
+    /** Stream a sub-agent's reply through a parent tool call. See {@link forwardSubAgent}. */
+    forwardSubAgent: typeof forwardSubAgent;
     /** Pre-built input stream for receiving messages from the transport. */
     messages: ChatMessages;
     /** The current chat.agent run's Session handle. See {@link SessionHandle}. */

package/dist/commonjs/v3/ai.js

@@ -32,6 +32,7 @@ const compactionResponse_js_1 = require("./compactionResponse.js");
 const toolResultOrder_js_1 = require("./toolResultOrder.js");
 const managedChatResponse_js_1 = require("./managedChatResponse.js");
 const uiMessageChunks_js_1 = require("./uiMessageChunks.js");
+const subAgentStream_js_1 = require("./subAgentStream.js");
 const steeringContext_js_1 = require("./steeringContext.js");
 let transcriptStorageOverride;
 /**
@@ -954,6 +955,64 @@ const chatResponse = {
         managedResponse().writeData(part);
     },
 };
+/**
+ * Stream a sub-agent's reply to the frontend from inside a parent tool call,
+ * and resolve with the sub-agent's final message once it finishes.
+ *
+ * Each chunk the sub-agent streams is written once to the parent chat as a
+ * transient `data-subagent` part, so the bytes written grow with the length of
+ * the reply. Render it while it runs with `useSubAgentMessages` from
+ * `@trigger.dev/sdk/chat/react`. The tool's output is the final message, which
+ * persists with the parent's history the way a tool result always does.
+ *
+ * Prefer this over yielding `stream.messages()` snapshots as preliminary tool
+ * results: every snapshot repeats the whole message so far, so that pattern
+ * writes bytes in proportion to the square of the reply length.
+ *
+ * Call it inside a `chat.agent` (or `chat.customAgent`) run.
+ *
+ * @example
+ * ```ts
+ * const research = tool({
+ *   description: "Delegate research to the research agent.",
+ *   inputSchema: z.object({ topic: z.string() }),
+ *   execute: async ({ topic }, { toolCallId, abortSignal }) => {
+ *     const agent = new AgentChat<typeof researchAgent>({ agent: "research-agent" });
+ *     const stream = await agent.sendMessage(topic, { abortSignal });
+ *     return await chat.forwardSubAgent(stream, { toolCallId });
+ *   },
+ *   toModelOutput: ({ output }) => ({ type: "text", value: lastText(output) }),
+ * });
+ * ```
+ */
+async function forwardSubAgent(stream, options) {
+    const source = isReadableStream(stream)
+        ? stream
+        : stream.stream;
+    let outcome = { message: undefined };
+    const { waitUntilComplete } = chatStream.writer({
+        spanName: "forward sub-agent",
+        collapsed: true,
+        execute: async ({ write }) => {
+            try {
+                outcome = {
+                    message: await (0, subAgentStream_js_1.forwardSubAgentChunks)(source, {
+                        toolCallId: options.toolCallId,
+                        flushIntervalMs: options.flushIntervalMs ?? 50,
+                        write,
+                    }),
+                };
+            }
+            catch (error) {
+                outcome = { error };
+            }
+        },
+    });
+    await waitUntilComplete();
+    if ("error" in outcome)
+        throw outcome.error;
+    return outcome.message;
+}
 /**
  * Creates a lazy ChatWriter that only opens a realtime stream on first use.
  * Call `flush()` after the callback returns to await stream completion.
@@ -1948,12 +2007,6 @@ function spliceHandoverPartial(modelMessages, uiMessages, signal) {
  * @internal
  */
 const chatBackgroundQueueKey = locals_js_1.locals.create("chat.backgroundQueue");
-/**
- * Background injections a step-boundary drain handed to the model this turn,
- * with the transcript message they followed. Reconciled into the model lane
- * and the persisted injections once the turn's response is in.
- */
-const chatPendingBackgroundKey = locals_js_1.locals.create("chat.pendingBackground");
 /**
  * System-role context injected mid-conversation, held for the instructions lane.
  *
@@ -2906,6 +2959,25 @@ const EMPTY_DRAIN = { injected: [], claimed: [] };
 function modelFormOf(m, batch, injected) {
     return batch[0] === m ? injected : [];
 }
+/**
+ * Record a prepared injection and write its marker into the response, so the
+ * model lane rebuilds it at the step boundary where the model received it.
+ */
+function markInjection(steps, messageIds, messages, markerMessages, kind) {
+    const id = (0, ai_runtime_js_1.generateId)();
+    const injections = locals_js_1.locals.get(chatSteeringInjectionsKey) ?? new Map();
+    injections.set(id, { id, messageIds, messages, ...(kind ? { kind } : {}) });
+    locals_js_1.locals.set(chatSteeringInjectionsKey, injections);
+    const response = managedResponse();
+    // prepareStep can run ahead of the UI consumer. Admit the marker only
+    // once the actual preceding finish-step chunk has entered this stream.
+    response.afterToolStep(steps.at(-1)?.content.flatMap((part) => (part.toolCallId ? [part.toolCallId] : [])) ?? []);
+    response.writeData({
+        type: kind === "background" ? ai_shared_js_1.BACKGROUND_INJECTION_TYPE : ai_shared_js_1.PENDING_MESSAGE_INJECTED_TYPE,
+        id,
+        data: { messageIds, messages: markerMessages },
+    });
+}
 /**
  * Drain the steering queue as a batch. Calls `shouldInject` once with all
  * pending messages. If it returns true, calls `prepareMessages` once to
@@ -2919,8 +2991,6 @@ function modelFormOf(m, batch, injected) {
  * @internal
  */
 async function drainSteeringQueue(config, messages, steps, queueOverride) {
-    if (steps.length === 0)
-        managedResponse().beginGeneration();
     const queue = queueOverride ?? locals_js_1.locals.get(chatSteeringQueueKey);
     if (!queue || queue.length === 0)
         return EMPTY_DRAIN;
@@ -3053,23 +3123,7 @@ async function drainSteeringQueue(config, messages, steps, queueOverride) {
             locals_js_1.locals.set(chatPendingSteerKey, pendingSteer);
         }
         if (injected.length > 0) {
-            const id = (0, ai_runtime_js_1.generateId)();
-            const messageIds = claimedUIMessages.map((m) => m.id);
-            const injections = locals_js_1.locals.get(chatSteeringInjectionsKey) ?? new Map();
-            injections.set(id, { id, messageIds, messages: injected });
-            locals_js_1.locals.set(chatSteeringInjectionsKey, injections);
-            const response = managedResponse();
-            // prepareStep can run ahead of the UI consumer. Admit the marker only
-            // once the actual preceding finish-step chunk has entered this stream.
-            response.afterStep(steps.length);
-            response.writeData({
-                type: ai_shared_js_1.PENDING_MESSAGE_INJECTED_TYPE,
-                id,
-                data: {
-                    messageIds,
-                    messages: claimedUIMessages.map((m) => ({ id: m.id, text: textOfUIMessage(m) })),
-                },
-            });
+            markInjection(steps, claimedUIMessages.map((m) => m.id), injected, claimedUIMessages.map((m) => ({ id: m.id, text: textOfUIMessage(m) })));
         }
         // Fire onInjected callback
         if (config.onInjected && injected.length > 0) {
@@ -3634,12 +3688,7 @@ function toStreamTextOptions(options, retain = true) {
             if (bgQueue && bgQueue.length > 0) {
                 const injected = bgQueue.splice(0); // drain
                 resultMessages = [...(resultMessages ?? messages), ...injected];
-                const pendingBackground = locals_js_1.locals.get(chatPendingBackgroundKey) ?? [];
-                pendingBackground.push({
-                    afterId: locals_js_1.locals.get(chatCurrentUIMessagesKey)?.at(-1)?.id ?? "",
-                    messages: injected,
-                });
-                locals_js_1.locals.set(chatPendingBackgroundKey, pendingBackground);
+                markInjection(steps, [], injected, [], "background");
             }
             // 4. Parallel tool results in call order, the order the next turn's history
             // will list them in. See `withToolResultsInCallOrder`.
@@ -4988,24 +5037,6 @@ function chatAgent(options) {
             // durable snapshot + `session.out` replay (or `hydrateMessages` if
             // registered) — the wire is delta-only now, no longer a seed.
             let accumulatedMessages = [];
-            /**
-             * Give the model accumulator the background injections a step-boundary
-             * drain handed to the model this turn, and record them for persistence.
-             * Returns how many model messages were appended.
-             */
-            const reconcilePendingBackground = () => {
-                const pending = locals_js_1.locals.get(chatPendingBackgroundKey);
-                if (!pending || pending.length === 0)
-                    return 0;
-                locals_js_1.locals.set(chatPendingBackgroundKey, []);
-                let appended = 0;
-                for (const entry of pending) {
-                    accumulatedMessages.push(...entry.messages);
-                    laneInjections.push(entry);
-                    appended += entry.messages.length;
-                }
-                return appended;
-            };
             /**
              * Give the model accumulator the steering messages a drain consumed,
              * in the form the model actually received. Appended, never reconverted
@@ -5029,6 +5060,15 @@ function chatAgent(options) {
             // Accumulated UI messages for persistence. Mirrors the model accumulator
             // but in frontend-friendly UIMessage format (with parts, id, etc.).
             let accumulatedUIMessages = [];
+            const cleanIncomingMessage = (msg) => {
+                if (msg.role !== "assistant")
+                    return (0, steeringContext_js_1.withoutInjectionMarkers)(msg);
+                const cleaned = cleanupAbortedParts(msg);
+                // Markers are the agent's own; only a known assistant message keeps them.
+                return accumulatedUIMessages.some((m) => m.id === msg.id)
+                    ? cleaned
+                    : (0, steeringContext_js_1.withoutInjectionMarkers)(cleaned);
+            };
             // ── Snapshot + replay (gated on prior-state signals) ─────────────
             //
             // With `hydrateMessages` registered the customer owns history — the
@@ -6545,7 +6585,7 @@ function chatAgent(options) {
                         // Cleaning happens once here so `extractLastUserMessageText` and
                         // every downstream consumer see the same message shape — and
                         // `cleanupAbortedParts` no longer has to be re-applied below.
-                        const cleanedIncomingMessages = incomingMessages.map((msg) => msg.role === "assistant" ? cleanupAbortedParts(msg) : msg);
+                        const cleanedIncomingMessages = incomingMessages.map(cleanIncomingMessage);
                         const lastUserMessage = extractLastUserMessageText(cleanedIncomingMessages);
                         channelTurnRan =
                             !!channelConn &&
@@ -6606,7 +6646,6 @@ function chatAgent(options) {
                             locals_js_1.locals.set(chatOutGateKey, createChatOutGate());
                             locals_js_1.locals.set(chatCompactionStateKey, undefined);
                             locals_js_1.locals.set(chatSteeringQueueKey, []);
-                            locals_js_1.locals.set(chatPendingBackgroundKey, []);
                             await locals_js_1.locals.get(chatManagedResponseKey)?.close();
                             locals_js_1.locals.set(chatManagedResponseKey, undefined);
                             locals_js_1.locals.set(chatManagedResponseActiveKey, true);
@@ -7705,7 +7744,7 @@ function chatAgent(options) {
                                 const steerTailThisTurn = reconcilePendingSteer({
                                     turnNew: turnNewModelMessages,
                                     response: capturedResponseMessage,
-                                }).reduce((n, e) => n + e.model.length, 0) + reconcilePendingBackground();
+                                }).reduce((n, e) => n + e.model.length, 0);
                                 // Append the assistant's response (partial or complete) to the accumulator.
                                 // The onFinish callback fires even on abort/stop, so partial responses
                                 // from stopped generation are captured correctly.
@@ -8588,7 +8627,8 @@ function chatAgent(options) {
                         // yet (a pre-run hook threw), so fold the wire message in for the
                         // error event + snapshot — the cursor has already advanced past it,
                         // so otherwise it survives in neither the snapshot nor the `.in` tail.
-                        const erroredWireMessage = currentWirePayload.message;
+                        const rawWireMessage = currentWirePayload.message;
+                        const erroredWireMessage = rawWireMessage && cleanIncomingMessage(rawWireMessage);
                         const erroredUIMessages = erroredWireMessage &&
                             !accumulatedUIMessages.some((m) => m.id === erroredWireMessage.id)
                             ? [...accumulatedUIMessages, erroredWireMessage]
@@ -8645,7 +8685,6 @@ function chatAgent(options) {
                         let erroredNewUIMessages = buildErroredNew();
                         let erroredNewModelMessages = [];
                         const reconciledSteer = reconcilePendingSteer({ response: partialResponse });
-                        const backgroundTailThisTurn = reconcilePendingBackground();
                         if (!responseCommitted) {
                             try {
                                 if (erroredNewUIMessages.length > 0) {
@@ -8663,8 +8702,7 @@ function chatAgent(options) {
                                         accumulatedMessages.push(...(await toModelMessages(appended.map((m) => stripProviderMetadata(m)))));
                                     }
                                     else {
-                                        const ok = await replaceModelRun(accumulatedMessages, erroredUIMessages[partialIdx], partialResponse, reconciledSteer.reduce((n, e) => n + e.model.length, 0) +
-                                            backgroundTailThisTurn);
+                                        const ok = await replaceModelRun(accumulatedMessages, erroredUIMessages[partialIdx], partialResponse, reconciledSteer.reduce((n, e) => n + e.model.length, 0));
                                         if (!ok) {
                                             v3_1.logger.warn("chat.agent: replaced partial not found at the model lane tail; reconverting the lane");
                                             accumulatedMessages = await toModelMessages(erroredUIMessagesWithPartial, erroredUIMessagesWithPartial);
@@ -11064,10 +11102,10 @@ function resolveChatStartBaseURL(endpoint, chatId, option) {
     const raw = typeof option === "function" ? option({ endpoint, chatId }) : (option ?? fallback);
     return raw.replace(/\/$/, "");
 }
-function overrideRequestHeaders(accessToken) {
+function overrideRequestHeaders(authHeaders) {
     const headers = {
         "Content-Type": "application/json",
-        Authorization: `Bearer ${accessToken}`,
+        ...authHeaders,
         "x-trigger-source": "sdk",
     };
     // Forward the preview-branch hint so override-mode requests land on the
@@ -11080,15 +11118,16 @@ function overrideRequestHeaders(accessToken) {
     return headers;
 }
 async function callSessionsCreateWithOverride(args) {
-    const accessToken = v3_1.apiClientManager.accessToken;
-    if (!accessToken) {
+    const apiClient = v3_1.apiClientManager.client;
+    if (!apiClient) {
         throw new Error("chat.createStartSessionAction: no API access token configured. Set TRIGGER_SECRET_KEY or call apiClientManager.setGlobalAPIClientConfiguration before invoking the action.");
     }
+    const authHeaders = apiClient.getAuthenticationHeaders("createSession");
     const ctx = { endpoint: "sessions", chatId: args.chatId };
     const url = `${resolveChatStartBaseURL("sessions", args.chatId, args.baseURLOption)}/api/v1/sessions`;
     const init = {
         method: "POST",
-        headers: overrideRequestHeaders(accessToken),
+        headers: overrideRequestHeaders(authHeaders),
         // This path bypasses `sessions.start`, so it resolves the pin itself.
         body: JSON.stringify((0, externalDeploymentId_js_1.withResolvedExternalDeploymentId)(args.body)),
     };
@@ -11103,18 +11142,20 @@ async function callSessionsCreateWithOverride(args) {
     return json;
 }
 async function mintPublicTokenWithOverride(args) {
-    const accessToken = v3_1.apiClientManager.accessToken;
-    if (!accessToken) {
+    const apiClient = v3_1.apiClientManager.client;
+    if (!apiClient) {
         throw new Error("chat.createStartSessionAction: no API access token configured for JWT mint.");
     }
+    const authHeaders = apiClient.getAuthenticationHeaders("createPublicToken");
+    const accessToken = authHeaders.Authorization.slice("Bearer ".length);
     const ctx = { endpoint: "auth", chatId: args.chatId };
     const scopes = [`read:sessions:${args.chatId}`, `write:sessions:${args.chatId}`];
-    const serverMint = (0, v3_1.isAdditionalApiKey)(accessToken);
+    const serverMint = (0, v3_1.isAdditionalApiKey)(accessToken) || (0, v3_1.isRunToken)(accessToken);
     const endpoint = serverMint ? "/api/v1/auth/public-tokens" : "/api/v1/auth/jwt/claims";
     const url = `${resolveChatStartBaseURL("auth", args.chatId, args.baseURLOption)}${endpoint}`;
     const init = {
         method: "POST",
-        headers: overrideRequestHeaders(accessToken),
+        headers: overrideRequestHeaders(authHeaders),
         ...(serverMint
             ? {
                 body: JSON.stringify({
@@ -11130,11 +11171,9 @@ async function mintPublicTokenWithOverride(args) {
         ? await args.fetchOverride(url, init, ctx)
         : await fetch(url, init);
     if (!response.ok) {
-        // An additional API key cannot self-sign, so it must use the server mint
-        // endpoint. On a server too old to expose it, explain the recovery path
-        // instead of surfacing a bare 404 (mirrors auth.createServerPublicToken).
         if (serverMint && response.status === 404) {
-            throw new Error("This additional API key cannot self-sign public tokens, and the server does not support public-token minting. Upgrade the server or use the root API key.");
+            const credentialType = (0, v3_1.isRunToken)(accessToken) ? "run token" : "additional API key";
+            throw new Error(`This ${credentialType} cannot self-sign public tokens, and the server does not support public-token minting. Upgrade the server or use the root API key.`);
         }
         const text = await response.text().catch(() => "");
         throw new Error(`auth.createPublicToken failed: ${response.status} ${text}`);
@@ -11248,6 +11287,8 @@ exports.chat = {
     stream: chatStream,
     /** Write data parts that persist to the response message. See {@link chatResponse}. */
     response: chatResponse,
+    /** Stream a sub-agent's reply through a parent tool call. See {@link forwardSubAgent}. */
+    forwardSubAgent,
     /** Pre-built input stream for receiving messages from the transport. */
     messages: messagesInput,
     /** The current chat.agent run's Session handle. See {@link SessionHandle}. */