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

package/dist/esm/v3/ai.js

@@ -1,4 +1,6 @@
 import { accessoryAttributes, apiClientManager, controlSubtype, generateJWT, getSchemaParseFn, headerValue, InputStreamOncePromise, isAdditionalApiKey, isSchemaZodEsque, logger, ManualWaitpointPromise, OutOfMemoryError, resourceCatalog, SemanticInternalAttributes, SESSION_IN_CONSUMED_ID_HEADER, SESSION_IN_EVENT_ID_HEADER, sessionStreams, SessionChannelRouter, InputStreamTimeoutError, taskContext, TRIGGER_CONTROL_SUBTYPE, SESSION_CLOSED_HEADER, SESSION_CLOSED_REASON_HEADER, tryCatch, } from "@trigger.dev/core/v3";
+import { chatEvent, normalizeKeyString } from "./webhooks.js";
+import { fetchPublicFile } from "./modelFileDownload.js";
 // Runtime VALUES go through the ESM/CJS shim so the CJS build can `require`
 // ESM-only `ai@7` (see ../imports/ai-runtime.ts).
 import { trace } from "@opentelemetry/api";
@@ -73,6 +75,14 @@ const chatSessionHandleKey = locals.create("chat.sessionHandle");
 // is documented to carry. Custom-agent loops never set per-turn context, so subtask tool
 // metadata reads this directly rather than the Session handle id.
 const chatExternalIdKey = locals.create("chat.externalId");
+/**
+ * Set at boot when a continuation run inherited an interrupted turn (a
+ * partial assistant reply on `session.out`). Consumed by the first channel
+ * turn's ack so the re-emitted placeholder reads as a recovery resume rather
+ * than a silent duplicate. Boxed so the ack site can flip it to false.
+ * @internal
+ */
+const chatChannelRecoveryPendingKey = locals.create("chat.channelRecoveryPending");
 /**
  * S2 seq_num of the most recent `turn-complete` control record written by
  * this worker. Read by `writeTurnCompleteChunk` to know what to trim back
@@ -356,14 +366,23 @@ export function __setReplaySessionInTailImplForTests(impl) {
  * @internal
  */
 async function replaySessionInTail(sessionId, options) {
+    return (await replaySessionInTailWithChannels(sessionId, options)).messages;
+}
+/**
+ * The full unprocessed `session.in` tail: browser messages and channel deliveries, each with its
+ * seq_num, so recovery can dispatch them in the order they arrived rather than messages first.
+ */
+async function replaySessionInTailWithChannels(sessionId, options) {
     if (replaySessionInTailImpl) {
-        return await replaySessionInTailImpl(sessionId, options);
+        const replayed = await replaySessionInTailImpl(sessionId, options);
+        return Array.isArray(replayed) ? { messages: replayed, channelEvents: [] } : replayed;
     }
     const apiClient = apiClientManager.clientOrThrow();
     const response = await apiClient.readSessionStreamRecords(sessionId, "in", {
         afterEventId: options?.lastEventId,
     });
     const out = [];
+    const channelEvents = [];
     for (const record of response.records) {
         // session.in writers POST `JSON.stringify(chunk)` directly; the
         // webapp wraps that in `{ data: <string>, id }` and stores it on
@@ -390,15 +409,23 @@ async function replaySessionInTail(sessionId, options) {
         if (!payload || payload.trigger !== "submit-message")
             continue;
         const message = payload.message;
-        if (!message || typeof message !== "object")
+        if (!message || typeof message !== "object") {
+            if (payload.channelEvent && typeof payload.channelEvent === "object") {
+                channelEvents.push({
+                    channelEvent: payload.channelEvent,
+                    metadata: payload.metadata,
+                    seqNum: record.seqNum,
+                });
+            }
             continue;
+        }
         out.push({
             message: message,
             metadata: payload.metadata,
             seqNum: record.seqNum,
         });
     }
-    return out;
+    return { messages: out, channelEvents };
 }
 /**
  * Test-only entry point that bypasses
@@ -659,6 +686,37 @@ export const ai = {
 function createChatAccessToken(taskId) {
     return auth.createTriggerPublicToken(taskId, { expirationTime: "24h" });
 }
+/**
+ * Mint a read-only, session-scoped token for WATCHING a chat session by its `externalId`.
+ *
+ * A session is addressed by `externalId`, so the same session is reachable from any surface that
+ * knows it: a web `useChat` client and a Slack thread converge on one session when they share an
+ * `externalId` (for a channel, the connector's `key` template produces it). This token carries
+ * `read:sessions:{externalId}` only (no write): the holder can subscribe to the session's `.out`
+ * stream (observe the conversation, hydrating history from the snapshot) but cannot append to `.in`.
+ *
+ * Use it for a dashboard viewer or a cross-surface watcher of a Slack-thread session. Run server-side
+ * (needs the secret key). To CONTINUE a session from another surface (drive it, not just watch), mint
+ * a read+write token instead ({@link createChatStartSessionAction}).
+ *
+ * @example
+ * ```ts
+ * // actions.ts
+ * "use server";
+ * import { chat } from "@trigger.dev/sdk/ai";
+ *
+ * export const watchChat = (externalId: string) => chat.createWatchToken(externalId);
+ * ```
+ */
+function createChatWatchToken(externalId, options) {
+    if (!externalId) {
+        throw new Error("chat.createWatchToken: externalId is required (the session addressing key).");
+    }
+    return auth.createPublicToken({
+        scopes: { read: { sessions: externalId } },
+        expirationTime: options?.tokenTTL ?? "1h",
+    });
+}
 function createChatOutGate() {
     let resolveOpened;
     const opened = new Promise((resolve) => {
@@ -1895,7 +1953,16 @@ const chatInstructionsConsumedKey = locals.create("chat.injectedInstructionsCons
  * @internal
  */
 const chatPipeCountKey = locals.create("chat.pipeCount");
+/**
+ * The current turn's channel observer tap, set before run() when the turn has channel observers
+ * (ack stream edits, tool progress) and cleared at the turn boundary. `pipeChat` applies it so a
+ * manual `chat.pipe()` inside run() feeds the same observers as the automatic pipe.
+ * @internal
+ */
+const chatTurnChannelTapKey = locals.create("chat.turnChannelTap");
 const chatStopControllerKey = locals.create("chat.stopController");
+const chatChannelSurfaceKey = locals.create("chat.channelSurface");
+const chatChannelDownloadKey = locals.create("chat.channelDownload");
 /** Static (task-level) UIMessageStream options, set once during chatAgent setup. @internal */
 const chatUIStreamStaticKey = locals.create("chat.uiMessageStreamOptions.static");
 /** Per-turn UIMessageStream options, set via chat.setUIMessageStreamOptions(). @internal */
@@ -2867,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.
@@ -3006,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({
@@ -3271,7 +3337,7 @@ function buildManagedStreamTextOptions(options, config) {
      * caller's value winning because `rest` is spread after `managed`. Pulling a
      * key out to "handle" it is how a caller's option gets silently dropped.
      */
-    const { tools, system: callerSystem, prepareStep: callerPrepareStep, ...rest } = options;
+    const { tools, system: callerSystem, prepareStep: callerPrepareStep, experimental_download: callerDownload, ...rest } = options;
     const managed = toStreamTextOptions({
         registry,
         system: callerSystem ?? agentSystem,
@@ -3314,6 +3380,12 @@ function buildManagedStreamTextOptions(options, config) {
     if (typeof managed.prepareStep === "function") {
         managed.prepareStep = retainStepMessages(managed.prepareStep);
     }
+    if (typeof callerDownload === "function") {
+        const channelDownload = locals.get(chatChannelDownloadKey);
+        managed.experimental_download = channelDownload
+            ? channelAwareDownload(channelDownload, callerDownload)
+            : callerDownload;
+    }
     return { ...managed, ...rest };
 }
 /** @internal Test hook for {@link buildManagedStreamTextOptions}. */
@@ -3543,6 +3615,10 @@ function toStreamTextOptions(options, retain = true) {
     if (retain && typeof result.prepareStep === "function") {
         result.prepareStep = retainStepMessages(result.prepareStep);
     }
+    const channelDownload = locals.get(chatChannelDownloadKey);
+    if (channelDownload) {
+        result.experimental_download = channelAwareDownload(channelDownload);
+    }
     return result;
 }
 const actionTurnBrand = Symbol.for("trigger.dev/chat/actionTurn");
@@ -3557,6 +3633,9 @@ const actionTurnBrand = Symbol.for("trigger.dev/chat/actionTurn");
  * tools, steering, compaction, injected instructions and persistence, with no
  * action-specific handling.
  *
+ * Pass `message` to have the turn answer a new user message, appended after the edit: a click on a
+ * "Explain more" button becomes `chat.turn("Explain that in more detail.")`.
+ *
  * @example
  * ```ts
  * onAction: async ({ action }) => {
@@ -3564,12 +3643,13 @@ const actionTurnBrand = Symbol.for("trigger.dev/chat/actionTurn");
  *     chat.history.slice(0, -1);
  *     return chat.turn();
  *   }
+ *   if (action.type === "ask") return chat.turn(action.question);
  *   if (action.type === "undo") chat.history.slice(0, -2); // no turn
  * },
  * ```
  */
-function chatTurn() {
-    return { [actionTurnBrand]: true };
+function chatTurn(message) {
+    return (message === undefined ? { [actionTurnBrand]: true } : { [actionTurnBrand]: true, message });
 }
 function isActionTurn(value) {
     return typeof value === "object" && value !== null && value[actionTurnBrand] === true;
@@ -3635,6 +3715,21 @@ function warnMissingOnActionOnce() {
 function isAsyncIterable(value) {
     return typeof value === "object" && value !== null && Symbol.asyncIterator in value;
 }
+function readableStreamFromAsyncIterable(source) {
+    const iterator = source[Symbol.asyncIterator]();
+    return new ReadableStream({
+        async pull(controller) {
+            const next = await iterator.next();
+            if (next.done)
+                controller.close();
+            else
+                controller.enqueue(next.value);
+        },
+        async cancel(reason) {
+            await iterator.return?.(reason);
+        },
+    });
+}
 function isReadableStream(value) {
     return (typeof value === "object" && value !== null && typeof value.getReader === "function");
 }
@@ -3690,6 +3785,10 @@ async function pipeChat(source, options, capture) {
         throw new Error("pipeChat: source must be a StreamTextResult (with .toUIMessageStream()), " +
             "an AsyncIterable, or a ReadableStream");
     }
+    const channelTap = locals.get(chatTurnChannelTapKey);
+    if (channelTap) {
+        stream = channelTap(isReadableStream(stream) ? stream : readableStreamFromAsyncIterable(stream));
+    }
     const pipeOptions = {};
     if (options?.signal) {
         pipeOptions.signal = options.signal;
@@ -3719,155 +3818,1069 @@ async function pipeChat(source, options, capture) {
         await waitUntilComplete();
     }
 }
-function chatCustomAgent(options) {
-    const { clientDataSchema, onClientDataValidationError, clientDataReportErrorAt, run: userRun, ...restOptions } = options;
-    const parseClientData = clientDataSchema ? getSchemaParseFn(clientDataSchema) : undefined;
-    const parseClientDataSync = clientDataSchema
-        ? getChatCustomAgentSyncSchemaParseFn(clientDataSchema)
-        : undefined;
-    const task = createTask({
-        ...restOptions,
-        triggerSource: "agent",
-        agentConfig: { type: "ai-sdk-chat" },
-        run: async (payload, runOptions) => {
-            // Bind the run to its backing Session so module-level helpers
-            // (chat.messages, chat.stream, chat.createStopSignal, chat.createSession)
-            // resolve to this chat's `.in` / `.out` channels. Address
-            // everywhere by `payload.chatId` (the session externalId) so the
-            // agent's writes and the transport's reads converge on the same
-            // S2 stream key + waitpoint key.
-            //
-            // The Session row is created server-side by `POST /sessions` (or
-            // `chat.createStartSessionAction`) before this run is triggered.
-            // No client-side upsert needed.
-            locals.set(chatSessionHandleKey, sessions.open(payload.chatId));
-            locals.set(chatExternalIdKey, payload.chatId);
-            locals.set(chatAgentRunContextKey, runOptions.ctx);
-            locals.set(chatCustomAgentRunKey, true);
-            if (parseClientData && parseClientDataSync) {
-                locals.set(chatCustomAgentClientDataParserKey, {
-                    parse: parseClientData,
-                    parseSync: parseClientDataSync,
-                });
+/** 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, 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 }.`);
+    }
+    resourceCatalog.registerDeclaredSessionWebhook(id);
+    return {
+        id,
+        endpointId: endpoint.id,
+        source: endpoint.source,
+        key: normalizeKeyString(key),
+        filter,
+        startOn,
+        inbound,
+        bind,
+        seed,
+        outbound,
+        ack,
+        send,
+        renderInteraction,
+        onInteraction,
+        finalizeInteraction,
+        react,
+        reactions,
+        progress,
+        surface,
+        onControl,
+        stream,
+        endInterruptedStream,
+        download,
+        received,
+        toAction,
+        lifecycle,
+        cancelInteraction,
+        delivery: delivery ?? "final",
+        errorMessage,
+    };
+}
+const chatChannels = {
+    /** A generic chat-frontend channel over any source, with your own egress. See {@link chatChannelCustom}. */
+    custom: chatChannelCustom,
+};
+// Prior surface messages from a connector's seed(), as transcript messages stamped with provenance.
+function channelSeedMessages(seed, provenance) {
+    return seed
+        .filter((m) => m && typeof m.text === "string" && m.text.length > 0)
+        .map((m, index) => {
+        const meta = {
+            ...provenance,
+            seeded: true,
+            ...(m.externalUserId ? { externalUserId: m.externalUserId } : {}),
+            ...(m.externalMessageId ? { externalMessageId: m.externalMessageId } : {}),
+        };
+        return {
+            id: `seed-${m.externalMessageId ?? `${provenance.deliveryId}-${index}`}`,
+            role: m.role === "assistant" ? "assistant" : "user",
+            parts: [{ type: "text", text: m.text }],
+            metadata: meta,
+        };
+    });
+}
+// Turn a channel connector's inbound() result into the turn's user UIMessage, stamped with where
+// it came from so a transcript storage can attribute it (see ChannelMessageMetadata).
+/**
+ * True when a connector's `inbound()` result carries nothing to answer: blank text and no file or
+ * data parts. A button click from another app on a shared endpoint maps to one.
+ */
+function isEmptyChannelInbound(input) {
+    const message = input !== null && typeof input === "object" && "message" in input && !("role" in input)
+        ? input.message
+        : input;
+    if (typeof message === "string")
+        return message.trim() === "";
+    return (message.parts ?? []).every((part) => part.type === "text" && part.text?.trim() === "");
+}
+/** Bytes held for a run's channel file downloads before the oldest are dropped and fetched again. */
+const CHANNEL_DOWNLOAD_CACHE_BYTES = 64 * 1024 * 1024;
+/**
+ * One downloader for a run's connectors that define `download`: asks each in turn (the ones bound to
+ * the session first, the next one after a failure) and caches what they return by URL, so a file in
+ * the history is fetched once per run rather than per step.
+ */
+function makeChannelDownloader(connectors, handleFor) {
+    const downloaders = connectors.filter((c) => typeof c.download === "function");
+    if (downloaders.length === 0)
+        return undefined;
+    const cache = new Map();
+    const sizes = new Map();
+    let cachedBytes = 0;
+    const evict = () => {
+        for (const key of cache.keys()) {
+            if (cachedBytes <= CHANNEL_DOWNLOAD_CACHE_BYTES)
+                return;
+            cachedBytes -= sizes.get(key) ?? 0;
+            sizes.delete(key);
+            cache.delete(key);
+        }
+    };
+    const fetchOwned = async (url) => {
+        const candidates = downloaders.map((connector) => ({
+            connector,
+            handle: handleFor(connector.id),
+        }));
+        const ordered = [
+            ...candidates.filter((c) => c.handle !== undefined),
+            ...candidates.filter((c) => c.handle === undefined),
+        ];
+        let failure;
+        for (const { connector, handle } of ordered) {
+            try {
+                const file = await connector.download(url, { handle });
+                if (file)
+                    return file;
             }
-            if (onClientDataValidationError) {
-                locals.set(chatCustomAgentClientDataErrorHandlerKey, onClientDataValidationError);
+            catch (error) {
+                failure ??= { error };
             }
-            locals.set(chatCustomAgentClientDataErrorTimingKey, clientDataReportErrorAt ?? "turn-end");
-            // Initialize the turn-complete trim slot so `chat.writeTurnComplete`
-            // trims `session.out` back to the previous turn boundary. Without
-            // this the slot is undefined and the trim never runs, so `.out`
-            // grows without bound for the whole custom-agent surface.
-            locals.set(lastTurnCompleteSeqNumKey, { value: undefined });
-            markChatAgentRunForStreamsWarning();
-            taskContext.setConversationId(payload.chatId);
-            stampConversationIdOnActiveSpan(payload.chatId);
-            await installChatInputRouter(payload.chatId, {
-                resuming: Boolean(payload.continuation),
-            });
-            // A custom agent's loop is the customer's, so there is no exit site the
-            // SDK controls. Perform a requested close when `run()` returns, whatever
-            // shape the loop had. Idempotent, so the createSession iterator having
-            // already closed on its own exit costs nothing.
-            const withClose = async (result) => {
-                try {
-                    return await result;
-                }
-                finally {
-                    await performChatClose();
-                }
-            };
-            // Keep the schema-free path identical to the original custom-agent
-            // wrapper, including when userRun starts executing.
-            if (!parseClientData) {
-                return withClose(userRun(payload, runOptions));
+        }
+        if (failure)
+            throw failure.error;
+        return null;
+    };
+    return (url) => {
+        const key = url.href;
+        const cached = cache.get(key);
+        if (cached)
+            return cached;
+        const pending = fetchOwned(url).then((file) => {
+            if (file && cache.get(key) === pending) {
+                sizes.set(key, file.data.byteLength);
+                cachedBytes += file.data.byteLength;
+                evict();
             }
-            const isHandoverBoot = payload.trigger === "handover-prepare";
-            const isMessagelessBoot = payload.trigger === "preload" ||
-                (payload.continuation === true &&
-                    payload.message === undefined &&
-                    payload.trigger !== "action" &&
-                    payload.trigger !== "regenerate-message" &&
-                    !isHandoverBoot);
-            const validated = await validateChatCustomAgentPayload(payload, {
-                // Preload and continuation boots do not represent a submitted turn,
-                // so there is no sender waiting for a terminal frame. Handover errors
-                // must be written after the warm response flushes and signals below.
-                writeErrorToStream: !isMessagelessBoot && !isHandoverBoot,
+            return file;
+        }, (error) => {
+            if (cache.get(key) === pending)
+                cache.delete(key);
+            throw error;
+        });
+        cache.set(key, pending);
+        return pending;
+    };
+}
+function fileUrlOf(part) {
+    const p = part;
+    const raw = p?.type === "file" ? p.data : p?.type === "image" ? p.image : undefined;
+    if (raw instanceof URL)
+        return raw;
+    if (typeof raw !== "string" || !/^https?:\/\//i.test(raw))
+        return undefined;
+    try {
+        return new URL(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Fetch the channel-owned files in the messages a turn hands to `run()`, so the model call reads
+ * them from the cache. A file a connector owns but cannot read becomes a text note in this turn's
+ * copy of the messages, and the turn still runs. The transcript keeps the URL.
+ */
+async function resolveChannelFiles(messages, download) {
+    const failed = new Set();
+    const mediaTypes = new Map();
+    const urls = new Map();
+    for (const message of messages) {
+        if (!Array.isArray(message.content))
+            continue;
+        for (const part of message.content) {
+            const url = fileUrlOf(part);
+            if (url)
+                urls.set(url.href, url);
+        }
+    }
+    await Promise.all([...urls.values()].map(async (url) => {
+        try {
+            const file = await download(url);
+            if (file?.mediaType)
+                mediaTypes.set(url.href, file.mediaType);
+        }
+        catch (error) {
+            failed.add(url.href);
+            logger.warn("chat.agent: a channel file could not be downloaded; the model gets a note", {
+                url: url.origin + url.pathname,
+                error,
             });
-            if (validated.ok) {
-                return withClose(userRun(validated.payload, runOptions));
-            }
-            if (isHandoverBoot) {
-                const signal = await waitForHandover({
-                    payload,
-                    timeout: "1h",
-                    spanName: "waiting for handover signal (invalid clientData)",
-                });
-                if (!signal || signal.kind === "handover-skip") {
-                    return;
-                }
-                // The head-start writer flushes before sending this signal. Writing
-                // the terminal error now preserves stream order and closes the stitch.
-                await writeChatCustomAgentClientDataErrorToStream(payload);
-                return;
+        }
+    }));
+    const isWildcard = (part) => {
+        const mediaType = part.mediaType;
+        return part.type === "file" && !!mediaType && mediaType.endsWith("/*");
+    };
+    return messages.map((message) => {
+        if (!Array.isArray(message.content))
+            return message;
+        let changed = false;
+        const content = message.content.map((part) => {
+            const url = fileUrlOf(part);
+            if (!url)
+                return part;
+            if (failed.has(url.href)) {
+                changed = true;
+                const name = part.filename;
+                return {
+                    type: "text",
+                    text: `[Attached file${name ? ` "${name}"` : ""} could not be loaded]`,
+                };
             }
-            // The Session base payload is sticky across continuation runs. If it is
-            // invalid, returning here would boot the same bad metadata again on the
-            // next message. Stay attached and wait for a valid wire frame instead.
-            const next = await messagesInput.waitWithIdleTimeout({
-                idleTimeoutInSeconds: payload.idleTimeoutInSeconds ?? 30,
-                timeout: "1h",
-                spanName: "waiting for valid clientData",
-            });
-            if (!next.ok || next.output.trigger === "close") {
-                return;
+            const downloaded = mediaTypes.get(url.href);
+            if (downloaded && isWildcard(part)) {
+                changed = true;
+                return { ...part, mediaType: downloaded };
             }
-            // Normal input frames omit run-level boot context. Carry it forward so
-            // a continuation still tells the custom loop to restore prior state.
-            const recoveredPayload = {
-                ...next.output,
-                continuation: next.output.continuation ?? payload.continuation,
-                previousRunId: next.output.previousRunId ?? payload.previousRunId,
-                sessionId: next.output.sessionId ?? payload.sessionId,
-                idleTimeoutInSeconds: next.output.idleTimeoutInSeconds ?? payload.idleTimeoutInSeconds,
-            };
-            return withClose(userRun(recoveredPayload, runOptions));
-        },
+            return part;
+        });
+        return changed ? { ...message, content } : message;
     });
-    // Register clientDataSchema so the CLI converts it to JSONSchema
-    // and stores it as payloadSchema — used by the Playground UI
-    if (clientDataSchema) {
-        resourceCatalog.updateTaskMetadata(options.id, {
-            schema: clientDataSchema,
+}
+/**
+ * The AI SDK `experimental_download` for a turn: channel-owned URLs come from the connectors, and
+ * every other URL goes to `fallback`, or to the AI SDK's default behaviour (left for a model that
+ * reads the URL itself, fetched from a public host otherwise).
+ */
+function channelAwareDownload(download, fallback) {
+    return async (requests) => {
+        const results = await Promise.all(requests.map(async (request) => {
+            const file = await download(request.url);
+            return file ? { data: file.data, mediaType: file.mediaType } : null;
+        }));
+        const misses = requests.flatMap((_, i) => (results[i] ? [] : [i]));
+        if (misses.length === 0)
+            return results;
+        const rest = fallback
+            ? await fallback(misses.map((i) => requests[i]))
+            : await Promise.all(misses.map((i) => requests[i].isUrlSupportedByModel ? null : fetchPublicFile(requests[i].url)));
+        misses.forEach((i, n) => {
+            results[i] = rest[n] ?? null;
         });
+        return results;
+    };
+}
+/** The action a channel click maps to through its connector's `toAction()`, if it maps to one. */
+function channelClickAction(connectors, wire) {
+    const channelEvent = wire;
+    if (!channelEvent?.connectorId)
+        return undefined;
+    const connector = connectors?.find((c) => c.id === channelEvent.connectorId);
+    if (!connector?.toAction)
+        return undefined;
+    try {
+        return connector.toAction(channelEvent.event) ?? undefined;
+    }
+    catch (error) {
+        logger.warn("chat.agent: channel toAction() threw; handling the delivery as a message", {
+            error,
+        });
+        return undefined;
     }
-    return task;
 }
-function chatAgent(options) {
-    const { run: userRun, clientDataSchema, onBoot, onRecoveryBoot, onPreload, onChatStart, onValidateMessages, hydrateMessages, storage, actionSchema, 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;
-    if (hydrateMessages) {
-        if (storage) {
-            throw new Error(`chat.agent: "${options.id}" sets both \`hydrateMessages\` and \`storage\`. ` +
-                "`hydrateMessages` is deprecated and replaced by the storage: `save` receives every " +
-                "change and `loadContext` on the storage owns the model's context. Remove `hydrateMessages`.");
-        }
-        if (typeof (transcriptStorageOverride ?? defaultStorage).loadContext === "function") {
-            throw new Error(`chat.agent: "${options.id}" sets \`hydrateMessages\` and uses a transcript storage with ` +
-                "`loadContext`. Both would own the model's context; keep one.");
-        }
-        warnHydrateMessagesDeprecatedOnce(options.id);
+/**
+ * A channel delivery that arrived during a turn, as a message `pendingMessages` can steer into it:
+ * the connector's `inbound()` with channel provenance. Undefined for what must not be steered (a
+ * stop or other control, an interaction such as an approval click, an empty message, a connector
+ * this agent does not list), which stays queued as its own turn.
+ */
+function channelSteeringMessage(connectors, wire, messageId) {
+    const connector = connectors?.find((c) => c.id === wire.connectorId);
+    if (!connector)
+        return undefined;
+    try {
+        if (connector.onControl?.(wire.event))
+            return undefined;
+        if (connector.onInteraction?.(wire.event))
+            return undefined;
+        if (connector.toAction?.(wire.event) != null)
+            return undefined;
+        const inbound = connector.inbound(wire.event);
+        if (isEmptyChannelInbound(inbound))
+            return undefined;
+        const message = channelUserMessage(inbound, messageId ?? wire.deliveryId, {
+            source: "channel",
+            connectorId: connector.id,
+            provider: connector.source,
+            deliveryId: wire.deliveryId,
+            ...(wire.externalDeliveryId ? { externalDeliveryId: wire.externalDeliveryId } : {}),
+        });
+        return { message };
     }
-    const parseClientData = clientDataSchema ? getSchemaParseFn(clientDataSchema) : undefined;
-    const parseAction = actionSchema ? getSchemaParseFn(actionSchema) : undefined;
-    // chat.agent does not expose generic retry options (see docstring on
-    // `oomMachine`). The only opt-in is an OOM-triggered machine swap. If
-    // `oomMachine` is set we allow one retry on a larger machine; otherwise
-    // we keep the historical no-retry default.
-    const retry = oomMachine
-        ? { maxAttempts: 2, outOfMemory: { machine: oomMachine } }
-        : { maxAttempts: 1 };
-    const task = createTask({
+    catch (error) {
+        logger.warn("chat.agent: a channel message could not be offered for steering; it runs as its own turn", {
+            error,
+        });
+        return undefined;
+    }
+}
+/**
+ * Call the connector's `received` for a message that arrived mid-turn, unless it is not a message
+ * to answer (an interaction click, an action click, an empty message). Fire and forget.
+ */
+function acknowledgeChannelMessage(connector, wire, handle) {
+    if (!connector.received)
+        return;
+    try {
+        if (connector.onInteraction?.(wire.event))
+            return;
+        if (connector.toAction?.(wire.event) != null)
+            return;
+        if (isEmptyChannelInbound(connector.inbound(wire.event)))
+            return;
+        void Promise.resolve(connector.received({
+            event: wire.event,
+            deliveryId: wire.deliveryId,
+            handle,
+            bound: false,
+        })).catch(() => { });
+    }
+    catch {
+        return;
+    }
+}
+function channelUserMessage(input, messageId, provenance) {
+    const wrapped = input !== null && typeof input === "object" && "message" in input && !("role" in input);
+    const message = (wrapped ? input.message : input);
+    const extra = wrapped
+        ? input
+        : {};
+    const meta = {
+        ...provenance,
+        ...(extra.externalUserId ? { externalUserId: extra.externalUserId } : {}),
+        ...(extra.externalMessageId ? { externalMessageId: extra.externalMessageId } : {}),
+    };
+    const base = typeof message === "string"
+        ? { id: messageId, role: "user", parts: [{ type: "text", text: message }] }
+        : message.id
+            ? message
+            : { ...message, id: messageId };
+    const existing = base.metadata;
+    return {
+        ...base,
+        metadata: { ...(existing && typeof existing === "object" ? existing : {}), ...meta },
+    };
+}
+/**
+ * The assistant's closing text for a channel reply: the text after the last tool part in the message,
+ * so a pre-tool preamble (e.g. the HITL "I'll need approval first" line, or a "let me look that up")
+ * is dropped and only the answer is posted. Falls back to all text when there's no trailing text or no
+ * tool parts (an ordinary turn), so a plain reply is unchanged.
+ */
+function channelReplyText(message) {
+    const parts = (message.parts ?? []);
+    const isTool = (p) => {
+        const t = p?.type;
+        return typeof t === "string" && (t.startsWith("tool-") || t === "dynamic-tool");
+    };
+    let lastToolIdx = -1;
+    parts.forEach((p, i) => {
+        if (isTool(p))
+            lastToolIdx = i;
+    });
+    const textFrom = (from) => parts
+        .slice(from)
+        .map((p) => p && typeof p === "object" && p.type === "text"
+        ? String(p.text)
+        : "")
+        .join("");
+    const trailing = textFrom(lastToolIdx + 1);
+    return trailing.trim().length > 0 ? trailing : textFrom(0);
+}
+/**
+ * Tries at a turn's final channel reply before it is given up on and the turn shows the error
+ * reaction. Only an edit of the ack placeholder is retried: a failed post may still have landed, so
+ * a post is tried once.
+ */
+const CHANNEL_FINAL_SEND_ATTEMPTS = 3;
+/** Tool parts of a UIMessage awaiting a human answer (`input-available`), for `renderInteraction`. */
+function pendingToolCallsInMessage(message) {
+    const out = [];
+    for (const part of (message.parts ?? [])) {
+        if (!part || typeof part !== "object")
+            continue;
+        const type = part.type;
+        const isTool = typeof type === "string" && (type.startsWith("tool-") || type === "dynamic-tool");
+        if (!isTool || part.state !== "input-available")
+            continue;
+        const toolName = type === "dynamic-tool" ? String(part.toolName ?? "") : String(type).slice("tool-".length);
+        if (typeof part.toolCallId === "string")
+            out.push({ toolCallId: part.toolCallId, toolName, input: part.input });
+    }
+    return out;
+}
+/**
+ * Fill in `toolCallId` on a resolution that names the tool instead: the most recent assistant part of
+ * that tool still awaiting input. Returns the resolution unchanged when it already has an id, and
+ * undefined when no pending call of that tool exists.
+ */
+function resolveInteractionToolCallId(resolution, messages) {
+    if (resolution.toolCallId) {
+        return resolution;
+    }
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (message.role !== "assistant")
+            continue;
+        for (const call of pendingToolCallsInMessage(message).reverse()) {
+            if (call.toolName === resolution.toolName) {
+                return { ...resolution, toolCallId: call.toolCallId };
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Build the slim assistant message the HITL resume path expects (mirrors `slimSubmitMessageForWire`):
+ * the pending tool part matched by `toolCallId` across `messages`, advanced to `output-available` with
+ * the interaction's output. Returns undefined when no pending part matches (a stale/duplicate callback).
+ */
+function buildInteractionResolutionMessage(resolution, messages, provenance) {
+    // Resolved anywhere means resolved: a resumed turn can carry the same tool call in more than
+    // one assistant message, and a second click on a decided call must not resolve a stale copy.
+    for (const message of messages) {
+        if (message.role !== "assistant")
+            continue;
+        for (const part of (message.parts ?? [])) {
+            if (part && typeof part === "object" && part.toolCallId === resolution.toolCallId) {
+                if (isResolvedToolState(part.state))
+                    return undefined;
+            }
+        }
+    }
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (message.role !== "assistant")
+            continue;
+        for (const part of (message.parts ?? [])) {
+            if (!part || typeof part !== "object" || part.toolCallId !== resolution.toolCallId)
+                continue;
+            const type = part.type;
+            const isTool = typeof type === "string" && (type.startsWith("tool-") || type === "dynamic-tool");
+            if (!isTool)
+                continue;
+            if (part.state !== "input-available")
+                return undefined;
+            const slimPart = {
+                type,
+                toolCallId: resolution.toolCallId,
+                state: "output-available",
+                output: resolution.output,
+            };
+            if (type === "dynamic-tool" && typeof part.toolName === "string")
+                slimPart.toolName = part.toolName;
+            return {
+                id: message.id,
+                role: "assistant",
+                parts: [slimPart],
+                ...(provenance ? { metadata: provenance } : {}),
+            };
+        }
+    }
+    return undefined;
+}
+// Default outbound: post the reply text, or nothing when empty (a tool-only / empty turn).
+function defaultChannelOutbound(reply) {
+    return reply.text ? { text: reply.text } : null;
+}
+// Resolve a lifecycle reaction choice to one emoji name for this turn: call a resolver if given, then
+// pick one at random from an array. Returns undefined to skip (no choice / empty).
+export async function resolveReactionChoice(choice, event) {
+    if (choice == null)
+        return undefined;
+    let value = typeof choice === "function" ? await choice(event) : choice;
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return undefined;
+        value = value[Math.floor(Math.random() * value.length)];
+    }
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+// Best-effort reaction on the triggering message; a failure never breaks the turn.
+async function applyChannelReaction(connector, wireEvent, reaction) {
+    if (!connector?.react || !wireEvent || !reaction.name)
+        return;
+    try {
+        await connector.react(reaction, { event: wireEvent.event, deliveryId: wireEvent.deliveryId });
+    }
+    catch (error) {
+        logger.warn("chat.agent: channel reaction failed", { error, name: reaction.name });
+    }
+}
+// The run()-facing reaction surface for a channel turn (flavor 2). Undefined when the connector has no
+// `react`, so `payload.channel` is only present when reacting is actually possible.
+function buildChannelRunSurface(connector, wireEvent, handle) {
+    if (!connector)
+        return undefined;
+    const canReact = !!connector.react && !!wireEvent;
+    if (!canReact && !connector.surface)
+        return undefined;
+    const turnCtx = channelTurnCtx(wireEvent, handle);
+    let extra = {};
+    if (connector.surface) {
+        try {
+            extra = connector.surface(turnCtx) ?? {};
+        }
+        catch (error) {
+            logger.warn("chat.agent: channel surface() threw; continuing without it", { error });
+        }
+    }
+    const noop = async () => { };
+    return {
+        ...extra,
+        react: canReact ? (name) => applyChannelReaction(connector, wireEvent, { name }) : noop,
+        unreact: canReact
+            ? (name) => applyChannelReaction(connector, wireEvent, { name, remove: true })
+            : noop,
+    };
+}
+function channelTurnCtx(wireEvent, handle) {
+    return {
+        ...(wireEvent ? { event: wireEvent.event, deliveryId: wireEvent.deliveryId } : {}),
+        ...(handle !== undefined ? { handle } : {}),
+        bound: !wireEvent,
+    };
+}
+/**
+ * Feed a connector's `progress()` from the UI message stream: a tool call once its input is available,
+ * then its result or error. Calls are serialized so the surface sees them in order; a throw is logged.
+ * `stop()` refuses further chunks and drains what is already queued, so a slow first post does not
+ * lose the results behind it, and nothing new lands after the turn ended.
+ */
+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) => {
+        chain = chain.then(async () => {
+            try {
+                await progress(event, turnCtx);
+            }
+            catch (error) {
+                logger.warn("chat.agent: channel progress() failed; continuing", {
+                    error,
+                    type: event.type,
+                });
+            }
+        });
+    };
+    return {
+        observe(chunk) {
+            if (stopped)
+                return;
+            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;
+            }
+            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, ...titled, input: c.input });
+                return;
+            }
+            if (c.type === "tool-output-available" && !c.preliminary) {
+                emit({
+                    type: "tool-result",
+                    toolCallId: c.toolCallId,
+                    toolName: toolNames.get(c.toolCallId) ?? "tool",
+                    ...titled,
+                    output: c.output,
+                });
+                return;
+            }
+            if (c.type === "tool-output-error") {
+                emit({
+                    type: "tool-error",
+                    toolCallId: c.toolCallId,
+                    toolName: toolNames.get(c.toolCallId) ?? "tool",
+                    ...titled,
+                    errorText: c.errorText ?? "tool failed",
+                });
+            }
+        },
+        async stop() {
+            stopped = true;
+            await chain;
+        },
+    };
+}
+/** Re-send `working` this often during a long turn: Slack drops a processing status after an hour. */
+const CHANNEL_WORKING_REFRESH_MS = 50 * 60 * 1000;
+/**
+ * Report a session's lifecycle to its connector in order, one call at a time, and re-send `working`
+ * while a long turn runs. Every report bumps a sequence number and a refresh only fires while its
+ * `working` is still the latest report, so a refresh can never land after the turn went idle.
+ */
+function makeChannelLifecycleReporter() {
+    let chain = Promise.resolve();
+    let seq = 0;
+    let refreshTimer;
+    let closed = false;
+    const clearRefresh = () => {
+        if (refreshTimer)
+            clearTimeout(refreshTimer);
+        refreshTimer = undefined;
+    };
+    const enqueue = (connector, state, ctx, reportSeq) => {
+        chain = chain.then(async () => {
+            if (ctx.refresh && reportSeq !== seq)
+                return;
+            try {
+                await connector.lifecycle(state, ctx);
+            }
+            catch (error) {
+                logger.warn("chat.agent: channel lifecycle() failed; continuing", { error, state });
+            }
+        });
+        return chain;
+    };
+    return {
+        report(connector, state, ctx) {
+            if (!connector?.lifecycle || closed)
+                return Promise.resolve();
+            if (state === "closed")
+                closed = true;
+            const reportSeq = ++seq;
+            clearRefresh();
+            const done = enqueue(connector, state, ctx, reportSeq);
+            if (state === "working") {
+                const arm = () => {
+                    refreshTimer = setTimeout(() => {
+                        if (reportSeq !== seq)
+                            return;
+                        void enqueue(connector, "working", { ...ctx, firstTurn: false, refresh: true }, reportSeq);
+                        arm();
+                    }, CHANNEL_WORKING_REFRESH_MS);
+                    refreshTimer.unref?.();
+                };
+                arm();
+            }
+            return done;
+        },
+        dispose: clearRefresh,
+    };
+}
+/**
+ * The assistant message with the given pending tool calls resolved as stopped (`output-error`), for
+ * a stop that arrives while the session waits on a human decision. Undefined when none matched.
+ */
+function stopPendingToolCalls(message, toolCallIds, errorText) {
+    let changed = false;
+    const parts = (message.parts ?? []).map((part) => {
+        if (part &&
+            typeof part === "object" &&
+            toolCallIds.has(part.toolCallId) &&
+            part.state === "input-available") {
+            changed = true;
+            return { ...part, state: "output-error", errorText };
+        }
+        return part;
+    });
+    return changed ? { ...message, parts } : undefined;
+}
+/**
+ * Feed a connector's native reply stream from the UI message stream: text deltas as they arrive, and
+ * tool progress when the stream accepts it. `stop()` only refuses further chunks; the turn boundary
+ * ends the stream itself with the turn's outcome.
+ */
+function makeChannelReplyStreamObserver(stream) {
+    const toolNames = new Map();
+    const toolTitles = new Map();
+    let stopped = false;
+    const safe = (fn) => {
+        try {
+            fn();
+        }
+        catch (error) {
+            logger.warn("chat.agent: channel reply stream threw; continuing", { error });
+        }
+    };
+    return {
+        observe(chunk) {
+            if (stopped)
+                return;
+            const c = chunk;
+            if (c?.type === "text-delta" && typeof c.delta === "string") {
+                const delta = c.delta;
+                safe(() => stream.text(delta));
+                return;
+            }
+            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, ...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,
+                    ...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, ...titled, errorText }));
+            }
+        },
+        stop() {
+            stopped = true;
+        },
+    };
+}
+function composeChannelObservers(observers) {
+    return {
+        observe(chunk) {
+            for (const o of observers)
+                o.observe(chunk);
+        },
+        async stop() {
+            await Promise.all(observers.map((o) => o.stop()));
+        },
+    };
+}
+// "stream" egress: as the reply streams, debounce-edit the ack message (previousRef) with the growing
+// text. Trailing-edge, one edit per interval (Slack chat.update ~1/s); the turn-complete final edit is
+// the authoritative last write. Best-effort: an edit failure is logged, never fatal.
+const CHANNEL_STREAM_EDIT_INTERVAL_MS = 1000;
+function makeChannelStreamEditor(connector, channelEvent, ackRef, handle) {
+    const outbound = connector.outbound ?? defaultChannelOutbound;
+    let latest = "";
+    let lastSent = "";
+    let timer;
+    let inFlightPromise;
+    let stopped = false;
+    const arm = () => {
+        if (stopped || timer)
+            return;
+        timer = setTimeout(() => {
+            timer = undefined;
+            void edit();
+        }, CHANNEL_STREAM_EDIT_INTERVAL_MS);
+    };
+    const edit = async () => {
+        if (stopped || inFlightPromise)
+            return;
+        const text = latest;
+        if (text === lastSent)
+            return;
+        const message = outbound({
+            text,
+            message: { id: ackRef, role: "assistant", parts: [{ type: "text", text }] },
+            final: false,
+            stopped: false,
+        });
+        if (!message)
+            return;
+        inFlightPromise = (async () => {
+            try {
+                await connector.send(message, {
+                    event: channelEvent.event,
+                    handle,
+                    deliveryId: channelEvent.deliveryId,
+                    previousRef: ackRef,
+                    mode: "stream",
+                    final: false,
+                    bound: false,
+                });
+                lastSent = text;
+            }
+            catch (error) {
+                logger.warn("chat.agent: channel stream edit failed", { error });
+            }
+            finally {
+                inFlightPromise = undefined;
+                if (!stopped && latest !== lastSent)
+                    arm();
+            }
+        })();
+        await inFlightPromise;
+    };
+    return {
+        observe(chunk) {
+            if (stopped)
+                return;
+            const c = chunk;
+            if (c?.type === "text-delta" && typeof c.delta === "string") {
+                latest += c.delta;
+                arm();
+            }
+        },
+        async stop() {
+            stopped = true;
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            if (inFlightPromise) {
+                try {
+                    await inFlightPromise;
+                }
+                catch { }
+            }
+        },
+    };
+}
+/**
+ * Wrap the reply stream so it debounce-edits the channel message as it streams.
+ * Both `flush` (the stream completed) and `cancel` (the stream was aborted or
+ * cancelled downstream) stop the editor, so a pending debounce timer can never
+ * fire an edit after the turn ended, onto a message the next turn already owns.
+ */
+/**
+ * Feed every chunk of a stream to `editor`. By default the editor is stopped when the stream ends or
+ * is cancelled (one stream per turn, the automatic pipe). With `stopOnEnd: false` the editor outlives
+ * the stream, for a turn whose run() pipes several streams through `chat.pipe()`; the turn boundary
+ * stops it.
+ */
+function makeChannelStreamTap(editor, options = {}) {
+    const stopOnEnd = options.stopOnEnd ?? true;
+    const transformer = {
+        transform(chunk, controller) {
+            editor.observe(chunk);
+            controller.enqueue(chunk);
+        },
+        async flush() {
+            if (stopOnEnd)
+                await editor.stop();
+        },
+        async cancel() {
+            if (stopOnEnd)
+                await editor.stop();
+        },
+    };
+    return new TransformStream(transformer);
+}
+export { makeChannelStreamEditor as __makeChannelStreamEditorForTests, makeChannelStreamTap as __makeChannelStreamTapForTests, makeChannelProgressObserver as __makeChannelProgressObserverForTests, makeChannelLifecycleReporter as __makeChannelLifecycleReporterForTests, };
+/**
+ * Per-chat latch for the channel egress that runs AFTER `trigger:turn-complete` is written (the
+ * final `send()` and the done/error reactions). The run loop opens it before writing the chunk and
+ * settles it once that egress has finished, so a caller that saw the chunk can wait for the
+ * connector to be quiet instead of guessing with timers. One latch per chat at a time; a chat with
+ * no open latch is quiet.
+ */
+const channelEgressLatches = new Map();
+function openChannelEgressLatch(chatId) {
+    let settle;
+    const promise = new Promise((resolve) => (settle = resolve));
+    channelEgressLatches.set(chatId, { promise, settle });
+}
+function settleChannelEgressLatch(chatId) {
+    const latch = channelEgressLatches.get(chatId);
+    if (!latch)
+        return;
+    channelEgressLatches.delete(chatId);
+    latch.settle();
+}
+/** Resolves once the post-turn channel egress for `chatId` has finished (immediately when none is running). */
+export async function __waitForChannelEgressForTests(chatId) {
+    await channelEgressLatches.get(chatId)?.promise;
+}
+function chatCustomAgent(options) {
+    const { clientDataSchema, onClientDataValidationError, clientDataReportErrorAt, run: userRun, ...restOptions } = options;
+    const parseClientData = clientDataSchema ? getSchemaParseFn(clientDataSchema) : undefined;
+    const parseClientDataSync = clientDataSchema
+        ? getChatCustomAgentSyncSchemaParseFn(clientDataSchema)
+        : undefined;
+    const task = createTask({
+        ...restOptions,
+        triggerSource: "agent",
+        agentConfig: { type: "ai-sdk-chat" },
+        run: async (payload, runOptions) => {
+            // Bind the run to its backing Session so module-level helpers
+            // (chat.messages, chat.stream, chat.createStopSignal, chat.createSession)
+            // resolve to this chat's `.in` / `.out` channels. Address
+            // everywhere by `payload.chatId` (the session externalId) so the
+            // agent's writes and the transport's reads converge on the same
+            // S2 stream key + waitpoint key.
+            //
+            // The Session row is created server-side by `POST /sessions` (or
+            // `chat.createStartSessionAction`) before this run is triggered.
+            // No client-side upsert needed.
+            locals.set(chatSessionHandleKey, sessions.open(payload.chatId));
+            locals.set(chatExternalIdKey, payload.chatId);
+            locals.set(chatAgentRunContextKey, runOptions.ctx);
+            locals.set(chatCustomAgentRunKey, true);
+            if (parseClientData && parseClientDataSync) {
+                locals.set(chatCustomAgentClientDataParserKey, {
+                    parse: parseClientData,
+                    parseSync: parseClientDataSync,
+                });
+            }
+            if (onClientDataValidationError) {
+                locals.set(chatCustomAgentClientDataErrorHandlerKey, onClientDataValidationError);
+            }
+            locals.set(chatCustomAgentClientDataErrorTimingKey, clientDataReportErrorAt ?? "turn-end");
+            // Initialize the turn-complete trim slot so `chat.writeTurnComplete`
+            // trims `session.out` back to the previous turn boundary. Without
+            // this the slot is undefined and the trim never runs, so `.out`
+            // grows without bound for the whole custom-agent surface.
+            locals.set(lastTurnCompleteSeqNumKey, { value: undefined });
+            markChatAgentRunForStreamsWarning();
+            taskContext.setConversationId(payload.chatId);
+            stampConversationIdOnActiveSpan(payload.chatId);
+            await installChatInputRouter(payload.chatId, {
+                resuming: Boolean(payload.continuation),
+            });
+            // A custom agent's loop is the customer's, so there is no exit site the
+            // SDK controls. Perform a requested close when `run()` returns, whatever
+            // shape the loop had. Idempotent, so the createSession iterator having
+            // already closed on its own exit costs nothing.
+            const withClose = async (result) => {
+                try {
+                    return await result;
+                }
+                finally {
+                    await performChatClose();
+                }
+            };
+            // Keep the schema-free path identical to the original custom-agent
+            // wrapper, including when userRun starts executing.
+            if (!parseClientData) {
+                return withClose(userRun(payload, runOptions));
+            }
+            const isHandoverBoot = payload.trigger === "handover-prepare";
+            const isMessagelessBoot = payload.trigger === "preload" ||
+                (payload.continuation === true &&
+                    payload.message === undefined &&
+                    payload.trigger !== "action" &&
+                    payload.trigger !== "regenerate-message" &&
+                    !isHandoverBoot);
+            const validated = await validateChatCustomAgentPayload(payload, {
+                // Preload and continuation boots do not represent a submitted turn,
+                // so there is no sender waiting for a terminal frame. Handover errors
+                // must be written after the warm response flushes and signals below.
+                writeErrorToStream: !isMessagelessBoot && !isHandoverBoot,
+            });
+            if (validated.ok) {
+                return withClose(userRun(validated.payload, runOptions));
+            }
+            if (isHandoverBoot) {
+                const signal = await waitForHandover({
+                    payload,
+                    timeout: "1h",
+                    spanName: "waiting for handover signal (invalid clientData)",
+                });
+                if (!signal || signal.kind === "handover-skip") {
+                    return;
+                }
+                // The head-start writer flushes before sending this signal. Writing
+                // the terminal error now preserves stream order and closes the stitch.
+                await writeChatCustomAgentClientDataErrorToStream(payload);
+                return;
+            }
+            // The Session base payload is sticky across continuation runs. If it is
+            // invalid, returning here would boot the same bad metadata again on the
+            // next message. Stay attached and wait for a valid wire frame instead.
+            const next = await messagesInput.waitWithIdleTimeout({
+                idleTimeoutInSeconds: payload.idleTimeoutInSeconds ?? 30,
+                timeout: "1h",
+                spanName: "waiting for valid clientData",
+            });
+            if (!next.ok || next.output.trigger === "close") {
+                return;
+            }
+            // Normal input frames omit run-level boot context. Carry it forward so
+            // a continuation still tells the custom loop to restore prior state.
+            const recoveredPayload = {
+                ...next.output,
+                continuation: next.output.continuation ?? payload.continuation,
+                previousRunId: next.output.previousRunId ?? payload.previousRunId,
+                sessionId: next.output.sessionId ?? payload.sessionId,
+                idleTimeoutInSeconds: next.output.idleTimeoutInSeconds ?? payload.idleTimeoutInSeconds,
+            };
+            return withClose(userRun(recoveredPayload, runOptions));
+        },
+    });
+    // Register clientDataSchema so the CLI converts it to JSONSchema
+    // and stores it as payloadSchema — used by the Playground UI
+    if (clientDataSchema) {
+        resourceCatalog.updateTaskMetadata(options.id, {
+            schema: clientDataSchema,
+        });
+    }
+    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, 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\`. ` +
+                "`hydrateMessages` is deprecated and replaced by the storage: `save` receives every " +
+                "change and `loadContext` on the storage owns the model's context. Remove `hydrateMessages`.");
+        }
+        if (typeof (transcriptStorageOverride ?? defaultStorage).loadContext === "function") {
+            throw new Error(`chat.agent: "${options.id}" sets \`hydrateMessages\` and uses a transcript storage with ` +
+                "`loadContext`. Both would own the model's context; keep one.");
+        }
+        warnHydrateMessagesDeprecatedOnce(options.id);
+    }
+    const parseClientData = clientDataSchema ? getSchemaParseFn(clientDataSchema) : undefined;
+    const parseAction = actionSchema ? getSchemaParseFn(actionSchema) : undefined;
+    // chat.agent does not expose generic retry options (see docstring on
+    // `oomMachine`). The only opt-in is an OOM-triggered machine swap. If
+    // `oomMachine` is set we allow one retry on a larger machine; otherwise
+    // we keep the historical no-retry default.
+    const retry = oomMachine
+        ? { maxAttempts: 2, outOfMemory: { machine: oomMachine } }
+        : { maxAttempts: 1 };
+    const task = createTask({
         ...restOptions,
         retry,
         triggerSource: "agent",
@@ -4011,6 +5024,69 @@ function chatAgent(options) {
                     : undefined;
             let transcriptShadow = createTranscriptShadow([]);
             let bootTranscriptState = null;
+            /**
+             * The channel this session answers into (see TranscriptChannelBinding). Set by a channel turn
+             * whose connector defines `bind`, restored from runtime state at boot, saved on every changeset.
+             */
+            let sessionChannelBinding;
+            const channelDownloader = channels
+                ? makeChannelDownloader(channels, (connectorId) => sessionChannelBinding?.connectorId === connectorId
+                    ? sessionChannelBinding.handle
+                    : undefined)
+                : undefined;
+            locals.set(chatChannelDownloadKey, channelDownloader);
+            /**
+             * Tool calls that already have channel controls posted. A turn that resumes with one of
+             * several pending calls resolved still carries the others as pending; without this the
+             * controls would be posted again, and the model's final text would lose to them. A
+             * continuation worker seeds it at boot from the calls still pending in the restored
+             * transcript of a channel-bound session, since the worker before it posted their controls.
+             */
+            const channelRenderedToolCallIds = new Set();
+            /** Serializes `lifecycle()` reports for the session's channel across turns. */
+            const channelLifecycle = makeChannelLifecycleReporter();
+            /**
+             * Pending calls a channel stop resolved as stopped on this worker. A click on their old controls
+             * is dropped even when the transcript was hydrated again from a store that never saw the stop.
+             */
+            const channelStoppedToolCallIds = new Set();
+            /** When the latest channel turn started, so a stop pressed before it is recognized as stale. */
+            let lastChannelTurnStartedAt;
+            /** When the latest channel turn ended, so a stop pressed while it ran is not run as a new turn. */
+            let lastChannelTurnEndedAt;
+            /** The turn reported its end state: the binding no longer marks the surface as working. */
+            const clearChannelWorking = () => {
+                if (!sessionChannelBinding?.working)
+                    return;
+                const { working: _working, ...rest } = sessionChannelBinding;
+                void _working;
+                sessionChannelBinding = rest;
+            };
+            /** The turn's reply stream ended: the binding no longer names it for recovery. */
+            const clearOpenReplyStream = () => {
+                if (!sessionChannelBinding?.stream)
+                    return;
+                const { stream: _stream, ...rest } = sessionChannelBinding;
+                void _stream;
+                sessionChannelBinding = rest;
+            };
+            /** Tell the bound channel the conversation is over (`chat.close()` or a close signal). */
+            const reportChannelClosed = async () => {
+                const binding = sessionChannelBinding;
+                if (!binding)
+                    return;
+                const connector = channels?.find((c) => c.id === binding.connectorId);
+                await channelLifecycle.report(connector, "closed", {
+                    handle: binding.handle,
+                    bound: true,
+                    firstTurn: false,
+                });
+            };
+            /** Provenance of the turn or action being processed, for the storage context. */
+            let currentTurnSource = "client";
+            let currentTurnConnectorId;
+            /** True once `onAction` returned `chat.turn()` for the action being processed. */
+            let turnIsActionTurn = false;
             /**
              * True while the model lane holds a compaction summary, so it cannot be
              * rebuilt from the transcript and has to be persisted as state. Reset
@@ -4073,9 +5149,14 @@ function chatAgent(options) {
                 const transcriptIds = new Set(opts.messages.map((message) => message.id));
                 const markerIds = new Set(steeringMarkers(opts.messages).map((marker) => marker.id));
                 const steering = [...(locals.get(chatSteeringInjectionsKey)?.values() ?? [])].filter((entry) => markerIds.has(entry.id) || entry.messageIds.some((id) => transcriptIds.has(id)));
-                const runtimeState = laneCompacted || laneInjections.length > 0 || queued.length > 0 || steering.length > 0
+                const runtimeState = laneCompacted ||
+                    laneInjections.length > 0 ||
+                    queued.length > 0 ||
+                    steering.length > 0 ||
+                    sessionChannelBinding
                     ? {
                         v: 1,
+                        ...(sessionChannelBinding ? { channelBinding: sessionChannelBinding } : {}),
                         ...(laneCompacted
                             ? {
                                 compaction: {
@@ -4105,7 +5186,9 @@ function chatAgent(options) {
                     chatId: payload.chatId,
                     clientData: opts.clientData,
                     turn: opts.turn,
-                    trigger: opts.trigger,
+                    trigger: opts.trigger === "action" && turnIsActionTurn ? "action-turn" : opts.trigger,
+                    source: currentTurnSource,
+                    ...(currentTurnConnectorId ? { connectorId: currentTurnConnectorId } : {}),
                     runId: ctx.run.id,
                     ctx,
                 }, {
@@ -4188,6 +5271,9 @@ function chatAgent(options) {
             let replayedPartial;
             let replayedPartialRaw;
             let replayedInTail = [];
+            // Channel deliveries on the same tail. They are not "messages" for the recovery hooks, but
+            // they are turns the predecessor owed, and they have to dispatch in seq order with the rest.
+            let replayedChannelInTail = [];
             // Wire payloads to dispatch as turns before the regular session.in
             // pump kicks in. Populated by `onRecoveryBoot.recoveredTurns` (or its
             // default, `inFlightUsers`). The turn-loop checks this queue ahead of
@@ -4318,9 +5404,11 @@ function chatAgent(options) {
                         }
                         bootSpan.setAttribute("chat.boot.replay.in.cursorFromSnapshot", snapshotInCursor !== undefined);
                         try {
-                            replayedInTail = await replaySessionInTail(payload.chatId, {
+                            const tail = await replaySessionInTailWithChannels(payload.chatId, {
                                 lastEventId: bootInCursor !== undefined ? String(bootInCursor) : undefined,
                             });
+                            replayedInTail = tail.messages;
+                            replayedChannelInTail = tail.channelEvents;
                         }
                         catch (error) {
                             logger.warn("chat.agent: session.in replay failed; in-flight users may not be recovered", { error: error instanceof Error ? error.message : String(error) });
@@ -4341,7 +5429,10 @@ function chatAgent(options) {
             }
             // ── session.in router ──────────────────────────────────────────
             //
-            const recoveredSeqNums = replayedInTail.map((r) => r.seqNum);
+            const recoveredSeqNums = [
+                ...replayedInTail.map((r) => r.seqNum),
+                ...replayedChannelInTail.map((r) => r.seqNum),
+            ];
             await installChatInputRouter(payload.chatId, {
                 fallbackResumeFrom: bootInCursorResolved ? bootInCursor : undefined,
                 recoveredSeqNums,
@@ -4358,6 +5449,9 @@ function chatAgent(options) {
                 // predecessor chose to end before processing the message;
                 // those route through the normal continuation-wait path.
                 const hasRecoveredState = partialAssistant !== undefined;
+                if (couldHavePriorState && hasRecoveredState) {
+                    locals.set(chatChannelRecoveryPendingKey, { value: true });
+                }
                 let hookChain;
                 let hookRecoveredTurns;
                 let hookBeforeBoot;
@@ -4428,10 +5522,18 @@ function chatAgent(options) {
                 // user is re-dispatched as a fresh turn instead.
                 let seedChain;
                 let recoveredEntries;
+                // The orphan-partial splice pairs the partial assistant with the oldest unprocessed record,
+                // which only makes sense when that record is the browser message it was answering. When a
+                // channel delivery is older than every browser message, the partial belongs to it instead, and
+                // splicing the first browser message ahead of it would reorder the conversation.
+                const oldestTailSeq = Math.min(...replayedInTail.map((r) => r.seqNum), ...replayedChannelInTail.map((r) => r.seqNum));
+                const partialFollowsBrowserMessage = partialAssistant !== undefined &&
+                    inFlightUsers.length > 1 &&
+                    (replayedChannelInTail.length === 0 || replayedInTail[0]?.seqNum === oldestTailSeq);
                 if (hookChain !== undefined) {
                     seedChain = hookChain;
                 }
-                else if (partialAssistant !== undefined && inFlightUsers.length > 1) {
+                else if (partialFollowsBrowserMessage) {
                     seedChain = [...settledMessages, inFlightUsers[0], partialAssistant];
                 }
                 else {
@@ -4451,7 +5553,7 @@ function chatAgent(options) {
                         seqNum: seqNumsByRecoveredId.get(message.id)?.shift(),
                     }));
                 }
-                else if (partialAssistant !== undefined && inFlightUsers.length > 1) {
+                else if (partialFollowsBrowserMessage) {
                     recoveredEntries = replayedInTail
                         .slice(1)
                         .map((r) => ({ message: r.message, seqNum: r.seqNum }));
@@ -4488,6 +5590,7 @@ function chatAgent(options) {
                     metadataById.set(entry.message.id, entry.metadata);
                 }
                 const dispatchedRecoveredSeqs = new Set();
+                const toInject = [];
                 for (const { message: msg, seqNum } of recoveredEntries) {
                     if (wireMessageId && msg.id === wireMessageId)
                         continue;
@@ -4504,13 +5607,37 @@ function chatAgent(options) {
                         continuation: payload.continuation,
                         previousRunId: payload.previousRunId,
                     };
+                    toInject.push({ injectedPayload, seqNum });
+                }
+                // Channel deliveries the predecessor never processed dispatch too, interleaved with the
+                // browser messages by seq_num so a Slack message that arrived before a browser message
+                // still runs before it. A delivery the boot payload itself carries is not queued twice.
+                const wireDeliveryId = payload.channelEvent
+                    ?.deliveryId;
+                for (const entry of replayedChannelInTail) {
+                    const entryDeliveryId = entry.channelEvent.deliveryId;
+                    if (wireDeliveryId && entryDeliveryId === wireDeliveryId)
+                        continue;
+                    const injectedPayload = {
+                        chatId: payload.chatId,
+                        sessionId: payload.sessionId,
+                        metadata: entry.metadata ?? payload.metadata,
+                        trigger: "submit-message",
+                        channelEvent: entry.channelEvent,
+                        continuation: payload.continuation,
+                        previousRunId: payload.previousRunId,
+                    };
+                    toInject.push({ injectedPayload, seqNum: entry.seqNum });
+                }
+                toInject.sort((a, b) => (a.seqNum ?? Infinity) - (b.seqNum ?? Infinity));
+                for (const { injectedPayload, seqNum } of toInject) {
                     bootInjectedQueue.push(injectedPayload);
                     if (seqNum !== undefined) {
                         recoveredSeqByPayload.set(injectedPayload, seqNum);
                         dispatchedRecoveredSeqs.add(seqNum);
                     }
                 }
-                for (const entry of replayedInTail) {
+                for (const entry of [...replayedInTail, ...replayedChannelInTail]) {
                     if (!dispatchedRecoveredSeqs.has(entry.seqNum)) {
                         chatInputRouter().settleRecovered(entry.seqNum);
                     }
@@ -4553,15 +5680,47 @@ function chatAgent(options) {
                         catch (error) {
                             logger.warn("chat.agent: tools() resolver threw at boot; restored history converted without toModelOutput", { error: error instanceof Error ? error.message : String(error) });
                         }
-                    }
-                    try {
-                        const bootRuntimeState = parseTranscriptRuntimeState(bootTranscriptState);
-                        locals.set(chatSteeringInjectionsKey, new Map((bootRuntimeState?.steering ?? []).map((entry) => [entry.id, entry])));
-                        locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
-                        const restored = await restoreModelLane(accumulatedUIMessages, bootRuntimeState, (messages) => toModelMessages(messages));
-                        accumulatedMessages = restored.messages;
-                        laneCompacted = restored.compacted;
-                        laneInjections = restored.injections;
+                    }
+                    try {
+                        const bootRuntimeState = parseTranscriptRuntimeState(bootTranscriptState);
+                        locals.set(chatSteeringInjectionsKey, new Map((bootRuntimeState?.steering ?? []).map((entry) => [entry.id, entry])));
+                        locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
+                        const restored = await restoreModelLane(accumulatedUIMessages, bootRuntimeState, (messages) => toModelMessages(messages));
+                        accumulatedMessages = restored.messages;
+                        laneCompacted = restored.compacted;
+                        laneInjections = restored.injections;
+                        sessionChannelBinding = bootRuntimeState?.channelBinding;
+                        const interruptedStream = sessionChannelBinding?.stream;
+                        if (interruptedStream && sessionChannelBinding) {
+                            const binding = sessionChannelBinding;
+                            const connector = channels?.find((c) => c.id === binding.connectorId);
+                            clearOpenReplyStream();
+                            if (connector?.endInterruptedStream) {
+                                try {
+                                    await connector.endInterruptedStream(interruptedStream, {
+                                        handle: binding.handle,
+                                        bound: true,
+                                    });
+                                }
+                                catch (error) {
+                                    logger.warn("chat.agent: ending the interrupted reply stream failed", { error });
+                                }
+                            }
+                        }
+                        if (sessionChannelBinding?.working) {
+                            const binding = sessionChannelBinding;
+                            clearChannelWorking();
+                            await channelLifecycle.report(channels?.find((c) => c.id === binding.connectorId), "idle", { handle: binding.handle, bound: true, firstTurn: false });
+                        }
+                        if (sessionChannelBinding) {
+                            for (const message of accumulatedUIMessages) {
+                                if (message.role !== "assistant")
+                                    continue;
+                                for (const call of pendingToolCallsInMessage(message)) {
+                                    channelRenderedToolCallIds.add(call.toolCallId);
+                                }
+                            }
+                        }
                         if (bootRuntimeState?.queued && bootRuntimeState.queued.length > 0) {
                             locals.set(chatBackgroundQueueKey, [
                                 ...(locals.get(chatBackgroundQueueKey) ?? []),
@@ -4948,26 +6107,434 @@ function chatAgent(options) {
                     // Declared here so the finally can detach it — a handler leaked past
                     // its turn duplicates every mid-stream message into the shared buffer.
                     let turnMsgSub;
+                    let turnControlSub;
                     let capturedPartialResponse;
                     let responseCommitted = false;
                     const turnBufferedChunks = [];
+                    let channelConn;
+                    let channelWorkingReaction;
+                    let channelWireEvent;
+                    /** The connector's posting handle for this turn: from `bind(event)` on a channel turn, else the session binding. */
+                    let channelHandle;
+                    /** True when no channel delivery started this turn and egress goes through the session binding. */
+                    let boundTurn = false;
+                    let channelAckRef;
+                    let channelStreamEditor;
+                    let droppedStaleInteraction = false;
+                    /** True when the connector mapped this delivery to an empty message: no turn runs. */
+                    let droppedEmptyMessage = false;
+                    let droppedUnknownConnector = false;
+                    /** True when this delivery was a stop the connector drops while idle: no turn runs. */
+                    let droppedIdleControl = false;
+                    /** This turn's native reply stream (`delivery: "stream"` with a `stream()` hook). */
+                    let channelReplyStream;
+                    /** True once this turn reported `working`, so its end reports the outcome. */
+                    let channelLifecycleStarted = false;
+                    /** When this turn started, to tell a stop meant for an earlier turn from one for this turn. */
+                    const channelTurnStartedAt = Date.now();
+                    /** True when this turn is a channel or bound turn that runs (not a dropped delivery). */
+                    let channelTurnRan = false;
+                    /** True when this turn resolves a pending tool call from a channel interaction callback. */
+                    let channelInteractionResolved = false;
+                    let channelFinalAnswerPosted = false;
+                    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 {
                         // Extract turn-level context before entering the span. Slim
                         // wire: at most one delta message per record. `headStartMessages`
                         // is consumed at boot only (via `payload.headStartMessages`)
                         // and intentionally discarded here.
-                        const { metadata: wireMetadata, message: incomingMessage, headStartMessages: _hsm, ...restWire } = currentWirePayload;
+                        const clickedAction = channelClickAction(channels, currentWirePayload.channelEvent);
+                        let actionChannel;
+                        if (clickedAction !== undefined) {
+                            const { channelEvent: clicked, ...withoutChannelEvent } = currentWirePayload;
+                            const click = clicked;
+                            actionChannel = {
+                                connectorId: click.connectorId,
+                                provider: channels?.find((c) => c.id === click.connectorId)?.source ?? "custom",
+                                event: click.event,
+                                deliveryId: click.deliveryId,
+                            };
+                            currentWirePayload = {
+                                ...withoutChannelEvent,
+                                trigger: "action",
+                                action: clickedAction,
+                                actionSource: "channel",
+                            };
+                        }
+                        const { metadata: wireMetadata, message: incomingMessage, headStartMessages: _hsm, channelEvent: wireChannelEvent, ...restWire } = currentWirePayload;
                         void _hsm;
-                        const incomingMessages = incomingMessage
-                            ? [incomingMessage]
+                        channelWireEvent = wireChannelEvent;
+                        let effectiveIncomingMessage = incomingMessage;
+                        const clientData = (parseClientData ? await parseClientData(wireMetadata) : wireMetadata);
+                        turnClientData = clientData;
+                        turnIsActionTurn = false;
+                        currentTurnSource = wireChannelEvent
+                            ? "channel"
+                            : currentWirePayload.actionSource === "webhook"
+                                ? "webhook"
+                                : "client";
+                        currentTurnConnectorId = undefined;
+                        if (wireChannelEvent) {
+                            channelConn = channels?.find((c) => c.id === wireChannelEvent.connectorId);
+                            if (channelConn) {
+                                currentTurnConnectorId = channelConn.id;
+                                let idleControl = null;
+                                if (channelConn.onControl) {
+                                    try {
+                                        idleControl = channelConn.onControl(wireChannelEvent.event);
+                                    }
+                                    catch (controlError) {
+                                        logger.warn("chat.agent: channel onControl threw; treating as a message", {
+                                            error: controlError,
+                                        });
+                                    }
+                                }
+                                const stopForEndedTurn = idleControl?.at !== undefined &&
+                                    lastChannelTurnEndedAt !== undefined &&
+                                    idleControl.at < lastChannelTurnEndedAt;
+                                droppedIdleControl =
+                                    idleControl?.kind === "stop" &&
+                                        (idleControl.whenIdle === "drop" || stopForEndedTurn);
+                                // Bind the session to this connector so a later turn that no channel delivery
+                                // started (an action turn, a browser message) can still answer into the thread.
+                                if (channelConn.bind && !droppedIdleControl) {
+                                    try {
+                                        const handle = channelConn.bind(wireChannelEvent.event);
+                                        if (handle !== null && handle !== undefined) {
+                                            const controls = sessionChannelBinding?.connectorId === channelConn.id
+                                                ? sessionChannelBinding.controls
+                                                : undefined;
+                                            sessionChannelBinding = {
+                                                connectorId: channelConn.id,
+                                                handle,
+                                                boundAt: new Date().toISOString(),
+                                                deliveryId: wireChannelEvent.deliveryId,
+                                                ...(controls ? { controls } : {}),
+                                            };
+                                        }
+                                    }
+                                    catch (bindError) {
+                                        logger.warn("chat.agent: channel bind() failed; session binding unchanged", {
+                                            error: bindError,
+                                        });
+                                    }
+                                }
+                                channelHandle =
+                                    sessionChannelBinding?.connectorId === channelConn.id
+                                        ? sessionChannelBinding.handle
+                                        : undefined;
+                                const rawInteraction = droppedIdleControl
+                                    ? null
+                                    : (channelConn.onInteraction?.(wireChannelEvent.event) ?? null);
+                                let interaction = rawInteraction
+                                    ? (resolveInteractionToolCallId(rawInteraction, accumulatedUIMessages) ?? null)
+                                    : null;
+                                const accumulatorHasInteractionToolCall = interaction != null &&
+                                    accumulatedUIMessages.some((m) => (m.parts ?? []).some((p) => p?.toolCallId === interaction.toolCallId));
+                                if (rawInteraction && loadContextHook && !accumulatorHasInteractionToolCall) {
+                                    try {
+                                        const hydratedForInteraction = (await loadContextHook({
+                                            chatId: currentWirePayload.chatId,
+                                            turn,
+                                            trigger: "submit-message",
+                                            incomingMessages: [],
+                                            previousMessages: [...accumulatedUIMessages],
+                                            clientData,
+                                            continuation,
+                                            previousRunId,
+                                        }));
+                                        accumulatedUIMessages = hydratedForInteraction;
+                                        accumulatedMessages = await toModelMessages(hydratedForInteraction);
+                                        laneCompacted = false;
+                                        laneInjections = [];
+                                        locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
+                                        if (!interaction) {
+                                            interaction =
+                                                resolveInteractionToolCallId(rawInteraction, accumulatedUIMessages) ?? null;
+                                        }
+                                    }
+                                    catch (hydrateError) {
+                                        logger.warn("chat.agent: hydrateMessages for channel interaction resolution failed", { error: hydrateError });
+                                    }
+                                }
+                                const resolutionMessage = interaction && !channelStoppedToolCallIds.has(interaction.toolCallId)
+                                    ? buildInteractionResolutionMessage(interaction, accumulatedUIMessages, {
+                                        source: "channel",
+                                        connectorId: channelConn.id,
+                                        provider: channelConn.source,
+                                        deliveryId: wireChannelEvent.deliveryId,
+                                    })
+                                    : undefined;
+                                const channelInbound = droppedIdleControl || resolutionMessage || rawInteraction
+                                    ? undefined
+                                    : channelConn.inbound(wireChannelEvent.event);
+                                if (droppedIdleControl) {
+                                    const staleStop = idleControl?.at !== undefined &&
+                                        lastChannelTurnStartedAt !== undefined &&
+                                        idleControl.at < lastChannelTurnStartedAt;
+                                    if (!staleStop && loadContextHook && accumulatedUIMessages.length === 0) {
+                                        try {
+                                            const hydratedForStop = (await loadContextHook({
+                                                chatId: currentWirePayload.chatId,
+                                                turn,
+                                                trigger: "submit-message",
+                                                incomingMessages: [],
+                                                previousMessages: [],
+                                                clientData,
+                                                continuation,
+                                                previousRunId,
+                                            }));
+                                            accumulatedUIMessages = hydratedForStop;
+                                            accumulatedMessages = await toModelMessages(hydratedForStop);
+                                            laneCompacted = false;
+                                            laneInjections = [];
+                                            locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
+                                        }
+                                        catch (hydrateError) {
+                                            logger.warn("chat.agent: hydrateMessages for a channel stop failed", {
+                                                error: hydrateError,
+                                            });
+                                        }
+                                    }
+                                    let lastAssistantIndex = -1;
+                                    for (let i = accumulatedUIMessages.length - 1; i >= 0; i--) {
+                                        if (accumulatedUIMessages[i].role === "assistant") {
+                                            lastAssistantIndex = i;
+                                            break;
+                                        }
+                                    }
+                                    const lastAssistant = lastAssistantIndex === -1
+                                        ? undefined
+                                        : accumulatedUIMessages[lastAssistantIndex];
+                                    const stoppedCalls = lastAssistant && !staleStop && idleControl?.whenIdle === "drop"
+                                        ? pendingToolCallsInMessage(lastAssistant)
+                                        : [];
+                                    if (lastAssistant && stoppedCalls.length > 0) {
+                                        const errorText = idleControl?.message || "stopped";
+                                        const stoppedMessage = stopPendingToolCalls(lastAssistant, new Set(stoppedCalls.map((call) => call.toolCallId)), errorText);
+                                        if (stoppedMessage) {
+                                            accumulatedUIMessages = accumulatedUIMessages.map((m, i) => i === lastAssistantIndex ? stoppedMessage : m);
+                                            const pausedRun = await toModelMessages([
+                                                stripProviderMetadata(lastAssistant),
+                                            ]);
+                                            if (pausedRun.length === 0) {
+                                                accumulatedMessages = [
+                                                    ...accumulatedMessages,
+                                                    ...(await toModelMessages([stoppedMessage])),
+                                                ];
+                                            }
+                                            else if (!(await replaceModelRun(accumulatedMessages, lastAssistant, stoppedMessage, 0, pausedRun))) {
+                                                logger.warn("chat.agent: paused message not found at the model lane tail; reconverting the lane");
+                                                accumulatedMessages = await toModelMessages(accumulatedUIMessages, accumulatedUIMessages);
+                                                laneCompacted = false;
+                                                laneInjections = [];
+                                            }
+                                            for (const call of stoppedCalls)
+                                                channelStoppedToolCallIds.add(call.toolCallId);
+                                            locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
+                                        }
+                                        const refs = sessionChannelBinding?.connectorId === channelConn.id
+                                            ? sessionChannelBinding.controls
+                                            : undefined;
+                                        const cancelled = stoppedCalls.map((call) => refs?.[call.toolCallId] ? { ...call, ref: refs[call.toolCallId] } : call);
+                                        for (const call of stoppedCalls) {
+                                            channelRenderedToolCallIds.delete(call.toolCallId);
+                                        }
+                                        if (refs && sessionChannelBinding) {
+                                            const remaining = Object.fromEntries(Object.entries(refs).filter(([id]) => !stoppedCalls.some((call) => call.toolCallId === id)));
+                                            const { controls: _controls, ...rest } = sessionChannelBinding;
+                                            void _controls;
+                                            sessionChannelBinding =
+                                                Object.keys(remaining).length > 0 ? { ...rest, controls: remaining } : rest;
+                                        }
+                                        await writeSnapshotOutsideTurn("channel-stop", { turn, clientData });
+                                        if (channelConn.cancelInteraction) {
+                                            try {
+                                                await channelConn.cancelInteraction(cancelled, channelTurnCtx(wireChannelEvent, channelHandle));
+                                            }
+                                            catch (cancelError) {
+                                                logger.warn("chat.agent: channel cancelInteraction failed; continuing", {
+                                                    error: cancelError,
+                                                });
+                                            }
+                                        }
+                                        await channelLifecycle.report(channelConn, "idle", {
+                                            ...channelTurnCtx(wireChannelEvent, channelHandle),
+                                            firstTurn: false,
+                                        });
+                                    }
+                                }
+                                else if (resolutionMessage) {
+                                    effectiveIncomingMessage = resolutionMessage;
+                                    channelInteractionResolved = true;
+                                    const resolvedCallId = interaction?.toolCallId;
+                                    const controlRefs = sessionChannelBinding?.controls;
+                                    if (resolvedCallId && controlRefs?.[resolvedCallId] && sessionChannelBinding) {
+                                        const { [resolvedCallId]: _resolved, ...remaining } = controlRefs;
+                                        void _resolved;
+                                        const { controls: _controls, ...rest } = sessionChannelBinding;
+                                        void _controls;
+                                        sessionChannelBinding =
+                                            Object.keys(remaining).length > 0 ? { ...rest, controls: remaining } : rest;
+                                    }
+                                    if (interaction && channelConn.finalizeInteraction) {
+                                        try {
+                                            await channelConn.finalizeInteraction(wireChannelEvent.event, interaction);
+                                        }
+                                        catch (finalizeError) {
+                                            logger.warn("chat.agent: channel finalizeInteraction failed; continuing", {
+                                                error: finalizeError,
+                                            });
+                                        }
+                                    }
+                                }
+                                else if (rawInteraction) {
+                                    droppedStaleInteraction = true;
+                                    logger.debug("chat.agent: dropping stale channel interaction that matched no pending tool call", {
+                                        deliveryId: wireChannelEvent.deliveryId,
+                                    });
+                                }
+                                else if (channelInbound === undefined || isEmptyChannelInbound(channelInbound)) {
+                                    droppedEmptyMessage = true;
+                                    logger.debug("chat.agent: dropping a channel delivery with an empty message", {
+                                        deliveryId: wireChannelEvent.deliveryId,
+                                    });
+                                }
+                                else {
+                                    // A session that starts on a conversation with history: let the connector supply
+                                    // it, so the agent answers with the context a reader of the thread has.
+                                    if (channelConn.seed && accumulatedUIMessages.length === 0) {
+                                        try {
+                                            const seeded = channelSeedMessages(await channelConn.seed(wireChannelEvent.event, {
+                                                event: wireChannelEvent.event,
+                                                deliveryId: wireChannelEvent.deliveryId,
+                                            }), {
+                                                source: "channel",
+                                                connectorId: channelConn.id,
+                                                provider: channelConn.source,
+                                                deliveryId: wireChannelEvent.deliveryId,
+                                            });
+                                            if (seeded.length > 0) {
+                                                accumulatedUIMessages = seeded;
+                                                accumulatedMessages = await toModelMessages(seeded);
+                                                locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
+                                            }
+                                        }
+                                        catch (seedError) {
+                                            logger.warn("chat.agent: channel seed() failed; starting the session empty", {
+                                                error: seedError,
+                                            });
+                                        }
+                                    }
+                                    effectiveIncomingMessage = channelUserMessage(channelInbound, currentWirePayload.messageId ?? wireChannelEvent.deliveryId, {
+                                        source: "channel",
+                                        connectorId: channelConn.id,
+                                        provider: channelConn.source,
+                                        deliveryId: wireChannelEvent.deliveryId,
+                                        ...(wireChannelEvent.externalDeliveryId
+                                            ? { externalDeliveryId: wireChannelEvent.externalDeliveryId }
+                                            : {}),
+                                    });
+                                    if (channelConn.send && channelConn.ack) {
+                                        const recoveryPending = locals.get(chatChannelRecoveryPendingKey);
+                                        const recovered = recoveryPending?.value === true;
+                                        if (recovered)
+                                            recoveryPending.value = false;
+                                        const ackMessage = channelConn.ack(wireChannelEvent.event, { recovered });
+                                        if (ackMessage) {
+                                            try {
+                                                const ackResult = await channelConn.send(ackMessage, {
+                                                    event: wireChannelEvent.event,
+                                                    handle: channelHandle,
+                                                    deliveryId: wireChannelEvent.deliveryId,
+                                                    mode: channelConn.delivery,
+                                                    final: false,
+                                                    bound: false,
+                                                });
+                                                channelAckRef = ackResult?.ref;
+                                            }
+                                            catch (ackError) {
+                                                logger.warn("chat.agent: channel ack post failed; continuing", {
+                                                    error: ackError,
+                                                });
+                                            }
+                                        }
+                                    }
+                                    try {
+                                        channelWorkingReaction = await resolveReactionChoice(channelConn.reactions?.working, wireChannelEvent.event);
+                                        if (channelWorkingReaction) {
+                                            await applyChannelReaction(channelConn, wireChannelEvent, {
+                                                name: channelWorkingReaction,
+                                            });
+                                        }
+                                    }
+                                    catch (reactionError) {
+                                        logger.warn("chat.agent: channel working reaction failed", {
+                                            error: reactionError,
+                                        });
+                                    }
+                                }
+                            }
+                            else {
+                                droppedUnknownConnector = true;
+                                logger.warn("chat.agent: no channel connector matches this delivery; skipping turn", {
+                                    connectorId: wireChannelEvent.connectorId,
+                                    deliveryId: wireChannelEvent.deliveryId,
+                                });
+                            }
+                        }
+                        if (!wireChannelEvent &&
+                            sessionChannelBinding &&
+                            currentWirePayload.trigger !== "close" &&
+                            currentWirePayload.trigger !== "preload") {
+                            // No channel delivery started this turn, but the session is bound to a channel: answer
+                            // into it. Reactions need the triggering message, so a bound turn adds none; its reply,
+                            // any error and any approval controls go to the bound thread.
+                            const bound = channels?.find((c) => c.id === sessionChannelBinding.connectorId);
+                            if (bound?.send) {
+                                channelConn = bound;
+                                channelHandle = sessionChannelBinding.handle;
+                                boundTurn = true;
+                                currentTurnConnectorId = bound.id;
+                            }
+                        }
+                        const incomingMessages = effectiveIncomingMessage
+                            ? [effectiveIncomingMessage]
                             : [];
                         // 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 clientData = (parseClientData ? await parseClientData(wireMetadata) : wireMetadata);
-                        turnClientData = clientData;
                         const lastUserMessage = extractLastUserMessageText(cleanedIncomingMessages);
+                        channelTurnRan =
+                            !!channelConn &&
+                                !!(wireChannelEvent || boundTurn) &&
+                                currentWirePayload.trigger !== "action" &&
+                                !droppedIdleControl &&
+                                !droppedStaleInteraction &&
+                                !droppedEmptyMessage;
+                        const startChannelLifecycle = async () => {
+                            lastChannelTurnStartedAt = channelTurnStartedAt;
+                            if (!channelConn?.lifecycle)
+                                return;
+                            channelLifecycleStarted = true;
+                            if (sessionChannelBinding?.connectorId === channelConn.id) {
+                                sessionChannelBinding = { ...sessionChannelBinding, working: true };
+                            }
+                            await channelLifecycle.report(channelConn, "working", {
+                                ...channelTurnCtx(wireChannelEvent, channelHandle),
+                                firstTurn: accumulatedUIMessages.every((m) => m.metadata?.seeded === true),
+                                ...(lastUserMessage ? { prompt: lastUserMessage } : {}),
+                            });
+                        };
+                        if (channelTurnRan)
+                            await startChannelLifecycle();
                         // Actions are not turns. They use a different span name
                         // and don't carry a turn.number. Branched on at `isAction`.
                         const isAction = currentWirePayload.trigger === "action";
@@ -4982,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
@@ -4993,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);
                         }
@@ -5018,11 +6585,16 @@ function chatAgent(options) {
                                 turn,
                                 continuation,
                                 clientData,
+                                recordUserMessage,
                             });
                             // Resolve the per-turn `tools` set now that turn context
                             // (incl. parsed clientData) exists, so every toModelMessages
                             // call this turn can re-apply tool `toModelOutput`.
                             await resolveTurnTools();
+                            // The channel surface for this turn, handed to run() and reachable from a tool's
+                            // execute through chat.surface(), so a connector can ship tools the model drives.
+                            const channelSurface = buildChannelRunSurface(channelConn, wireChannelEvent, channelHandle);
+                            locals.set(chatChannelSurfaceKey, channelSurface);
                             // Per-turn stop controller (reset each turn)
                             const stopController = new AbortController();
                             currentStopController = stopController;
@@ -5044,12 +6616,19 @@ function chatAgent(options) {
                                 ? chatInputRouter().observe(CHAT_ROUTE_MESSAGES, async (record) => {
                                     const msg = record.data
                                         .payload;
+                                    const wireChannel = msg
+                                        .channelEvent;
+                                    const steeredChannel = wireChannel != null
+                                        ? channelSteeringMessage(channels, wireChannel, msg.messageId)
+                                        : undefined;
+                                    if (wireChannel != null && !steeredChannel)
+                                        return;
                                     // Slim wire: at most one delta message per record. The
                                     // pendingMessages handler reads `msg.message` directly
                                     // instead of slicing an array — a wire record arrives
                                     // with the new user message in `.message`, or no message
                                     // at all (regenerate / preload / close / handover-prepare).
-                                    const lastUIMessage = msg.message;
+                                    const lastUIMessage = (steeredChannel?.message ?? msg.message);
                                     if (lastUIMessage) {
                                         if (pmConfig.onReceived) {
                                             try {
@@ -5070,7 +6649,10 @@ function chatAgent(options) {
                                                 queue.some((e) => e.uiMessage.id === lastUIMessage.id)) {
                                                 return;
                                             }
-                                            const modelMsgs = await toModelMessages([lastUIMessage]);
+                                            const converted = await toModelMessages([lastUIMessage]);
+                                            const modelMsgs = steeredChannel && channelDownloader
+                                                ? await resolveChannelFiles(converted, channelDownloader)
+                                                : converted;
                                             queue.push({
                                                 uiMessage: lastUIMessage,
                                                 modelMessages: modelMsgs,
@@ -5085,6 +6667,52 @@ function chatAgent(options) {
                                 })
                                 : undefined;
                             turnMsgSub = msgSub;
+                            /**
+                             * Channel deliveries while this turn runs. A delivery the connector maps to `stop`
+                             * aborts this turn through the same controller the stop input uses, and is taken
+                             * off the route so it does not also run as a turn. Any other message is
+                             * acknowledged through the connector's `received` as soon as it arrives, and left
+                             * queued for steering or the next turn.
+                             */
+                            const controlSub = channels?.some((c) => c.onControl || c.received)
+                                ? chatInputRouter().observe(CHAT_ROUTE_MESSAGES, (record) => {
+                                    const msg = record.data
+                                        .payload;
+                                    const ce = msg.channelEvent;
+                                    if (!ce)
+                                        return;
+                                    const conn = channels?.find((c) => c.id === ce.connectorId);
+                                    if (!conn)
+                                        return;
+                                    let control = null;
+                                    try {
+                                        control = conn.onControl?.(ce.event) ?? null;
+                                    }
+                                    catch (controlError) {
+                                        logger.warn("chat.agent: channel onControl threw; treating as a message", {
+                                            error: controlError,
+                                        });
+                                    }
+                                    if (!control) {
+                                        acknowledgeChannelMessage(conn, ce, sessionChannelBinding?.connectorId === conn.id
+                                            ? sessionChannelBinding.handle
+                                            : undefined);
+                                        return;
+                                    }
+                                    if (control.kind !== "stop")
+                                        return;
+                                    const earlierTurnStop = control.at !== undefined && control.at < channelTurnStartedAt;
+                                    if (!earlierTurnStop && !stopController.signal.aborted) {
+                                        stopController.abort(new DOMException(control.message || "stopped", "AbortError"));
+                                    }
+                                    // Observers are offered a record before it is queued, so the take has to
+                                    // wait a tick or it finds nothing and the stop runs again as a turn.
+                                    void Promise.resolve().then(() => {
+                                        chatInputRouter().take(CHAT_ROUTE_MESSAGES, record.seqNum);
+                                    });
+                                })
+                                : undefined;
+                            turnControlSub = controlSub;
                             // Track new messages for this turn (user input + assistant response).
                             const turnNewModelMessages = [];
                             const turnNewUIMessages = [];
@@ -5114,7 +6742,8 @@ function chatAgent(options) {
                             let actionChangedHistory = false;
                             if (isAction) {
                                 // Parse and validate the action payload
-                                const parsedAction = parseAction
+                                const isWebhookAction = currentWirePayload.actionSource === "webhook";
+                                const parsedAction = parseAction && !isWebhookAction
                                     ? await parseAction(currentWirePayload.action)
                                     : currentWirePayload.action;
                                 // Hydrate messages from backend if configured
@@ -5155,6 +6784,7 @@ function chatAgent(options) {
                                             clientData,
                                             uiMessages: accumulatedUIMessages,
                                             messages: accumulatedMessages,
+                                            ...(actionChannel ? { channel: actionChannel } : {}),
                                         });
                                     }, {
                                         attributes: {
@@ -5189,7 +6819,11 @@ function chatAgent(options) {
                             // snapshot + `session.out` replay (or `hydrateMessages`,
                             // which also fires per-turn below). Per-turn handling is
                             // therefore a delta merge, not a full-history reset.
-                            if (currentWirePayload.trigger !== "action") {
+                            if (currentWirePayload.trigger !== "action" &&
+                                !droppedStaleInteraction &&
+                                !droppedEmptyMessage &&
+                                !droppedUnknownConnector &&
+                                !droppedIdleControl) {
                                 let cleanedUIMessages = cleanedIncomingMessages;
                                 // Turn-0 head-start with hydrateMessages: the boot seeding from
                                 // `payload.headStartMessages` is non-hydrate-only, so ship the
@@ -5441,17 +7075,41 @@ function chatAgent(options) {
                             // calling the model would prefill its own last reply. Keyed on
                             // the model tail, so a `tool`-terminated chain (a merged tool
                             // approval) still runs.
-                            const isNoOpTurn = !isAction &&
-                                !splicedHandoverPartial &&
-                                currentWirePayload.trigger === "submit-message" &&
-                                turnNewUIMessages.length === 0 &&
-                                accumulatedMessages[accumulatedMessages.length - 1]?.role === "assistant";
+                            // A channel delivery the run decided not to turn into a turn: a stale
+                            // interaction callback (no pending tool call matched) or an event for
+                            // a connector this agent does not list. Nothing to answer either way.
+                            const isDroppedChannelDelivery = droppedStaleInteraction ||
+                                droppedEmptyMessage ||
+                                droppedUnknownConnector ||
+                                droppedIdleControl;
+                            // A resolved interaction is never a no-op: the assistant may already have text after
+                            // the pending call, so the lane ends on an assistant message, but the model has not
+                            // seen the decision yet.
+                            const isNoOpTurn = isDroppedChannelDelivery ||
+                                (!isAction &&
+                                    !splicedHandoverPartial &&
+                                    !channelInteractionResolved &&
+                                    currentWirePayload.trigger === "submit-message" &&
+                                    turnNewUIMessages.length === 0 &&
+                                    accumulatedMessages[accumulatedMessages.length - 1]?.role === "assistant");
                             if (isNoOpTurn) {
                                 msgSub?.off();
-                                logger.warn("chat.agent: turn added no new user message; skipping the model", {
-                                    chatId: currentWirePayload.chatId,
-                                    messageId: currentWirePayload.messageId,
-                                });
+                                turnControlSub?.off();
+                                if (channelTurnRan)
+                                    lastChannelTurnEndedAt = Date.now();
+                                clearChannelWorking();
+                                if (channelLifecycleStarted) {
+                                    await channelLifecycle.report(channelConn, "idle", {
+                                        ...channelTurnCtx(wireChannelEvent, channelHandle),
+                                        firstTurn: false,
+                                    });
+                                }
+                                if (!isDroppedChannelDelivery) {
+                                    logger.warn("chat.agent: turn added no new user message; skipping the model", {
+                                        chatId: currentWirePayload.chatId,
+                                        messageId: currentWirePayload.messageId,
+                                    });
+                                }
                                 settleRecoveredTurn(currentWirePayload);
                                 await writeTurnCompleteChunk(currentWirePayload.chatId);
                                 // Not a turn — don't consume an iteration.
@@ -5467,6 +7125,24 @@ function chatAgent(options) {
                             // sees the same `turn` value — actions don't count.
                             if (isAction) {
                                 if (isActionTurn(actionResult)) {
+                                    if (actionResult.message !== undefined) {
+                                        const asked = (typeof actionResult.message === "string"
+                                            ? {
+                                                id: generateMessageId(),
+                                                role: "user",
+                                                parts: [{ type: "text", text: actionResult.message }],
+                                            }
+                                            : actionResult.message.id
+                                                ? actionResult.message
+                                                : { ...actionResult.message, id: generateMessageId() });
+                                        accumulatedUIMessages = [...accumulatedUIMessages, asked];
+                                        accumulatedMessages = [
+                                            ...accumulatedMessages,
+                                            ...(await toModelMessages([asked])),
+                                        ];
+                                        locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
+                                        actionChangedHistory = true;
+                                    }
                                     // Persist the edit before the turn starts, so a turn that is
                                     // cancelled or runs out of memory continues from the edited
                                     // history rather than from the snapshot the edit replaced.
@@ -5475,6 +7151,11 @@ function chatAgent(options) {
                                         await writeSnapshotOutsideTurn("action", { turn, clientData });
                                     }
                                     actionTurn = true;
+                                    turnIsActionTurn = true;
+                                    if (boundTurn && channelConn) {
+                                        channelTurnRan = true;
+                                        await startChannelLifecycle();
+                                    }
                                 }
                                 else if (actionResult !== undefined) {
                                     throw new Error("chat.agent: onAction returned a value. An action is a state edit; to answer " +
@@ -5483,6 +7164,7 @@ function chatAgent(options) {
                                 }
                                 else {
                                     msgSub?.off();
+                                    turnControlSub?.off();
                                     if (actionChangedHistory) {
                                         await writeSnapshotOutsideTurn("action", { turn, clientData });
                                     }
@@ -5684,12 +7366,87 @@ function chatAgent(options) {
                                     }
                                     else {
                                         const preparedMessages = await applyPrepareMessages(accumulatedMessages, "run");
+                                        const runMessages = channelDownloader
+                                            ? await resolveChannelFiles(preparedMessages, channelDownloader)
+                                            : preparedMessages;
+                                        // Channel observers for this turn are built before run(). The progress
+                                        // observer and the native reply stream are shared with a manual chat.pipe()
+                                        // inside run() through the turn tap and stay open across several pipes; the
+                                        // ack stream editor only rides the automatic pipe, because a manual pipe
+                                        // captures no response and posts no final reply that would supersede a
+                                        // partial edit. The finally of this turn stops all of them and clears the tap;
+                                        // the turn boundary ends the native stream.
+                                        if (channelConn) {
+                                            const observers = [];
+                                            const tapObservers = [];
+                                            if (channelConn.delivery === "stream" &&
+                                                channelConn.stream &&
+                                                (wireChannelEvent || channelHandle)) {
+                                                const streamConnectorId = channelConn.id;
+                                                const opened = (ref) => {
+                                                    if (sessionChannelBinding?.connectorId !== streamConnectorId)
+                                                        return;
+                                                    sessionChannelBinding = { ...sessionChannelBinding, stream: ref };
+                                                    if (hydrateMessages)
+                                                        return;
+                                                    void saveTranscript({
+                                                        reason: "turn-start",
+                                                        messages: accumulatedUIMessages,
+                                                        turn,
+                                                        trigger: storageTrigger(currentWirePayload.trigger),
+                                                        clientData,
+                                                        lastOutEventId: lastSnapshotOutEventId,
+                                                        skipIfUnchanged: true,
+                                                        carryInCursor: true,
+                                                    }).catch((error) => {
+                                                        logger.warn("chat.agent: saving the open reply stream failed", {
+                                                            error: error instanceof Error ? error.message : String(error),
+                                                        });
+                                                    });
+                                                };
+                                                try {
+                                                    channelReplyStream =
+                                                        channelConn.stream({
+                                                            ...channelTurnCtx(wireChannelEvent, channelHandle),
+                                                            opened,
+                                                        }) ?? undefined;
+                                                }
+                                                catch (streamError) {
+                                                    logger.warn("chat.agent: channel stream() threw; posting the reply", {
+                                                        error: streamError,
+                                                    });
+                                                }
+                                            }
+                                            if (channelReplyStream) {
+                                                const replyObserver = makeChannelReplyStreamObserver(channelReplyStream);
+                                                observers.push(replyObserver);
+                                                tapObservers.push(replyObserver);
+                                            }
+                                            else if (wireChannelEvent &&
+                                                channelConn.send &&
+                                                channelConn.delivery === "stream" &&
+                                                channelAckRef) {
+                                                observers.push(makeChannelStreamEditor(channelConn, wireChannelEvent, channelAckRef, channelHandle));
+                                            }
+                                            if (channelConn.progress && (wireChannelEvent || channelHandle)) {
+                                                const progressObserver = makeChannelProgressObserver(channelConn, wireChannelEvent, channelHandle);
+                                                observers.push(progressObserver);
+                                                tapObservers.push(progressObserver);
+                                            }
+                                            if (tapObservers.length > 0) {
+                                                const tapObserver = composeChannelObservers(tapObservers);
+                                                locals.set(chatTurnChannelTapKey, (stream) => stream.pipeThrough(makeChannelStreamTap(tapObserver, { stopOnEnd: false })));
+                                            }
+                                            if (observers.length > 0) {
+                                                channelStreamEditor = composeChannelObservers(observers);
+                                            }
+                                        }
                                         runResult = await userRun({
                                             ...restWire,
                                             // A turn requested by chat.turn() is not the action itself:
                                             // a run() that short-circuits on "action" must still answer.
                                             ...(actionTurn ? { trigger: "action-turn" } : {}),
-                                            messages: preparedMessages,
+                                            messages: runMessages,
                                             clientData,
                                             continuation,
                                             previousRunId,
@@ -5702,6 +7459,7 @@ function chatAgent(options) {
                                             cancelSignal,
                                             stopSignal,
                                             streamText: createBoundStreamText(promptRegistry, agentSystem, agentCacheControl, agentSystemProviderOptions),
+                                            channel: channelSurface,
                                         });
                                     }
                                     // Auto-pipe if the run function returned a StreamTextResult or similar,
@@ -5728,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;
@@ -5735,7 +7499,13 @@ function chatAgent(options) {
                                                 resolveOnFinish();
                                             },
                                         });
-                                        await pipeChat(tapUIMessageChunks(uiStream, turnBufferedChunks), {
+                                        // The automatic pipe feeds every observer (progress and the ack stream editor)
+                                        // itself; the manual tap is cleared so pipeChat does not feed progress twice.
+                                        locals.set(chatTurnChannelTapKey, undefined);
+                                        const streamForPipe = channelStreamEditor && uiStream instanceof ReadableStream
+                                            ? uiStream.pipeThrough(makeChannelStreamTap(channelStreamEditor))
+                                            : uiStream;
+                                        await pipeChat(tapUIMessageChunks(streamForPipe, turnBufferedChunks), {
                                             signal: combinedSignal,
                                             spanName: "stream response",
                                         }, { originalMessages: isActionTurn ? undefined : accumulatedUIMessages });
@@ -5758,6 +7528,9 @@ function chatAgent(options) {
                                 }
                                 finally {
                                     msgSub?.off();
+                                    turnControlSub?.off();
+                                    locals.set(chatTurnChannelTapKey, undefined);
+                                    await channelStreamEditor?.stop();
                                 }
                                 // Wait for onFinish to fire — on abort this may resolve slightly
                                 // after pipeChat, since the stream's cancel() handler is async.
@@ -6001,6 +7774,16 @@ function chatAgent(options) {
                                 if (capturedResponseMessage) {
                                     responseCommitted = true;
                                     capturedPartialResponse = capturedResponseMessage;
+                                    const errorChunk = turnBufferedChunks.find((chunk) => chunk.type === "error");
+                                    channelStreamErrorText = errorChunk?.errorText;
+                                    channelTurnText = turnBufferedChunks
+                                        .map((chunk) => {
+                                        const c = chunk;
+                                        return c.type === "text-delta" && typeof c.delta === "string"
+                                            ? c.delta
+                                            : "";
+                                    })
+                                        .join("");
                                     turnBufferedChunks.length = 0;
                                 }
                                 if (runSignal.aborted)
@@ -6220,8 +8003,206 @@ function chatAgent(options) {
                                     }
                                 }
                                 settleRecoveredTurn(currentWirePayload);
+                                openChannelEgressLatch(currentWirePayload.chatId);
                                 // Write turn-complete control chunk — closes the frontend stream.
                                 const turnCompleteResult = await writeTurnCompleteChunk(currentWirePayload.chatId, turnAccessToken);
+                                // Tool calls that have not had controls posted yet; a resume with the rest still
+                                // pending must not repost them or hide the answer text behind them.
+                                const pendingToolCalls = (wireChannelEvent || boundTurn) &&
+                                    channelConn?.send &&
+                                    turnCompleteEvent.responseMessage
+                                    ? pendingToolCallsInMessage(turnCompleteEvent.responseMessage).filter((call) => !channelRenderedToolCallIds.has(call.toolCallId))
+                                    : [];
+                                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;
+                                    channelReplyStream = undefined;
+                                    try {
+                                        const ended = await replyStream.end({
+                                            stopped: turnCompleteEvent.stopped,
+                                            pending: renderControls,
+                                            ...(channelStreamErrorText
+                                                ? { errorText: channelErrorLine ?? CHANNEL_TURN_ERROR_MESSAGE }
+                                                : {}),
+                                        });
+                                        channelReplyDelivered = ended.delivered;
+                                    }
+                                    catch (streamError) {
+                                        logger.warn("chat.agent: channel reply stream end failed", {
+                                            error: streamError,
+                                        });
+                                    }
+                                    finally {
+                                        clearOpenReplyStream();
+                                    }
+                                }
+                                // Channel egress: map the turn's reply via outbound() and send it, editing the ack
+                                // placeholder posted at turn start (previousRef). A failed send is retried; one that
+                                // never lands is logged and the turn gets the error reaction. A manual-pipe turn has
+                                // no responseMessage, so it opts out.
+                                const finalChannelConn = channelConn;
+                                if ((wireChannelEvent || boundTurn) &&
+                                    finalChannelConn?.send &&
+                                    turnCompleteEvent.responseMessage) {
+                                    if (renderControls) {
+                                        for (const call of pendingToolCalls) {
+                                            channelRenderedToolCallIds.add(call.toolCallId);
+                                        }
+                                    }
+                                    const replyText = channelTurnText && channelTurnText.trim().length > 0
+                                        ? 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 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.
+                                        // 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,
+                                        stopped: turnCompleteEvent.stopped,
+                                        ...(renderControls ? { pending: true } : {}),
+                                        ...(channelStreamErrorText
+                                            ? { error: new Error(channelStreamErrorText) }
+                                            : {}),
+                                    };
+                                    let outboundMessage = null;
+                                    if (!channelReplyDelivered) {
+                                        try {
+                                            outboundMessage = (finalChannelConn.outbound ?? defaultChannelOutbound)(finalReply);
+                                        }
+                                        catch (outboundError) {
+                                            logger.warn("chat.agent: channel outbound failed; posting the plain reply", {
+                                                error: outboundError,
+                                            });
+                                            outboundMessage = defaultChannelOutbound(finalReply) ?? {
+                                                text: "An unexpected error occurred",
+                                            };
+                                        }
+                                    }
+                                    const sendFinal = async (message) => {
+                                        for (let attempt = 1;; attempt++) {
+                                            try {
+                                                const sent = await finalChannelConn.send(message, {
+                                                    event: wireChannelEvent?.event,
+                                                    handle: channelHandle,
+                                                    deliveryId: wireChannelEvent?.deliveryId,
+                                                    previousRef: channelAckRef,
+                                                    mode: finalChannelConn.delivery,
+                                                    final: true,
+                                                    bound: boundTurn,
+                                                });
+                                                channelFinalAnswerPosted = true;
+                                                return sent ?? {};
+                                            }
+                                            catch (egressError) {
+                                                if (attempt >= CHANNEL_FINAL_SEND_ATTEMPTS || !channelAckRef) {
+                                                    channelFinalSendFailed = true;
+                                                    logger.error("chat.agent: channel egress send failed", {
+                                                        error: egressError,
+                                                        attempts: attempt,
+                                                    });
+                                                    return undefined;
+                                                }
+                                                logger.warn("chat.agent: channel egress send failed; retrying", {
+                                                    error: egressError,
+                                                    attempt,
+                                                });
+                                                await new Promise((resolve) => setTimeout(resolve, 500 * attempt));
+                                            }
+                                        }
+                                    };
+                                    // A turn that pauses on a human decision often explains itself first (a summary,
+                                    // the steps so far) and then calls the tool. That text is the answer so far: post it
+                                    // as the placeholder edit, and post the controls as their own message after it.
+                                    if (renderControls && outboundMessage && (await sendFinal(outboundMessage))) {
+                                        channelAckRef = undefined;
+                                    }
+                                    const channelMessage = renderControls
+                                        ? finalChannelConn.renderInteraction(pendingToolCalls, wireChannelEvent
+                                            ? {
+                                                event: wireChannelEvent.event,
+                                                deliveryId: wireChannelEvent.deliveryId,
+                                            }
+                                            : {})
+                                        : outboundMessage;
+                                    if (channelMessage) {
+                                        const controlsRef = (await sendFinal(channelMessage))?.ref;
+                                        if (renderControls &&
+                                            controlsRef &&
+                                            sessionChannelBinding?.connectorId === finalChannelConn.id) {
+                                            sessionChannelBinding = {
+                                                ...sessionChannelBinding,
+                                                controls: {
+                                                    ...sessionChannelBinding.controls,
+                                                    ...Object.fromEntries(pendingToolCalls.map((call) => [call.toolCallId, controlsRef])),
+                                                },
+                                            };
+                                        }
+                                    }
+                                }
+                                if (channelTurnRan)
+                                    lastChannelTurnEndedAt = Date.now();
+                                clearChannelWorking();
+                                if (channelLifecycleStarted) {
+                                    const stillPending = turnCompleteEvent.responseMessage
+                                        ? pendingToolCallsInMessage(turnCompleteEvent.responseMessage).length > 0
+                                        : false;
+                                    await channelLifecycle.report(channelConn, locals.get(chatCloseRequestedKey)
+                                        ? "closed"
+                                        : stillPending
+                                            ? "waiting"
+                                            : "idle", { ...channelTurnCtx(wireChannelEvent, channelHandle), firstTurn: false });
+                                }
+                                // Lifecycle reaction: turn done. Remove "working", mark "done".
+                                if (wireChannelEvent && channelConn?.react) {
+                                    try {
+                                        if (channelWorkingReaction) {
+                                            await applyChannelReaction(channelConn, wireChannelEvent, {
+                                                name: channelWorkingReaction,
+                                                remove: true,
+                                            });
+                                        }
+                                        const outcomeReaction = await resolveReactionChoice(channelStreamErrorText || channelFinalSendFailed
+                                            ? channelConn.reactions?.error
+                                            : channelConn.reactions?.done, wireChannelEvent.event);
+                                        if (outcomeReaction) {
+                                            await applyChannelReaction(channelConn, wireChannelEvent, {
+                                                name: outcomeReaction,
+                                            });
+                                        }
+                                    }
+                                    catch (reactionError) {
+                                        logger.warn("chat.agent: channel done reaction failed", {
+                                            error: reactionError,
+                                        });
+                                    }
+                                }
+                                settleChannelEgressLatch(currentWirePayload.chatId);
                                 // Fire onTurnComplete — stream is closed, use for persistence.
                                 if (onTurnComplete) {
                                     await tracer.startActiveSpan("onTurnComplete()", async () => {
@@ -6339,6 +8320,7 @@ function chatAgent(options) {
                             // chat.endRun() — same exit, no upgrade semantics.
                             if (locals.get(chatCloseRequestedKey)) {
                                 await performChatClose();
+                                await reportChannelClosed();
                                 return "exit";
                             }
                             if (locals.get(chatUpgradeRequestedKey) || locals.get(chatEndRunRequestedKey)) {
@@ -6410,6 +8392,7 @@ function chatAgent(options) {
                             currentWirePayload = next.output;
                             // Close signal — exit the loop gracefully
                             if (currentWirePayload.trigger === "close") {
+                                await reportChannelClosed();
                                 return "exit";
                             }
                             return "continue";
@@ -6427,12 +8410,16 @@ function chatAgent(options) {
                         // Detach the turn's message handler first — left attached it would
                         // eat the very message the wait below is waiting for.
                         turnMsgSub?.off();
+                        turnControlSub?.off();
                         if (turnError instanceof Error &&
                             turnError.name === "AbortError" &&
                             runSignal.aborted) {
+                            settleChannelEgressLatch(currentWirePayload.chatId);
+                            channelLifecycle.dispose();
                             // Full run cancellation — exit immediately
                             throw turnError;
                         }
+                        settleChannelEgressLatch(currentWirePayload.chatId);
                         // OOM errors must escape the turn loop so the task runtime can
                         // honor `retry.outOfMemory.machine` (set on chat.agent via
                         // `oomMachine`). Catching them here would keep the dead worker
@@ -6443,6 +8430,107 @@ function chatAgent(options) {
                         if (turnError instanceof OutOfMemoryError) {
                             throw turnError;
                         }
+                        if (channelWireEvent && channelConn?.react) {
+                            try {
+                                if (channelWorkingReaction) {
+                                    await applyChannelReaction(channelConn, channelWireEvent, {
+                                        name: channelWorkingReaction,
+                                        remove: true,
+                                    });
+                                }
+                                const errorReaction = await resolveReactionChoice(channelConn.reactions?.error, channelWireEvent.event);
+                                if (errorReaction) {
+                                    await applyChannelReaction(channelConn, channelWireEvent, {
+                                        name: errorReaction,
+                                    });
+                                }
+                            }
+                            catch (reactionError) {
+                                logger.warn("chat.agent: channel error reaction failed", { error: reactionError });
+                            }
+                        }
+                        // 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;
+                            channelReplyStream = undefined;
+                            try {
+                                const ended = await replyStream.end({
+                                    stopped: false,
+                                    pending: false,
+                                    errorText: channelErrorText,
+                                });
+                                errorStreamDelivered = ended.delivered;
+                            }
+                            catch (streamError) {
+                                logger.warn("chat.agent: channel reply stream end failed", {
+                                    error: streamError,
+                                });
+                            }
+                            finally {
+                                clearOpenReplyStream();
+                            }
+                        }
+                        if ((channelWireEvent || boundTurn) && channelConn?.send) {
+                            const errorPreviousRef = channelFinalAnswerPosted ? undefined : channelAckRef;
+                            const channelErrorMessageId = errorPreviousRef ?? channelWireEvent?.deliveryId ?? `channel-error-${turn}`;
+                            let errorMessage = null;
+                            try {
+                                errorMessage = (channelConn.outbound ?? defaultChannelOutbound)({
+                                    text: channelErrorText,
+                                    message: {
+                                        id: channelErrorMessageId,
+                                        role: "assistant",
+                                        parts: [{ type: "text", text: channelErrorText }],
+                                    },
+                                    final: true,
+                                    stopped: false,
+                                    error: turnError,
+                                });
+                            }
+                            catch (outboundError) {
+                                logger.warn("chat.agent: channel error outbound failed; posting the plain error", {
+                                    error: outboundError,
+                                });
+                                errorMessage = { text: channelErrorText };
+                            }
+                            if (errorMessage && !errorStreamDelivered) {
+                                try {
+                                    await channelConn.send(errorMessage, {
+                                        event: channelWireEvent?.event,
+                                        handle: channelHandle,
+                                        deliveryId: channelWireEvent?.deliveryId,
+                                        previousRef: errorPreviousRef,
+                                        mode: channelConn.delivery,
+                                        final: true,
+                                        bound: boundTurn,
+                                    });
+                                }
+                                catch (egressError) {
+                                    logger.warn("chat.agent: channel error egress send failed", {
+                                        error: egressError,
+                                    });
+                                }
+                            }
+                        }
+                        if (channelTurnRan)
+                            lastChannelTurnEndedAt = Date.now();
+                        clearChannelWorking();
+                        if (channelLifecycleStarted) {
+                            await channelLifecycle.report(channelConn, locals.get(chatCloseRequestedKey) ? "closed" : "idle", {
+                                ...channelTurnCtx(channelWireEvent, channelHandle),
+                                firstTurn: false,
+                            });
+                        }
                         let errorTurnCompleteResult;
                         try {
                             await withChatWriter(async (writer) => {
@@ -6699,6 +8787,7 @@ function chatAgent(options) {
                             .get(chatManagedResponseKey)
                             ?.close()
                             .catch(() => { });
+                        turnControlSub?.off();
                     }
                 }
             }
@@ -6722,6 +8811,45 @@ function chatAgent(options) {
             schema: clientDataSchema,
         });
     }
+    // Claim each listed chat.event descriptor: subscribe THIS agent's session to the event's endpoint.
+    // The subscriber id is scoped by agent, so the same descriptor on two agents is two subscribers.
+    if (events) {
+        for (const wh of events) {
+            resourceCatalog.markSessionWebhookClaimed(wh.id);
+            resourceCatalog.registerWebhookSubscriber({
+                endpointId: wh.endpointId,
+                target: {
+                    type: "session",
+                    id: `${options.id}:${wh.id}`,
+                    taskIdentifier: options.id,
+                    keyTemplate: wh.key,
+                    actionType: wh.type,
+                    deliverAs: "action",
+                    ...(wh.filter ? { filter: wh.filter } : {}),
+                },
+            });
+        }
+    }
+    // Claim each listed channel connector: the same kind of subscriber, but deliverAs "message" so a
+    // verified event becomes a turn (the run maps it via the connector's inbound(), resolved by connectorId).
+    if (channels) {
+        for (const ch of channels) {
+            resourceCatalog.markSessionWebhookClaimed(ch.id);
+            resourceCatalog.registerWebhookSubscriber({
+                endpointId: ch.endpointId,
+                target: {
+                    type: "session",
+                    id: `${options.id}:${ch.id}`,
+                    taskIdentifier: options.id,
+                    keyTemplate: ch.key,
+                    connectorId: ch.id,
+                    deliverAs: "message",
+                    ...(ch.filter ? { filter: ch.filter } : {}),
+                    ...(ch.startOn ? { startOn: ch.startOn } : {}),
+                },
+            });
+        }
+    }
     return task;
 }
 function composeHooks(builderHook, taskHook) {
@@ -7017,6 +9145,22 @@ function resolveUIMessageStreamOptions() {
 // ---------------------------------------------------------------------------
 // Stop detection
 // ---------------------------------------------------------------------------
+/**
+ * The channel surface of the current turn, from anywhere inside a `chat.agent` run, including a
+ * tool's `execute`. Undefined on a browser turn or when the connector defines no reactions and no
+ * `surface()`. Pass the connector's surface type to get its helpers typed:
+ *
+ * @example
+ * ```ts
+ * execute: async ({ steps }) => {
+ *   const linear = chat.surface<LinearRunSurface>();
+ *   if (linear) await linear.plan(steps);
+ * }
+ * ```
+ */
+function getChannelSurface() {
+    return locals.get(chatChannelSurfaceKey);
+}
 /**
  * Check whether the user stopped generation during the current turn.
  *
@@ -9014,6 +11158,10 @@ function createChatLoadTranscriptAction(storage, options) {
 export const chat = {
     /** Create a chat agent. See {@link chatAgent}. */
     agent: chatAgent,
+    /** Declare an inbound webhook event an agent claims via `chat.agent({ events })`. See {@link chatEvent}. */
+    event: chatEvent,
+    /** Chat frontend connectors (Slack, etc.) an agent claims via `chat.agent({ channels })`. */
+    channels: chatChannels,
     /** Create a custom agent with manual lifecycle control. See {@link chatCustomAgent}. */
     customAgent: chatCustomAgent,
     /** Create a chat task with a fixed {@link UIMessage} subtype and optional default stream options. See {@link withUIMessage}. */
@@ -9032,6 +11180,8 @@ export const chat = {
     local: chatLocal,
     /** Create a public access token for a chat task. See {@link createChatAccessToken}. */
     createAccessToken: createChatAccessToken,
+    /** Mint a read-only token to WATCH a session by externalId (cross-surface). See {@link createChatWatchToken}. */
+    createWatchToken: createChatWatchToken,
     /** Override the turn timeout at runtime (duration string). See {@link setTurnTimeout}. */
     setTurnTimeout,
     /** Override the turn timeout at runtime (seconds). See {@link setTurnTimeoutInSeconds}. */
@@ -9042,6 +11192,8 @@ export const chat = {
     setUIMessageStreamOptions,
     /** Check if the current turn was stopped by the user. See {@link isStopped}. */
     isStopped,
+    /** The current turn's channel surface (reactions plus connector helpers), also from inside a tool. See {@link getChannelSurface}. */
+    surface: getChannelSurface,
     /** Request that the run exits after the current turn so the next message starts on the latest version. See {@link requestUpgrade}. */
     requestUpgrade,
     /** Hand off a custom agent Session to a fresh run. See {@link endAndContinue}. */