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

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

@@ -1,6 +1,7 @@
-import { type AnyTask, type Task, type ApiClientConfiguration, type inferSchemaIn, type inferSchemaOut, type MachinePresetName, type RealtimeDefinedInputStream, type RealtimeDefinedStream, type TaskIdentifier, type TaskOptions, type TaskRunContext, type TaskSchema, type TaskWithSchema, type AnySessionChannel, type SessionChannelName } from "@trigger.dev/core/v3";
+import { type AnyTask, type Task, type ApiClientConfiguration, type inferSchemaIn, type inferSchemaOut, type MachinePresetName, type RealtimeDefinedInputStream, type RealtimeDefinedStream, type TaskIdentifier, type TaskOptions, type TaskRunContext, type TaskSchema, type TaskWithSchema, type AnySessionChannel, type SessionChannelName, type AnyChatEvent, type ChatEventActions, type ValidatedWebhookKey, type ValidateWebhookFilter, type NarrowWebhookEvent, type AnyWebhookEndpoint, type InferWebhookEndpointEvent } from "@trigger.dev/core/v3";
 import type { streamText as aiStreamTextSignature, FinishReason, LanguageModelUsage, ModelMessage, SystemModelMessage, ProviderMetadata, Tool, ToolSet, UIMessage, UIMessageChunk, UIMessageStreamOptions } from "ai";
-import { type TranscriptLoadResult, type TranscriptStorage } from "./transcriptStorage.js";
+import { chatEvent } from "./webhooks.js";
+import { type TranscriptLoadResult, type TranscriptChannelBinding, type TranscriptStorage } from "./transcriptStorage.js";
 import { type ChatInputChunk, type ChatTaskWirePayload, type InferChatClientData, type InferChatUIMessage, type InferChatUIMessageFromTools, PENDING_MESSAGE_INJECTED_TYPE, upsertIncomingMessage } from "./ai-shared.js";
 import { locals } from "./locals.js";
 import type { ResolvedPrompt } from "./prompt.js";
@@ -149,6 +150,31 @@ export declare const ai: {
  * ```
  */
 declare function createChatAccessToken<TTask extends AnyTask>(taskId: TaskIdentifier<TTask>): Promise<string>;
+/**
+ * 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);
+ * ```
+ */
+declare function createChatWatchToken(externalId: string, options?: {
+    tokenTTL?: string;
+}): Promise<string>;
 /**
  * Register work that must land before anything from this turn reaches the
  * frontend.
@@ -308,6 +334,12 @@ export type ChatTaskRunPayload<TClientData = unknown, TTools extends ToolSet = T
      * `tools` option on `chat.agent`). Empty object when no `tools` were declared.
      */
     tools: TTools;
+    /**
+     * Present for a channel turn whose connector supports reactions or defines a `surface()`. Lets the
+     * agent react to the triggering message (e.g. `channel.react("white_check_mark")`) and use the
+     * connector's helpers (cast to the connector's exported surface type).
+     */
+    channel?: ChannelRunSurface;
 };
 /**
  * One message record delivered through {@link chat.messages}.
@@ -1042,6 +1074,8 @@ declare const actionTurnBrand: unique symbol;
  */
 export type ActionTurn = {
     readonly [actionTurnBrand]: true;
+    /** A user message the turn answers, appended to the history after the action's edit. */
+    readonly message?: string | UIMessage;
 };
 /**
  * Turn the current action into a turn.
@@ -1054,6 +1088,9 @@ export type 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 }) => {
@@ -1061,11 +1098,12 @@ export type 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
  * },
  * ```
  */
-declare function chatTurn(): ActionTurn;
+declare function chatTurn(message?: string | UIMessage): ActionTurn;
 /**
  * Pipes a chat stream to the realtime stream, making it available to the
  * `TriggerChatTransport` on the frontend.
@@ -1408,6 +1446,18 @@ export type ActionEvent<TAction = unknown, TClientData = unknown, TUIM extends U
     uiMessages: TUIM[];
     /** The accumulated model messages (after hydration, if set). */
     messages: ModelMessage[];
+    /**
+     * The click that sent a channel action (a `slackButton()` in Slack): the verified provider event,
+     * with who clicked and the message the button was on. Absent for client and webhook actions.
+     */
+    channel?: ChannelActionSource;
+};
+/** Where a channel action came from: the connector and the verified event of the click. */
+export type ChannelActionSource = {
+    connectorId: string;
+    provider: string;
+    event: unknown;
+    deliveryId: string;
 };
 /**
  * Event passed to the `onTurnStart` callback.
@@ -1632,7 +1682,464 @@ export type ChatResumeEvent<TClientData = unknown, TUIM extends UIMessage = UIMe
     /** Custom data from the frontend. */
     clientData?: TClientData;
 };
-export type ChatAgentOptions<TIdentifier extends string, TClientDataSchema extends TaskSchema | undefined = undefined, TUIMessage extends UIMessage = UIMessage, TActionSchema extends TaskSchema | undefined = undefined, TTools extends ToolSet = ToolSet> = Omit<TaskOptions<TIdentifier, ChatTaskWirePayload<TUIMessage, inferSchemaIn<TClientDataSchema>>, unknown>, "run" | "retry"> & {
+export type ChannelMessageInput = string | UIMessage;
+/**
+ * What a connector's `inbound()` returns: the turn's message, optionally with who sent it on
+ * the provider and the provider's own message id. Both land on the user message's `metadata`
+ * (with `source: "channel"`, the connector id, the provider and the delivery id), so a
+ * transcript storage can attribute and reconcile channel messages.
+ */
+export type ChannelInbound = ChannelMessageInput | {
+    message: ChannelMessageInput;
+    externalUserId?: string;
+    externalMessageId?: string;
+};
+/** The `metadata` the runtime stamps on a channel-delivered user message. */
+export type ChannelMessageMetadata = {
+    source: "channel";
+    connectorId: string;
+    provider: string;
+    /** The delivery that carried the message (`whd_...`). */
+    deliveryId: string;
+    /** The provider's id for that delivery, the same across replays. */
+    externalDeliveryId?: string;
+    externalUserId?: string;
+    externalMessageId?: string;
+    /** True on a message the connector supplied from the surface's existing conversation via `seed()`. */
+    seeded?: boolean;
+};
+/**
+ * A prior message from the surface, returned by a connector's `seed()` when a session starts on a
+ * conversation that already has history (a Slack thread the bot was summoned into). Becomes a
+ * transcript message ahead of the triggering one, so the agent can answer with the context a human
+ * reading the thread would have.
+ */
+export type ChannelSeedMessage = {
+    role: "user" | "assistant";
+    text: string;
+    /** The provider's id for the message; used as the transcript message id suffix and kept in metadata. */
+    externalMessageId?: string;
+    externalUserId?: string;
+};
+export type ChannelSeedCtx<TEvent = unknown> = {
+    event: TEvent;
+    deliveryId: string;
+};
+/** A file a connector fetched for the model: its bytes, and the media type when the surface reports one. */
+export type ChannelDownloadedFile = {
+    data: Uint8Array;
+    mediaType?: string;
+};
+/**
+ * The channel a session answers into, once a channel turn has bound it. The connector's
+ * `bind()` derives the handle from a verified event; later turns that did not start from a
+ * channel delivery (a `chat.event` action that returns `chat.turn()`, a browser message on the
+ * same session) egress through it.
+ */
+export type ChannelBinding<THandle = unknown> = TranscriptChannelBinding<THandle>;
+export type ChannelMessage = {
+    text: string;
+    [key: string]: unknown;
+};
+export type ChannelReply = {
+    text: string;
+    message: UIMessage;
+    final: boolean;
+    stopped: boolean;
+    error?: unknown;
+    /**
+     * True when the turn paused on a human decision: this text is what the agent wrote before calling
+     * the tool, and the controls follow as their own message. A surface with a notion of "done" (Linear
+     * sessions) should post it as progress rather than as the answer.
+     */
+    pending?: boolean;
+};
+export type ChannelSendCtx<TEvent = unknown, THandle = unknown> = {
+    /** The verified event that started this turn. Absent on a bound turn that no channel delivery started. */
+    event?: TEvent;
+    /** The connector's posting handle from `bind()`, when the connector defines one. */
+    handle?: THandle;
+    /** The delivery that started this turn. Absent on a bound turn. */
+    deliveryId?: string;
+    previousRef?: string;
+    mode: "final" | "stream";
+    final: boolean;
+    /** True when this turn was not started by a channel delivery and egresses through the session's binding. */
+    bound: boolean;
+};
+export type ChannelAckCtx = {
+    /**
+     * True when this ack is being re-posted because the run is recovering an
+     * interrupted turn after a crash/continuation. The prior run's message ref
+     * is gone, so egress re-emits into the thread as a fresh message; a
+     * connector can vary the placeholder text to read as a deliberate resume
+     * ("picking this back up...") rather than a silent duplicate.
+     */
+    recovered: boolean;
+};
+/**
+ * A tool call the turn paused on, awaiting a human decision (HITL). `renderInteraction` maps these to
+ * the controls posted in the thread; the callback resolves one by `toolCallId`.
+ */
+export type ChannelPendingToolCall = {
+    toolCallId: string;
+    toolName: string;
+    input?: unknown;
+};
+/**
+ * A verified interaction callback resolved to a tool output. `onInteraction` returns this to resume the
+ * paused run: the framework stitches `output` onto the pending tool part and continues. Name the call
+ * by `toolCallId` when the surface can carry it (a Slack button value), or by `toolName` when it cannot
+ * (a Linear option whose value the user sees); the most recent pending call of that tool is resolved.
+ */
+export type ChannelInteractionResolution = {
+    toolCallId: string;
+    toolName?: string;
+    output: unknown;
+} | {
+    toolName: string;
+    toolCallId?: string;
+    output: unknown;
+};
+/**
+ * Context for `renderInteraction`: the event and delivery that started the turn, both absent on a
+ * bound turn (a `chat.turn()` action or a browser message answering into the bound thread).
+ */
+export type ChannelInteractionCtx<TEvent = unknown> = {
+    event?: TEvent;
+    deliveryId?: string;
+};
+export type ChannelReaction = {
+    name: string;
+    remove?: boolean;
+};
+export type ChannelReactCtx<TEvent = unknown> = {
+    event: TEvent;
+    deliveryId: string;
+};
+export type ChannelReactionChoice<TEvent = unknown> = string | string[] | ((event: TEvent) => string | string[] | null | undefined | Promise<string | string[] | null | undefined>);
+export type ChannelReactions<TEvent = unknown> = {
+    working?: ChannelReactionChoice<TEvent>;
+    done?: ChannelReactionChoice<TEvent>;
+    error?: ChannelReactionChoice<TEvent>;
+};
+export type ChannelRunSurface<TExtra extends Record<string, unknown> = Record<string, unknown>> = {
+    react: (name: string) => Promise<void>;
+    unreact: (name: string) => Promise<void>;
+} & TExtra;
+/**
+ * The turn a connector hook is running in: the verified event and delivery that started it (absent on
+ * a bound turn), and the session's posting handle from `bind()` when the connector defines one.
+ */
+export type ChannelTurnCtx<TEvent = unknown, THandle = unknown> = {
+    event?: TEvent;
+    handle?: THandle;
+    deliveryId?: string;
+    /** True when no channel delivery started this turn and it egresses through the session's binding. */
+    bound: boolean;
+};
+/**
+ * What a connector's `onControl()` maps a verified event to. `stop` aborts the turn in flight through
+ * the same per-turn stop signal the browser's stop button uses: the run's `stopSignal` fires,
+ * `streamText` aborts, the partial reply posts with `stopped: true`, and the event itself is consumed
+ * (it does not run as a turn).
+ *
+ * `whenIdle` decides what a stop does when no turn is in flight. `"message"` (the default) handles
+ * the event as a normal inbound message, so the connector's `inbound()` should give it a sensible
+ * reading. `"drop"` consumes it without a turn; if the session is paused on a human decision, the
+ * pending tool calls are resolved as stopped (a later approval click finds nothing to resume) and
+ * the connector's `cancelInteraction()` updates the controls.
+ *
+ * `at` is when the user asked to stop (epoch milliseconds). A stop older than the running turn's
+ * start belongs to an earlier turn: it is consumed without aborting this one.
+ */
+export type ChannelControl = {
+    kind: "stop";
+    message?: string;
+    whenIdle?: "message" | "drop";
+    at?: number;
+};
+/**
+ * What a connector's `progress()` hook observes while a turn streams: each tool call as its input is
+ * complete, and each result or error as it lands. Text deltas are not reported (use `delivery: "stream"`).
+ */
+export type ChannelProgressEvent = {
+    type: "tool-call";
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+} | {
+    type: "tool-result";
+    toolCallId: string;
+    toolName: string;
+    output: unknown;
+} | {
+    type: "tool-error";
+    toolCallId: string;
+    toolName: string;
+    errorText: string;
+};
+/**
+ * Where a channel session stands, reported to a connector's `lifecycle()` hook: `working` when a turn
+ * starts (and again every 50 minutes while it runs), `waiting` when it pauses on a human decision,
+ * `idle` when it ends for any reason (answered, empty, stopped or failed), and `closed` when the
+ * conversation is closed with `chat.close()`. A worker suspending between messages reports nothing.
+ */
+export type ChannelLifecycleState = "working" | "waiting" | "idle" | "closed";
+export type ChannelLifecycleCtx<TEvent = unknown, THandle = unknown> = ChannelTurnCtx<TEvent, THandle> & {
+    /** True on the session's first turn, when the surface creates its conversation. */
+    firstTurn: boolean;
+    /** The turn's user message text, when it has one (a title for the conversation). */
+    prompt?: string;
+    /** True on the periodic `working` re-send during a long turn. */
+    refresh?: boolean;
+};
+/** How a turn's reply stream ended, handed to {@link ChannelReplyStream.end}. */
+export type ChannelReplyStreamEnd = {
+    /** The turn was stopped (the partial reply is all there is). */
+    stopped: boolean;
+    /** The turn paused on a human decision; the controls follow as their own message. */
+    pending: boolean;
+    /** The sanitized error text when the turn ended on a model or stream error. */
+    errorText?: string;
+};
+/**
+ * A connector's native streaming transport for one turn, from its `stream()` hook, used when the
+ * connector's `delivery` is `"stream"`. The runtime feeds it the reply's text deltas as the model
+ * writes them (in the model's markdown) and the turn's tool progress, then ends it exactly once.
+ * `end()` resolves `delivered: true` when the reply reached the surface through the stream, so the
+ * runtime does not post it again; `false` (nothing was streamed) falls back to `send()`.
+ */
+export type ChannelReplyStream = {
+    text(delta: string): void;
+    progress?(event: ChannelProgressEvent): void;
+    end(outcome: ChannelReplyStreamEnd): Promise<{
+        delivered: boolean;
+    }>;
+};
+/**
+ * What a connector's `stream()` hook receives: the turn, and `opened(ref)` to call once the surface
+ * has created the stream message. The ref is saved with the session while the turn runs, so if the
+ * worker dies mid-stream the next worker can end that stream with `endInterruptedStream()`.
+ */
+export type ChannelStreamCtx<TEvent = unknown, THandle = unknown> = ChannelTurnCtx<TEvent, THandle> & {
+    opened(ref: string): void;
+};
+/** A pending tool call a stop cancelled, with the `ref` of the controls message that showed it. */
+export type ChannelCancelledToolCall = ChannelPendingToolCall & {
+    ref?: string;
+};
+export type ResolveChannelToken<TEvent = unknown> = (event: TEvent) => Promise<string>;
+declare const channelEventPhantom: unique symbol;
+export interface ChannelConnector<TEvent = unknown, THandle = unknown> {
+    id: string;
+    /** The endpoint this connector subscribes to (`webhooks.endpoint.define` id). */
+    endpointId: string;
+    source: string;
+    key: string;
+    filter?: string;
+    startOn?: string;
+    inbound: (event: TEvent) => ChannelInbound;
+    /**
+     * Derive the durable posting handle from a verified event (for Slack: team, channel, thread). When
+     * set, a channel turn binds the session to this connector, and later turns on the session that no
+     * channel delivery started (an action turn, a browser message) post their answer through `send`
+     * with `ctx.handle` and no `ctx.event`. Return null to leave the binding unchanged.
+     */
+    bind?: (event: TEvent) => THandle | null;
+    /**
+     * Supply the surface's existing conversation when a session starts on it (the bot was summoned
+     * into a thread that already has messages). Called once, on the first channel turn of a session
+     * with no history, before the triggering message is added. Return the prior messages in order,
+     * excluding the triggering one. Best effort: a throw is logged and the session starts empty.
+     */
+    seed?: (event: TEvent, ctx: ChannelSeedCtx<TEvent>) => Promise<ChannelSeedMessage[]> | ChannelSeedMessage[];
+    outbound?: (reply: ChannelReply) => ChannelMessage | null;
+    ack?: (event: TEvent, ctx: ChannelAckCtx) => ChannelMessage | null;
+    send?: (message: ChannelMessage, ctx: ChannelSendCtx<TEvent, THandle>) => Promise<{
+        ref?: string;
+    }>;
+    /** HITL: controls posted when a turn pauses on a human-decision tool (a tool with no `execute`). */
+    renderInteraction?: (pending: ChannelPendingToolCall[], ctx: ChannelInteractionCtx<TEvent>) => ChannelMessage | null;
+    /**
+     * HITL: map a verified callback event to a tool resolution. Non-null resumes the paused run; null
+     * means treat the event as a normal inbound message (a new turn).
+     */
+    onInteraction?: (event: TEvent) => ChannelInteractionResolution | null;
+    /**
+     * HITL: finalize the posted controls once a decision is made (edit them away, show the outcome), so
+     * the buttons can't be clicked again. Called with the same verified callback event when
+     * `onInteraction` resolves, before the run resumes. Best-effort: a throw is logged and the run continues.
+     */
+    finalizeInteraction?: (event: TEvent, resolution: ChannelInteractionResolution) => Promise<void> | void;
+    /**
+     * "final": the ack, then one post (or edit of the ack) when the turn ends. "stream": the connector's
+     * `stream()` transport when it has one, otherwise debounced edits of the ack.
+     */
+    delivery: "final" | "stream";
+    /**
+     * Native streaming for `delivery: "stream"`: open a {@link ChannelReplyStream} for this turn. Called
+     * once per turn that runs the model; return null to fall back to `send()` for this turn.
+     */
+    stream?: (ctx: ChannelStreamCtx<TEvent, THandle>) => ChannelReplyStream | null;
+    /**
+     * A worker booted on a session whose previous worker died with a reply stream open (the `ref` it
+     * passed to `opened()`). End that stream so it does not look like the agent is still writing; the
+     * recovered turn answers in a new one. Best effort: a throw is logged.
+     */
+    endInterruptedStream?: (ref: string, ctx: ChannelTurnCtx<TEvent, THandle>) => Promise<void> | void;
+    /**
+     * Fetch a file URL from the surface for the model, for files only the surface's credentials can
+     * read (a Slack `url_private`). The `streamText` given to `run()` calls it for every file URL in
+     * the prompt; return null for a URL this connector does not own. Throw when an owned file cannot
+     * be read: the turn replaces it with a short note and still runs. `handle` is the session's
+     * binding to this connector, when it has one.
+     */
+    download?: (url: URL, ctx: {
+        handle?: THandle;
+    }) => Promise<ChannelDownloadedFile | null>;
+    /**
+     * Acknowledge a message that arrives while a turn is running, as soon as it arrives: it is either
+     * folded into the running turn (`pendingMessages`) or answered right after it, so the wording
+     * should be true either way (`slack()` reacts with 👀, `linear()` posts a thought). Not called for
+     * stops, interaction clicks or empty messages. Called without waiting; a throw is ignored.
+     * `ctx.event` is the message's event.
+     */
+    received?: (ctx: ChannelTurnCtx<TEvent, THandle>) => Promise<void> | void;
+    /**
+     * Map a click on a control the agent posted (not a pending tool's control) to an action for the
+     * agent's `onAction`, validated against `actionSchema` like a client action. Return null for
+     * anything else. Returning `chat.turn()` from `onAction` answers into the session's thread.
+     */
+    toAction?: (event: TEvent) => unknown | null;
+    /**
+     * Mirror the session's state into the surface (a Slack agent session's status). See
+     * {@link ChannelLifecycleState}. Calls are serialized in order; a throw is logged and never
+     * affects the turn.
+     */
+    lifecycle?: (state: ChannelLifecycleState, ctx: ChannelLifecycleCtx<TEvent, THandle>) => Promise<void> | void;
+    /**
+     * HITL: a stop (`whenIdle: "drop"`) arrived while the session was paused on these tool calls. They
+     * are already resolved as stopped; update the controls so they no longer offer a decision.
+     * Best effort: a throw is logged.
+     */
+    cancelInteraction?: (cancelled: ChannelCancelledToolCall[], ctx: ChannelTurnCtx<TEvent, THandle>) => Promise<void> | void;
+    react?: (reaction: ChannelReaction, ctx: ChannelReactCtx<TEvent>) => Promise<void>;
+    reactions?: ChannelReactions<TEvent>;
+    /**
+     * Observe tool calls and results as the turn streams, to post progress into the surface (a Linear
+     * `action` activity, a Slack status). Called in order, awaited one at a time, independent of
+     * `delivery`. Best effort: a throw is logged and the turn continues.
+     */
+    progress?: (event: ChannelProgressEvent, ctx: ChannelTurnCtx<TEvent, THandle>) => Promise<void> | void;
+    /**
+     * Provider helpers merged into the `channel` object handed to `run()` (alongside `react`/`unreact`),
+     * such as a plan or a status setter. Built once per turn.
+     */
+    surface?: (ctx: ChannelTurnCtx<TEvent, THandle>) => Record<string, unknown>;
+    /**
+     * Map a verified event to a control instruction while a turn is running (a Stop in Linear, a
+     * "stop" slash command in Slack). See {@link ChannelControl}. Return null for an ordinary message.
+     */
+    onControl?: (event: TEvent) => ChannelControl | null;
+    readonly [channelEventPhantom]?: TEvent;
+}
+export type AnyChannelConnector = ChannelConnector<any, any>;
+/**
+ * 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 declare function chatChannelCustom<TEndpoint extends AnyWebhookEndpoint, const TKey extends string = string, const TFilter extends string = string, const TStartOn extends string = string, THandle = unknown>(options: {
+    id: string;
+    /** The endpoint this connector subscribes to. */
+    endpoint: TEndpoint;
+    /**
+     * The session each delivery goes to, as a template: `{event.x}` reads the event, `{header.x}` a
+     * header and `{webhook.x}` the endpoint, and `{a || b}` falls back to `b` when `a` is empty. e.g.
+     * `"{webhook.externalRef}:{event.data.object.customer}"`.
+     */
+    key: ValidatedWebhookKey<NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>, TKey>;
+    inbound: (event: NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>) => ChannelInbound;
+    bind?: (event: NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>) => THandle | null;
+    seed?: (event: NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>, ctx: ChannelSeedCtx<NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>>) => Promise<ChannelSeedMessage[]> | ChannelSeedMessage[];
+    outbound?: (reply: ChannelReply) => ChannelMessage | null;
+    ack?: (event: NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>, ctx: ChannelAckCtx) => ChannelMessage | null;
+    send?: (message: ChannelMessage, ctx: ChannelSendCtx<NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>, THandle>) => Promise<{
+        ref?: string;
+    }>;
+    renderInteraction?: (pending: ChannelPendingToolCall[], ctx: ChannelInteractionCtx<NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>>) => ChannelMessage | null;
+    onInteraction?: (event: NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>) => ChannelInteractionResolution | null;
+    finalizeInteraction?: (event: NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>, resolution: ChannelInteractionResolution) => Promise<void> | void;
+    react?: (reaction: ChannelReaction, ctx: ChannelReactCtx<NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>>) => Promise<void>;
+    reactions?: ChannelReactions<NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>>;
+    progress?: (event: ChannelProgressEvent, ctx: ChannelTurnCtx<NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>, THandle>) => Promise<void> | void;
+    surface?: (ctx: ChannelTurnCtx<NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>, THandle>) => Record<string, unknown>;
+    onControl?: (event: NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>) => ChannelControl | null;
+    stream?: (ctx: ChannelStreamCtx<NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>, THandle>) => ChannelReplyStream | null;
+    endInterruptedStream?: (ref: string, ctx: ChannelTurnCtx<NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>, THandle>) => Promise<void> | void;
+    download?: (url: URL, ctx: {
+        handle?: THandle;
+    }) => Promise<ChannelDownloadedFile | null>;
+    received?: (ctx: ChannelTurnCtx<InferWebhookEndpointEvent<TEndpoint>, THandle>) => Promise<void> | void;
+    toAction?: (event: InferWebhookEndpointEvent<TEndpoint>) => unknown | null;
+    lifecycle?: (state: ChannelLifecycleState, ctx: ChannelLifecycleCtx<NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>, THandle>) => Promise<void> | void;
+    cancelInteraction?: (cancelled: ChannelCancelledToolCall[], ctx: ChannelTurnCtx<NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>, THandle>) => Promise<void> | void;
+    filter?: ValidateWebhookFilter<InferWebhookEndpointEvent<TEndpoint>, TFilter>;
+    startOn?: ValidateWebhookFilter<InferWebhookEndpointEvent<TEndpoint>, TStartOn>;
+    delivery?: "final" | "stream";
+}): ChannelConnector<NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>, THandle>;
+export declare function resolveReactionChoice(choice: ChannelReactionChoice | undefined, event: unknown): Promise<string | undefined>;
+/**
+ * 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.
+ */
+declare function makeChannelProgressObserver(connector: AnyChannelConnector, wireEvent: {
+    event: unknown;
+    deliveryId: string;
+} | undefined, handle: unknown): ChannelStreamEditor;
+/**
+ * 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.
+ */
+declare function makeChannelLifecycleReporter(): {
+    report(connector: AnyChannelConnector | undefined, state: ChannelLifecycleState, ctx: ChannelLifecycleCtx): Promise<void>;
+    dispose: () => void;
+};
+declare function makeChannelStreamEditor<TEvent>(connector: ChannelConnector<TEvent>, channelEvent: {
+    event: unknown;
+    deliveryId: string;
+}, ackRef: string, handle?: unknown): {
+    observe(chunk: unknown): void;
+    stop(): Promise<void>;
+};
+type ChannelStreamEditor = {
+    observe(chunk: unknown): void;
+    stop(): void | Promise<void>;
+};
+/**
+ * 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.
+ */
+declare function makeChannelStreamTap(editor: ChannelStreamEditor, options?: {
+    stopOnEnd?: boolean;
+}): TransformStream<unknown, unknown>;
+export { makeChannelStreamEditor as __makeChannelStreamEditorForTests, makeChannelStreamTap as __makeChannelStreamTapForTests, makeChannelProgressObserver as __makeChannelProgressObserverForTests, makeChannelLifecycleReporter as __makeChannelLifecycleReporterForTests, };
+/** Resolves once the post-turn channel egress for `chatId` has finished (immediately when none is running). */
+export declare function __waitForChannelEgressForTests(chatId: string): Promise<void>;
+type ChatActionType<TActionSchema extends TaskSchema | undefined, TW extends readonly AnyChatEvent[]> = [TActionSchema] extends [TaskSchema] ? inferSchemaOut<TActionSchema> | ChatEventActions<TW> : [TW] extends [readonly []] ? unknown : ChatEventActions<TW>;
+export type ChatAgentOptions<TIdentifier extends string, TClientDataSchema extends TaskSchema | undefined = undefined, TUIMessage extends UIMessage = UIMessage, TActionSchema extends TaskSchema | undefined = undefined, TTools extends ToolSet = ToolSet, TW extends readonly AnyChatEvent[] = [], TChannels extends readonly AnyChannelConnector[] = []> = Omit<TaskOptions<TIdentifier, ChatTaskWirePayload<TUIMessage, inferSchemaIn<TClientDataSchema>>, unknown>, "run" | "retry"> & {
     /**
      * Fallback machine preset to use when an attempt fails with an
      * out-of-memory (OOM) error. Setting this enables a single OOM retry:
@@ -1736,9 +2243,22 @@ export type ChatAgentOptions<TIdentifier extends string, TClientDataSchema exten
      * action that returns nothing is a state edit only. Returning anything else
      * is an error; a response can no longer be returned directly.
      */
-    onAction?: (event: ActionEvent<[
-        TActionSchema
-    ] extends [TaskSchema] ? inferSchemaOut<TActionSchema> : unknown, inferSchemaOut<TClientDataSchema>, TUIMessage>) => Promise<void | ActionTurn> | void | ActionTurn;
+    /**
+     * Inbound `chat.event(...)` descriptors this agent handles. Listing one subscribes this agent to the
+     * descriptor's endpoint: each verified delivery goes to the session its `key` names and arrives at
+     * `onAction` as a `{ type, event, source, headers, deliveryId, externalDeliveryId, endpoint }` envelope whose `type` is
+     * the descriptor's `type`. The same descriptor listed on another agent is a second subscriber on the
+     * same endpoint.
+     */
+    events?: TW;
+    /**
+     * Inbound chat frontends (Slack, etc.) via `chat.channels.*`. Listing one subscribes this agent to
+     * the connector's endpoint, routing verified events to a durable per-key session as turns: the
+     * connector's `inbound()` maps the raw event to the turn's message, `run()` fires as normal, and the
+     * reply streams back to the channel. Use the connector's `filter` to ignore events.
+     */
+    channels?: TChannels;
+    onAction?: (event: ActionEvent<ChatActionType<TActionSchema, TW>, inferSchemaOut<TClientDataSchema>, TUIMessage>) => Promise<void | ActionTurn> | void | ActionTurn;
     /**
      * The tools available to this agent.
      *
@@ -1954,6 +2474,13 @@ export type ChatAgentOptions<TIdentifier extends string, TClientDataSchema exten
      *   },
      * });
      * ```
+     *
+     * Note: on a channel HITL resume turn (a button click that lands on a fresh
+     * run whose accumulator doesn't yet hold the pending tool call), this hook is
+     * called twice for the one delivery: once with `incomingMessages: []` to load
+     * the chain and locate the pending tool call, then again with the synthesized
+     * resolution message so it can be persisted. Keep the hook's read path
+     * idempotent.
      */
     hydrateMessages?: (event: HydrateMessagesEvent<inferSchemaOut<TClientDataSchema>, TUIMessage>) => TUIMessage[] | Promise<TUIMessage[]>;
     /**
@@ -2341,7 +2868,7 @@ type ChatCustomAgentOptions<TIdentifier extends string, TClientDataSchema extend
     run: TaskOptions<TIdentifier, ChatTaskWirePayload<TUIMessage, inferSchemaOut<TClientDataSchema>>, unknown>["run"];
 };
 declare function chatCustomAgent<TIdentifier extends string, TClientDataSchema extends TaskSchema | undefined = undefined, TUIMessage extends UIMessage = UIMessage>(options: ChatCustomAgentOptions<TIdentifier, TClientDataSchema, TUIMessage>): Task<TIdentifier, ChatTaskWirePayload<TUIMessage, inferSchemaIn<TClientDataSchema>>, unknown>;
-declare function chatAgent<TIdentifier extends string, TClientDataSchema extends TaskSchema | undefined = undefined, TUIMessage extends UIMessage = UIMessage, TActionSchema extends TaskSchema | undefined = undefined, TTools extends ToolSet = ToolSet>(options: ChatAgentOptions<TIdentifier, TClientDataSchema, TUIMessage, TActionSchema, TTools>): Task<TIdentifier, ChatTaskWirePayload<TUIMessage, inferSchemaIn<TClientDataSchema>>, unknown>;
+declare function chatAgent<TIdentifier extends string, TClientDataSchema extends TaskSchema | undefined = undefined, TUIMessage extends UIMessage = UIMessage, TActionSchema extends TaskSchema | undefined = undefined, TTools extends ToolSet = ToolSet, const TW extends readonly AnyChatEvent[] = [], const TChannels extends readonly AnyChannelConnector[] = []>(options: ChatAgentOptions<TIdentifier, TClientDataSchema, TUIMessage, TActionSchema, TTools, TW, TChannels>): Task<TIdentifier, ChatTaskWirePayload<TUIMessage, inferSchemaIn<TClientDataSchema>>, unknown>;
 /**
  * Optional config for {@link chat.withUIMessage}. `streamOptions` become default
  * static `toUIMessageStream()` settings; inner `chat.agent({ uiMessageStreamOptions })`
@@ -2552,6 +3079,20 @@ declare function setIdleTimeoutInSeconds(seconds: number): void;
  * ```
  */
 declare function setUIMessageStreamOptions(options: ChatUIMessageStreamOptions<UIMessage>): void;
+/**
+ * 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);
+ * }
+ * ```
+ */
+declare function getChannelSurface<T extends ChannelRunSurface = ChannelRunSurface>(): T | undefined;
 /**
  * Check whether the user stopped generation during the current turn.
  *
@@ -3407,6 +3948,13 @@ declare function createChatLoadTranscriptAction<TClientData = unknown>(storage:
 export declare const chat: {
     /** Create a chat agent. See {@link chatAgent}. */
     agent: typeof chatAgent;
+    /** Declare an inbound webhook event an agent claims via `chat.agent({ events })`. See {@link chatEvent}. */
+    event: typeof chatEvent;
+    /** Chat frontend connectors (Slack, etc.) an agent claims via `chat.agent({ channels })`. */
+    channels: {
+        /** A generic chat-frontend channel over any source, with your own egress. See {@link chatChannelCustom}. */
+        custom: typeof chatChannelCustom;
+    };
     /** Create a custom agent with manual lifecycle control. See {@link chatCustomAgent}. */
     customAgent: typeof chatCustomAgent;
     /** Create a chat task with a fixed {@link UIMessage} subtype and optional default stream options. See {@link withUIMessage}. */
@@ -3425,6 +3973,8 @@ export declare const chat: {
     local: typeof chatLocal;
     /** Create a public access token for a chat task. See {@link createChatAccessToken}. */
     createAccessToken: typeof createChatAccessToken;
+    /** Mint a read-only token to WATCH a session by externalId (cross-surface). See {@link createChatWatchToken}. */
+    createWatchToken: typeof createChatWatchToken;
     /** Override the turn timeout at runtime (duration string). See {@link setTurnTimeout}. */
     setTurnTimeout: typeof setTurnTimeout;
     /** Override the turn timeout at runtime (seconds). See {@link setTurnTimeoutInSeconds}. */
@@ -3435,6 +3985,8 @@ export declare const chat: {
     setUIMessageStreamOptions: typeof setUIMessageStreamOptions;
     /** Check if the current turn was stopped by the user. See {@link isStopped}. */
     isStopped: typeof isStopped;
+    /** The current turn's channel surface (reactions plus connector helpers), also from inside a tool. See {@link getChannelSurface}. */
+    surface: typeof getChannelSurface;
     /** Request that the run exits after the current turn so the next message starts on the latest version. See {@link requestUpgrade}. */
     requestUpgrade: typeof requestUpgrade;
     /** Hand off a custom agent Session to a fresh run. See {@link endAndContinue}. */