@trigger.dev/sdk 4.8.0-webhooks.20261015065339 → 4.8.0-webhooks.20261020092920

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

@@ -34,6 +34,7 @@ type ChatTurnContext<TClientData = unknown> = {
     turn: number;
     continuation: boolean;
     clientData?: TClientData;
+    recordUserMessage?: boolean;
 };
 export { __readChatSnapshotProductionPathForTests, __setReadChatSnapshotImplForTests, __setWriteChatSnapshotImplForTests, __writeChatSnapshotProductionPathForTests, } from "./chatSnapshotIo.js";
 export { defaultStorage, memoryTranscriptStorage, reduceTranscriptChanges, snapshotTranscriptStorage, type LoadContextEvent, type MemoryTranscriptStorage, type TranscriptChange, type TranscriptChangeReason, type TranscriptChangeset, type TranscriptCursors, type TranscriptLoadOptions, type TranscriptLoadResult, type TranscriptScope, type TranscriptState, type TranscriptStorage, type TranscriptStorageContext, } from "./transcriptStorage.js";
@@ -1862,21 +1863,25 @@ export type ChannelControl = {
 /**
  * What a connector's `progress()` hook observes while a turn streams: each tool call as its input is
  * complete, and each result or error as it lands. Text deltas are not reported (use `delivery: "stream"`).
+ * `title` is the tool's display title (`tool({ title })`), when it declares one.
  */
 export type ChannelProgressEvent = {
     type: "tool-call";
     toolCallId: string;
     toolName: string;
+    title?: string;
     input: unknown;
 } | {
     type: "tool-result";
     toolCallId: string;
     toolName: string;
+    title?: string;
     output: unknown;
 } | {
     type: "tool-error";
     toolCallId: string;
     toolName: string;
+    title?: string;
     errorText: string;
 };
 /**
@@ -1900,7 +1905,7 @@ export type ChannelReplyStreamEnd = {
     stopped: boolean;
     /** The turn paused on a human decision; the controls follow as their own message. */
     pending: boolean;
-    /** The sanitized error text when the turn ended on a model or stream error. */
+    /** The connector's error line (`errorMessage`) when the turn ended on a model or stream error. */
     errorText?: string;
 };
 /**
@@ -2026,6 +2031,12 @@ export interface ChannelConnector<TEvent = unknown, THandle = unknown> {
     cancelInteraction?: (cancelled: ChannelCancelledToolCall[], ctx: ChannelTurnCtx<TEvent, THandle>) => Promise<void> | void;
     react?: (reaction: ChannelReaction, ctx: ChannelReactCtx<TEvent>) => Promise<void>;
     reactions?: ChannelReactions<TEvent>;
+    /**
+     * What the channel shows when a turn fails, in place of the error text: a fixed line, or a
+     * function of the failure that returns one. Defaults to {@link CHANNEL_TURN_ERROR_MESSAGE}. The
+     * error itself is logged on the run, and `outbound()` still receives it as `reply.error`.
+     */
+    errorMessage?: ChannelErrorMessage<TEvent>;
     /**
      * Observe tool calls and results as the turn streams, to post progress into the surface (a Linear
      * `action` activity, a Slack status). Called in order, awaited one at a time, independent of
@@ -2045,6 +2056,34 @@ export interface ChannelConnector<TEvent = unknown, THandle = unknown> {
     readonly [channelEventPhantom]?: TEvent;
 }
 export type AnyChannelConnector = ChannelConnector<any, any>;
+/** The line a channel shows when a turn fails, unless the connector sets its own `errorMessage`. */
+export declare const CHANNEL_TURN_ERROR_MESSAGE = "Something went wrong answering this. Try again.";
+/** What an `errorMessage` function receives when a channel turn fails. */
+export type ChannelErrorContext<TEvent = unknown> = {
+    /** The failure: the model or stream error, or what the turn threw. */
+    error: Error;
+    /** The text the turn streamed before it failed; empty when it failed before answering. */
+    partialText: string;
+    /** The event that started the turn; undefined on a turn the channel did not start (an action turn, a browser message). */
+    event: TEvent | undefined;
+    /** The run the turn failed in, for a support reference. */
+    runId: string | undefined;
+    /** The session's chat id. */
+    chatId: string;
+    /** {@link CHANNEL_TURN_ERROR_MESSAGE}, to extend rather than replace. */
+    defaultMessage: string;
+};
+/**
+ * A channel's error line: a fixed string, or a function of the failure. A function that returns
+ * nothing, or throws, falls back to {@link CHANNEL_TURN_ERROR_MESSAGE}.
+ *
+ * @example
+ * ```ts
+ * errorMessage: ({ error, runId }) =>
+ *   error.name === "RateLimitError" ? "I'm a bit busy, try again in a minute." : `That failed (ref ${runId}).`,
+ * ```
+ */
+export type ChannelErrorMessage<TEvent = unknown> = string | ((ctx: ChannelErrorContext<TEvent>) => string | null | undefined | Promise<string | null | undefined>);
 /**
  * A generic chat-frontend channel over any verified source. Unlike `slack()`, you supply the egress
  * `send` yourself (post/edit the reply back to your surface), so the whole round-trip is under your
@@ -2088,6 +2127,8 @@ export declare function chatChannelCustom<TEndpoint extends AnyWebhookEndpoint,
     filter?: ValidateWebhookFilter<InferWebhookEndpointEvent<TEndpoint>, TFilter>;
     startOn?: ValidateWebhookFilter<InferWebhookEndpointEvent<TEndpoint>, TStartOn>;
     delivery?: "final" | "stream";
+    /** What the channel shows when a turn fails: a line, or a function of the failure. Defaults to {@link CHANNEL_TURN_ERROR_MESSAGE}. */
+    errorMessage?: ChannelErrorMessage<NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>>;
 }): ChannelConnector<NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>, THandle>;
 export declare function resolveReactionChoice(choice: ChannelReactionChoice | undefined, event: unknown): Promise<string | undefined>;
 /**
@@ -2184,6 +2225,31 @@ export type ChatAgentOptions<TIdentifier extends string, TClientDataSchema exten
      * Ignored for sessions with no pin, and for sessions using `lockToVersion`.
      */
     versionSkew?: ChatVersionSkewPolicy;
+    /**
+     * Controls which chat content the chat runtime records on its spans in the run trace.
+     *
+     * - `recordUserMessage` (default `true`) records the last user message as `chat.user_message`
+     *   and as the turn span's preview text, and messages sent mid-turn as `pending.messages`.
+     * - `recordClientData` (default `true`) records the raw `clientData` sent by the frontend as
+     *   `chat.client_data`.
+     *
+     * Set either to `false` to keep that content out of telemetry. Content recorded by the AI SDK's
+     * own spans is controlled separately, through `experimental_telemetry` on the model call.
+     *
+     * @example
+     * ```ts
+     * chat.agent({
+     *   id: "my-chat",
+     *   telemetry: { recordUserMessage: false, recordClientData: false },
+     *   run: async ({ messages, signal, streamText }) =>
+     *     streamText({ model, messages, abortSignal: signal }),
+     * });
+     * ```
+     */
+    telemetry?: {
+        recordUserMessage?: boolean;
+        recordClientData?: boolean;
+    };
     /**
      * Schema for validating `clientData` from the frontend.
      * Accepts Zod, ArkType, Valibot, or any supported schema library.

package/dist/esm/v3/ai.js

@@ -2934,7 +2934,6 @@ async function drainSteeringQueue(config, messages, steps, queueOverride) {
     // Span attributes describe the offered batch; the chunk and callback below
     // describe what was actually claimed and injected.
     const messageTexts = uiMessages.map(textOfUIMessage);
-    const _previewText = messageTexts.length === 1 ? messageTexts[0].slice(0, 80) : `${queue.length} messages`;
     return tracer.startActiveSpan("pending message injected", async () => {
         /**
          * Claim before transforming, and inject only what was claimed.
@@ -3073,7 +3072,7 @@ async function drainSteeringQueue(config, messages, steps, queueOverride) {
             [SemanticInternalAttributes.STYLE_ICON]: "tabler-message-forward",
             "pending.message_count": uiMessages.length,
             "pending.step_number": stepNumber,
-            "pending.messages": messageTexts,
+            ...(ctx?.recordUserMessage === false ? {} : { "pending.messages": messageTexts }),
             ...(ctx?.chatId ? { "pending.chat_id": ctx.chatId } : {}),
             ...(ctx?.turn != null ? { "pending.turn": ctx.turn } : {}),
             ...accessoryAttributes({
@@ -3819,13 +3818,39 @@ async function pipeChat(source, options, capture) {
         await waitUntilComplete();
     }
 }
+/** The AI SDK's default `toUIMessageStream` `onError`: the error's message, as the client sees it. */
+function uiStreamErrorText(error) {
+    if (error == null)
+        return "unknown error";
+    if (typeof error === "string")
+        return error;
+    if (error instanceof Error)
+        return error.message;
+    return JSON.stringify(error);
+}
+/** The line a channel shows when a turn fails, unless the connector sets its own `errorMessage`. */
+export const CHANNEL_TURN_ERROR_MESSAGE = "Something went wrong answering this. Try again.";
+async function channelTurnErrorMessage(connector, ctx) {
+    const option = connector?.errorMessage;
+    if (typeof option !== "function")
+        return option || CHANNEL_TURN_ERROR_MESSAGE;
+    try {
+        const line = await option({ ...ctx, defaultMessage: CHANNEL_TURN_ERROR_MESSAGE });
+        if (line)
+            return line;
+    }
+    catch (error) {
+        logger.warn("chat.agent: channel errorMessage threw; posting the default line", { error });
+    }
+    return CHANNEL_TURN_ERROR_MESSAGE;
+}
 /**
  * A generic chat-frontend channel over any verified source. Unlike `slack()`, you supply the egress
  * `send` yourself (post/edit the reply back to your surface), so the whole round-trip is under your
  * control. Use for providers without a preset, or to test the channel round-trip end to end.
  */
 export function chatChannelCustom(options) {
-    const { id, endpoint, key, inbound, bind, seed, outbound, ack, send, renderInteraction, onInteraction, finalizeInteraction, react, reactions, progress, surface, onControl, stream, endInterruptedStream, download, received, toAction, lifecycle, cancelInteraction, filter, startOn, delivery, } = options;
+    const { id, endpoint, key, inbound, bind, seed, outbound, ack, send, renderInteraction, onInteraction, finalizeInteraction, react, reactions, progress, surface, onControl, stream, endInterruptedStream, download, received, toAction, lifecycle, cancelInteraction, filter, startOn, delivery, errorMessage, } = options;
     if (!endpoint?.id) {
         throw new Error(`chat.channels.custom("${id}"): an endpoint is required. Declare one with webhooks.endpoint.define() and pass it as { endpoint }.`);
     }
@@ -3859,6 +3884,7 @@ export function chatChannelCustom(options) {
         lifecycle,
         cancelInteraction,
         delivery: delivery ?? "final",
+        errorMessage,
     };
 }
 const chatChannels = {
@@ -4356,6 +4382,7 @@ function makeChannelProgressObserver(connector, wireEvent, handle) {
     const progress = connector.progress;
     const turnCtx = channelTurnCtx(wireEvent, handle);
     const toolNames = new Map();
+    const toolTitles = new Map();
     let chain = Promise.resolve();
     let stopped = false;
     const emit = (event) => {
@@ -4378,6 +4405,10 @@ function makeChannelProgressObserver(connector, wireEvent, handle) {
             const c = chunk;
             if (!c?.type || !c.toolCallId)
                 return;
+            if (c.title)
+                toolTitles.set(c.toolCallId, c.title);
+            const title = toolTitles.get(c.toolCallId);
+            const titled = title ? { title } : {};
             if (c.type === "tool-input-start" && c.toolName) {
                 toolNames.set(c.toolCallId, c.toolName);
                 return;
@@ -4385,7 +4416,7 @@ function makeChannelProgressObserver(connector, wireEvent, handle) {
             if (c.type === "tool-input-available") {
                 const toolName = c.toolName ?? toolNames.get(c.toolCallId) ?? "tool";
                 toolNames.set(c.toolCallId, toolName);
-                emit({ type: "tool-call", toolCallId: c.toolCallId, toolName, input: c.input });
+                emit({ type: "tool-call", toolCallId: c.toolCallId, toolName, ...titled, input: c.input });
                 return;
             }
             if (c.type === "tool-output-available" && !c.preliminary) {
@@ -4393,6 +4424,7 @@ function makeChannelProgressObserver(connector, wireEvent, handle) {
                     type: "tool-result",
                     toolCallId: c.toolCallId,
                     toolName: toolNames.get(c.toolCallId) ?? "tool",
+                    ...titled,
                     output: c.output,
                 });
                 return;
@@ -4402,6 +4434,7 @@ function makeChannelProgressObserver(connector, wireEvent, handle) {
                     type: "tool-error",
                     toolCallId: c.toolCallId,
                     toolName: toolNames.get(c.toolCallId) ?? "tool",
+                    ...titled,
                     errorText: c.errorText ?? "tool failed",
                 });
             }
@@ -4493,6 +4526,7 @@ function stopPendingToolCalls(message, toolCallIds, errorText) {
  */
 function makeChannelReplyStreamObserver(stream) {
     const toolNames = new Map();
+    const toolTitles = new Map();
     let stopped = false;
     const safe = (fn) => {
         try {
@@ -4515,22 +4549,32 @@ function makeChannelReplyStreamObserver(stream) {
             if (!stream.progress || !c?.type || !c.toolCallId)
                 return;
             const toolCallId = c.toolCallId;
+            if (c.title)
+                toolTitles.set(toolCallId, c.title);
+            const title = toolTitles.get(toolCallId);
+            const titled = title ? { title } : {};
             if (c.type === "tool-input-start" && c.toolName) {
                 toolNames.set(toolCallId, c.toolName);
             }
             else if (c.type === "tool-input-available") {
                 const toolName = c.toolName ?? toolNames.get(toolCallId) ?? "tool";
                 toolNames.set(toolCallId, toolName);
-                safe(() => stream.progress({ type: "tool-call", toolCallId, toolName, input: c.input }));
+                safe(() => stream.progress({ type: "tool-call", toolCallId, toolName, ...titled, input: c.input }));
             }
             else if (c.type === "tool-output-available" && !c.preliminary) {
                 const toolName = toolNames.get(toolCallId) ?? "tool";
-                safe(() => stream.progress({ type: "tool-result", toolCallId, toolName, output: c.output }));
+                safe(() => stream.progress({
+                    type: "tool-result",
+                    toolCallId,
+                    toolName,
+                    ...titled,
+                    output: c.output,
+                }));
             }
             else if (c.type === "tool-output-error") {
                 const toolName = toolNames.get(toolCallId) ?? "tool";
                 const errorText = c.errorText ?? "tool failed";
-                safe(() => stream.progress({ type: "tool-error", toolCallId, toolName, errorText }));
+                safe(() => stream.progress({ type: "tool-error", toolCallId, toolName, ...titled, errorText }));
             }
         },
         stop() {
@@ -4812,7 +4856,9 @@ function chatCustomAgent(options) {
     return task;
 }
 function chatAgent(options) {
-    const { run: userRun, clientDataSchema, onBoot, onRecoveryBoot, onPreload, onChatStart, onValidateMessages, hydrateMessages, storage, actionSchema, events, channels, onAction, onTurnStart, onBeforeTurnComplete, onCompacted, compaction, pendingMessages: pendingMessagesConfig, prepareMessages, tools: toolsOption, onTurnComplete, maxTurns = 100, turnTimeout = "1h", idleTimeoutInSeconds = 30, chatAccessTokenTTL = "1h", preloadIdleTimeoutInSeconds, preloadTimeout, uiMessageStreamOptions, onChatSuspend, onChatResume, exitAfterPreloadIdle = false, oomMachine, registry: promptRegistry, system: agentSystem, cacheControl: agentCacheControl, systemProviderOptions: agentSystemProviderOptions, versionSkew, ...restOptions } = options;
+    const { run: userRun, clientDataSchema, onBoot, onRecoveryBoot, onPreload, onChatStart, onValidateMessages, hydrateMessages, storage, actionSchema, events, channels, onAction, onTurnStart, onBeforeTurnComplete, onCompacted, compaction, pendingMessages: pendingMessagesConfig, prepareMessages, tools: toolsOption, onTurnComplete, maxTurns = 100, turnTimeout = "1h", idleTimeoutInSeconds = 30, chatAccessTokenTTL = "1h", preloadIdleTimeoutInSeconds, preloadTimeout, uiMessageStreamOptions, onChatSuspend, onChatResume, exitAfterPreloadIdle = false, oomMachine, registry: promptRegistry, system: agentSystem, cacheControl: agentCacheControl, systemProviderOptions: agentSystemProviderOptions, versionSkew, telemetry: telemetryOptions, ...restOptions } = options;
+    const recordUserMessage = telemetryOptions?.recordUserMessage ?? true;
+    const recordClientData = telemetryOptions?.recordClientData ?? true;
     if (hydrateMessages) {
         if (storage) {
             throw new Error(`chat.agent: "${options.id}" sets both \`hydrateMessages\` and \`storage\`. ` +
@@ -6094,6 +6140,8 @@ function chatAgent(options) {
                     let channelFinalSendFailed = false;
                     /** The stream-level error (an `error` chunk) this turn ended on, if any; posted to the channel in place of an empty reply. */
                     let channelStreamErrorText;
+                    /** The original error behind that chunk, captured from `toUIMessageStream`'s `onError` when auto-piping. */
+                    let channelStreamError;
                     /** The text this turn streamed, so the channel reply is this turn's answer and not the whole message. */
                     let channelTurnText;
                     try {
@@ -6501,7 +6549,7 @@ function chatAgent(options) {
                                 : "tabler-message-chatbot",
                             [SemanticInternalAttributes.ENTITY_TYPE]: isAction ? "chat-action" : "chat-turn",
                         };
-                        if (lastUserMessage) {
+                        if (lastUserMessage && recordUserMessage) {
                             turnAttributes["chat.user_message"] = lastUserMessage;
                             // Show a truncated preview of the user message as an accessory
                             const preview = lastUserMessage.length > 80
@@ -6512,7 +6560,7 @@ function chatAgent(options) {
                                 style: "codepath",
                             }));
                         }
-                        if (wireMetadata !== undefined) {
+                        if (wireMetadata !== undefined && recordClientData) {
                             turnAttributes["chat.client_data"] =
                                 typeof wireMetadata === "string" ? wireMetadata : JSON.stringify(wireMetadata);
                         }
@@ -6537,6 +6585,7 @@ function chatAgent(options) {
                                 turn,
                                 continuation,
                                 clientData,
+                                recordUserMessage,
                             });
                             // Resolve the per-turn `tools` set now that turn context
                             // (incl. parsed clientData) exists, so every toModelMessages
@@ -7437,6 +7486,12 @@ function chatAgent(options) {
                                             // messageId. Without this, the frontend and backend generate IDs
                                             // independently and they won't match for ID-based dedup.
                                             generateMessageId: resolvedOptions.generateMessageId ?? generateMessageId,
+                                            onError: (error) => {
+                                                channelStreamError ??= error;
+                                                return resolvedOptions.onError
+                                                    ? resolvedOptions.onError(error)
+                                                    : uiStreamErrorText(error);
+                                            },
                                             onFinish: ({ responseMessage, finishReason, }) => {
                                                 capturedResponseMessage = responseMessage;
                                                 capturedPartialResponse = responseMessage;
@@ -7961,6 +8016,21 @@ function chatAgent(options) {
                                 const renderControls = !!((wireChannelEvent || boundTurn) &&
                                     pendingToolCalls.length > 0 &&
                                     channelConn?.renderInteraction);
+                                let channelErrorLine;
+                                if (channelStreamErrorText && (wireChannelEvent || boundTurn)) {
+                                    logger.warn("chat.agent: channel turn ended on a model or stream error", {
+                                        errorText: channelStreamErrorText,
+                                    });
+                                    channelErrorLine = await channelTurnErrorMessage(channelConn, {
+                                        error: channelStreamError instanceof Error
+                                            ? channelStreamError
+                                            : new Error(channelStreamErrorText),
+                                        partialText: channelTurnText?.trim() ?? "",
+                                        event: channelWireEvent?.event,
+                                        runId: ctx.run.id,
+                                        chatId: currentWirePayload.chatId,
+                                    });
+                                }
                                 let channelReplyDelivered = false;
                                 if (channelReplyStream) {
                                     const replyStream = channelReplyStream;
@@ -7969,7 +8039,9 @@ function chatAgent(options) {
                                         const ended = await replyStream.end({
                                             stopped: turnCompleteEvent.stopped,
                                             pending: renderControls,
-                                            ...(channelStreamErrorText ? { errorText: channelStreamErrorText } : {}),
+                                            ...(channelStreamErrorText
+                                                ? { errorText: channelErrorLine ?? CHANNEL_TURN_ERROR_MESSAGE }
+                                                : {}),
                                         });
                                         channelReplyDelivered = ended.delivered;
                                     }
@@ -7999,13 +8071,16 @@ function chatAgent(options) {
                                         ? channelTurnText
                                         : channelReplyText(turnCompleteEvent.responseMessage);
                                     // A model or stream error surfaces as an `error` chunk and an empty reply, not as a
-                                    // thrown turn. The mapper gets it on this one call, with the error text standing in
-                                    // for an empty reply, so the placeholder never sits there as if the agent were
-                                    // still working.
+                                    // thrown turn. The mapper gets it on this one call, with the connector's error line
+                                    // standing in for an empty reply, so the placeholder never sits there as if the agent
+                                    // were still working. The error text itself stays on the run, not in the channel.
                                     const finalReply = {
                                         // Prefer what this turn streamed; a resumed message carries earlier turns' text too.
-                                        text: channelStreamErrorText && replyText.trim().length === 0
-                                            ? channelStreamErrorText
+                                        // A failed turn always ends on the connector's error line, after any partial text.
+                                        text: channelErrorLine
+                                            ? replyText.trim().length > 0
+                                                ? `${replyText.trimEnd()}\n\n${channelErrorLine}`
+                                                : channelErrorLine
                                             : replyText,
                                         message: turnCompleteEvent.responseMessage,
                                         final: true,
@@ -8374,18 +8449,16 @@ function chatAgent(options) {
                                 logger.warn("chat.agent: channel error reaction failed", { error: reactionError });
                             }
                         }
-                        let channelErrorText = "An unexpected error occurred";
-                        if ((channelWireEvent || boundTurn) && channelConn) {
-                            const sanitizeChannelError = resolveUIMessageStreamOptions().onError;
-                            try {
-                                channelErrorText = sanitizeChannelError
-                                    ? sanitizeChannelError(turnError)
-                                    : turnError instanceof Error
-                                        ? turnError.message
-                                        : channelErrorText;
-                            }
-                            catch { }
-                        }
+                        // The channel gets the connector's error line, never the error itself: the run keeps that.
+                        const channelErrorText = channelReplyStream || ((channelWireEvent || boundTurn) && channelConn?.send)
+                            ? await channelTurnErrorMessage(channelConn, {
+                                error: turnError instanceof Error ? turnError : new Error(String(turnError)),
+                                partialText: channelTurnText?.trim() ?? "",
+                                event: channelWireEvent?.event,
+                                runId: ctx.run.id,
+                                chatId: currentWirePayload.chatId,
+                            })
+                            : CHANNEL_TURN_ERROR_MESSAGE;
                         let errorStreamDelivered = false;
                         if (channelReplyStream) {
                             const replyStream = channelReplyStream;