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

package/dist/esm/v3/test/mock-channel-connector.d.ts

@@ -0,0 +1,172 @@
+import type { ChannelAckCtx, ChannelCancelledToolCall, ChannelDownloadedFile, ChannelConnector, ChannelControl, ChannelInbound, ChannelInteractionCtx, ChannelInteractionResolution, ChannelLifecycleCtx, ChannelLifecycleState, ChannelMessage, ChannelPendingToolCall, ChannelProgressEvent, ChannelReaction, ChannelReactions, ChannelReply, ChannelReplyStreamEnd, ChannelSeedMessage, ChannelSendCtx, ChannelTurnCtx } from "../ai.js";
+/** The default event shape {@link recordingChannelConnector} maps when no `inbound` is given. */
+export type TestChannelEvent = {
+    text: string;
+    threadId?: string;
+    userId?: string;
+};
+/** The posting handle the default `bind` derives: the event's `threadId`. */
+export type TestChannelHandle = {
+    threadId: string;
+};
+/** A single `send()` call captured by {@link recordingChannelConnector}. */
+export type RecordedSend<TEvent = unknown> = {
+    /** The channel message the connector was asked to post (or edit into place). */
+    message: ChannelMessage;
+    /** The egress context: `final`, `mode`, `previousRef`, the raw `event`, `deliveryId`. */
+    ctx: ChannelSendCtx<TEvent>;
+    /** The ref this send resolved to (echoes `previousRef` on an edit, else a fresh id). */
+    ref: string;
+};
+/** A reaction applied to the triggering message, captured by {@link recordingChannelConnector}. */
+export type RecordedReaction<TEvent = unknown> = {
+    reaction: ChannelReaction;
+    event: TEvent;
+};
+/** A `progress()` call, captured by {@link recordingChannelConnector}. */
+type RecordedProgress<TEvent = unknown> = {
+    event: ChannelProgressEvent;
+    ctx: ChannelTurnCtx<TEvent>;
+};
+/** A `lifecycle()` report, captured by {@link recordingChannelConnector}. */
+export type RecordedLifecycle<TEvent = unknown> = {
+    state: ChannelLifecycleState;
+    ctx: ChannelLifecycleCtx<TEvent>;
+};
+/** One turn's native reply stream (`stream: true`), captured by {@link recordingChannelConnector}. */
+export type RecordedReplyStream<TEvent = unknown> = {
+    ctx: ChannelTurnCtx<TEvent>;
+    /** Every text delta, in order. */
+    deltas: string[];
+    progress: ChannelProgressEvent[];
+    /** How the runtime ended the stream; unset while the turn runs. */
+    ended?: ChannelReplyStreamEnd;
+    /** How many times `end()` was called (the runtime ends each stream once). */
+    endCalls: number;
+};
+/** A HITL `cancelInteraction()` call, captured by {@link recordingChannelConnector}. */
+export type RecordedCancel<TEvent = unknown> = {
+    cancelled: ChannelCancelledToolCall[];
+    ctx: ChannelTurnCtx<TEvent>;
+};
+/** A HITL `finalizeInteraction()` call, captured by {@link recordingChannelConnector}. */
+export type RecordedFinalize<TEvent = unknown> = {
+    event: TEvent;
+    resolution: ChannelInteractionResolution;
+};
+/**
+ * A real {@link ChannelConnector} whose egress hooks record what they were
+ * asked to do instead of touching a network, so a test can assert the channel
+ * round-trip a `chat.agent` turn produced. Built through the real
+ * `chat.channels.custom` factory, so it is a genuinely-shaped connector; only
+ * `send` / `ack` / `react` / `finalizeInteraction` are swapped for recorders.
+ */
+export type RecordingChannelConnector<TEvent = unknown> = ChannelConnector<TEvent> & {
+    /** Every `send()` call in order: the ack, any stream edits, and the final reply. */
+    readonly sent: ReadonlyArray<RecordedSend<TEvent>>;
+    /** Turn-start placeholder posts ("final" delivery): `final: false`, no `previousRef`. */
+    readonly acks: ReadonlyArray<RecordedSend<TEvent>>;
+    /** Stream-mode intermediate edits: `mode: "stream"`, `final: false`, with `previousRef`. */
+    readonly edits: ReadonlyArray<RecordedSend<TEvent>>;
+    /** Every reaction applied to the triggering message (lifecycle + `run().channel`). */
+    readonly reactionsApplied: ReadonlyArray<RecordedReaction<TEvent>>;
+    /** Every HITL `finalizeInteraction()` call. */
+    readonly finalized: ReadonlyArray<RecordedFinalize<TEvent>>;
+    /** Every `seed()` call's triggering event, in order. */
+    readonly seeded: ReadonlyArray<TEvent>;
+    /** Every `progress()` call (tool calls and results the turn streamed), in order. */
+    readonly progressed: ReadonlyArray<RecordedProgress<TEvent>>;
+    /** Every `lifecycle()` report, in order (`lifecycle: true`). */
+    readonly lifecycles: ReadonlyArray<RecordedLifecycle<TEvent>>;
+    /** Every native reply stream the runtime opened, one per turn (`stream: true`). */
+    readonly streams: ReadonlyArray<RecordedReplyStream<TEvent>>;
+    /** Every `cancelInteraction()` call. */
+    readonly cancelled: ReadonlyArray<RecordedCancel<TEvent>>;
+    /** Every `endInterruptedStream()` call: the ref of a stream a dead worker left open. */
+    readonly interrupted: ReadonlyArray<{
+        ref: string;
+        ctx: ChannelTurnCtx<TEvent>;
+    }>;
+    /** The ref of the most recent `send()`, i.e. the current edit target. */
+    readonly lastRef: string | undefined;
+    /** Text of the final reply (`final: true`), or `undefined` if none posted yet. */
+    finalText(): string | undefined;
+};
+/** Options for {@link recordingChannelConnector}. */
+export type RecordingChannelConnectorOptions<TEvent = TestChannelEvent> = {
+    /** Connector id. Defaults to {@link DEFAULT_TEST_CONNECTOR_ID} so it lines up with `sendChannelEvent`. */
+    id?: string;
+    /** The endpoint id the connector subscribes to. Server-side routing only; defaults to `"test-channel"`. */
+    endpointId?: string;
+    /** `"final"` (default: ack then edit-to-answer) or `"stream"` (debounced live edits). */
+    delivery?: "final" | "stream";
+    /** Session key template. Unused in-run (server-side routing only); defaults to `"{event.threadId}"`. */
+    key?: string;
+    /** Map the raw event to the turn's message. Defaults to `event.text`, attributed to `event.userId`. */
+    inbound?: (event: TEvent) => ChannelInbound;
+    /** Map the reply to the posted message. Defaults to `{ text }`; receives the full {@link ChannelReply}. */
+    outbound?: (reply: ChannelReply) => ChannelMessage | null;
+    /**
+     * Derive the session's posting handle from an event, so turns that no channel delivery started
+     * (an action turn, a browser message) still egress through this connector with `ctx.handle` and
+     * `ctx.bound: true`. Defaults to `{ threadId: event.threadId }`; pass `null` to make the
+     * connector unbindable.
+     */
+    bind?: ((event: TEvent) => unknown | null) | null;
+    /** Prior surface messages to seed a new session with (what `seed()` returns). Recorded per call. */
+    seed?: (event: TEvent) => Promise<ChannelSeedMessage[]> | ChannelSeedMessage[];
+    /**
+     * Placeholder posted at turn start ("final" delivery). Defaults to `{ text: "..." }`.
+     * Pass `null` (or a function returning `null`) to post no ack, so the final reply
+     * arrives as a fresh message instead of an edit.
+     */
+    ack?: ChannelMessage | null | ((event: TEvent, ctx: ChannelAckCtx) => ChannelMessage | null);
+    /** HITL: map a verified callback event to a tool resolution (null => treat as a normal message). */
+    onInteraction?: (event: TEvent) => ChannelInteractionResolution | null;
+    /** Fetch a file URL the connector owns for the model; null for URLs it does not own. */
+    download?: (url: URL, ctx: {
+        handle?: unknown;
+    }) => Promise<ChannelDownloadedFile | null>;
+    /** Map a click on an agent-posted control to an action for `onAction` (null for anything else). */
+    toAction?: (event: TEvent) => unknown | null;
+    /** Acknowledge a message that arrives while a turn is running. */
+    received?: (ctx: ChannelTurnCtx<TEvent>) => Promise<void> | void;
+    /** HITL: map the pending tool call(s) to the controls posted in the thread. */
+    renderInteraction?: (pending: ChannelPendingToolCall[], ctx: ChannelInteractionCtx<TEvent>) => ChannelMessage | null;
+    /** Lifecycle reaction choices (working/done/error). Requires nothing extra; `react` is always recorded. */
+    reactions?: ChannelReactions<TEvent>;
+    /** Record tool-call progress (`progress()` hook). Off by default so existing turns post nothing extra. */
+    progress?: boolean;
+    /** Provider helpers merged into `run({ channel })`. */
+    surface?: (ctx: ChannelTurnCtx<TEvent>) => Record<string, unknown>;
+    /** Map an event to a control (`{ kind: "stop" }`) while a turn runs. */
+    onControl?: (event: TEvent) => ChannelControl | null;
+    /** Record `lifecycle()` reports. Off by default. */
+    lifecycle?: boolean;
+    /**
+     * Stream replies natively (`delivery: "stream"` with a recording `stream()` hook): each turn's
+     * deltas and end outcome land in `streams`, the stream reports `opened("stream_<n>")` on its
+     * first delta, and it reports delivered when it saw text. `{ delivered: false }` reports every
+     * stream undelivered, like a Slack stream whose fallback post of the rest of the reply failed.
+     */
+    stream?: boolean | {
+        delivered: false;
+    };
+};
+/**
+ * Create a {@link RecordingChannelConnector} for driving a `chat.agent`
+ * channel turn offline. Pair it with `mockChatAgent(...).sendChannelEvent(...)`:
+ * list the connector on the agent's `channels`, deliver an event, then assert
+ * against `connector.sent` / `.acks` / `.edits` / `.finalText()`.
+ *
+ * @example
+ * ```ts
+ * const channel = recordingChannelConnector();
+ * const agent = chat.agent({ id: "support", channels: [channel], run: ... });
+ * const harness = mockChatAgent(agent);
+ * await harness.sendChannelEvent({ event: { text: "hi", threadId: "t1" } });
+ * expect(channel.finalText()).toBe("hello");
+ * ```
+ */
+export declare function recordingChannelConnector<TEvent = TestChannelEvent>(options?: RecordingChannelConnectorOptions<TEvent>): RecordingChannelConnector<TEvent>;
+export {};

package/dist/esm/v3/test/mock-channel-connector.js

@@ -0,0 +1,170 @@
+import { chat } from "../ai.js";
+import { DEFAULT_TEST_CONNECTOR_ID } from "./mock-chat-agent.js";
+const DEFAULT_TEST_ENDPOINT_ID = "test-channel";
+/**
+ * Create a {@link RecordingChannelConnector} for driving a `chat.agent`
+ * channel turn offline. Pair it with `mockChatAgent(...).sendChannelEvent(...)`:
+ * list the connector on the agent's `channels`, deliver an event, then assert
+ * against `connector.sent` / `.acks` / `.edits` / `.finalText()`.
+ *
+ * @example
+ * ```ts
+ * const channel = recordingChannelConnector();
+ * const agent = chat.agent({ id: "support", channels: [channel], run: ... });
+ * const harness = mockChatAgent(agent);
+ * await harness.sendChannelEvent({ event: { text: "hi", threadId: "t1" } });
+ * expect(channel.finalText()).toBe("hello");
+ * ```
+ */
+export function recordingChannelConnector(options = {}) {
+    const sent = [];
+    const reactionsApplied = [];
+    const finalized = [];
+    const seeded = [];
+    const progressed = [];
+    const lifecycles = [];
+    const streams = [];
+    const cancelled = [];
+    const interrupted = [];
+    let refCounter = 0;
+    let lastRef;
+    const inbound = options.inbound ??
+        ((event) => {
+            const e = event;
+            return { message: e?.text ?? "", externalUserId: e?.userId };
+        });
+    const bind = options.bind === null
+        ? undefined
+        : (options.bind ??
+            ((event) => {
+                const threadId = event?.threadId;
+                return threadId ? { threadId } : null;
+            }));
+    const ackFn = options.ack === undefined
+        ? () => ({ text: "..." })
+        : typeof options.ack === "function"
+            ? options.ack
+            : () => options.ack;
+    const send = async (message, ctx) => {
+        const ref = ctx.previousRef ?? `ref_${++refCounter}`;
+        sent.push({ message, ctx, ref });
+        lastRef = ref;
+        return { ref };
+    };
+    const react = async (reaction, ctx) => {
+        reactionsApplied.push({ reaction, event: ctx.event });
+    };
+    const finalizeInteraction = async (event, resolution) => {
+        finalized.push({ event, resolution });
+    };
+    const connector = chat.channels.custom({
+        id: options.id ?? DEFAULT_TEST_CONNECTOR_ID,
+        endpoint: {
+            id: options.endpointId ?? DEFAULT_TEST_ENDPOINT_ID,
+            source: "custom",
+        },
+        key: (options.key ?? "{event.threadId}"),
+        inbound: inbound,
+        ...(bind ? { bind: bind } : {}),
+        ...(options.seed
+            ? {
+                seed: (async (event) => {
+                    seeded.push(event);
+                    return options.seed(event);
+                }),
+            }
+            : {}),
+        ack: ackFn,
+        ...(options.outbound ? { outbound: options.outbound } : {}),
+        send: send,
+        react: react,
+        finalizeInteraction: finalizeInteraction,
+        ...(options.onInteraction ? { onInteraction: options.onInteraction } : {}),
+        ...(options.download ? { download: options.download } : {}),
+        ...(options.toAction ? { toAction: options.toAction } : {}),
+        ...(options.received ? { received: options.received } : {}),
+        ...(options.renderInteraction ? { renderInteraction: options.renderInteraction } : {}),
+        ...(options.reactions ? { reactions: options.reactions } : {}),
+        ...(options.progress
+            ? {
+                progress: ((event, ctx) => {
+                    progressed.push({ event, ctx });
+                }),
+            }
+            : {}),
+        ...(options.surface ? { surface: options.surface } : {}),
+        ...(options.onControl ? { onControl: options.onControl } : {}),
+        ...(options.lifecycle
+            ? {
+                lifecycle: ((state, ctx) => {
+                    lifecycles.push({ state, ctx });
+                }),
+            }
+            : {}),
+        ...(options.stream
+            ? {
+                stream: ((ctx) => {
+                    const recorded = {
+                        ctx,
+                        deltas: [],
+                        progress: [],
+                        endCalls: 0,
+                    };
+                    streams.push(recorded);
+                    return {
+                        text: (delta) => {
+                            if (recorded.deltas.length === 0)
+                                ctx.opened(`stream_${streams.length}`);
+                            recorded.deltas.push(delta);
+                        },
+                        progress: (event) => {
+                            recorded.progress.push(event);
+                        },
+                        end: async (outcome) => {
+                            recorded.endCalls += 1;
+                            recorded.ended = outcome;
+                            const undelivered = typeof options.stream === "object" && options.stream.delivered === false;
+                            return { delivered: !undelivered && recorded.deltas.join("").length > 0 };
+                        },
+                    };
+                }),
+            }
+            : {}),
+        endInterruptedStream: ((ref, ctx) => {
+            interrupted.push({ ref, ctx });
+        }),
+        cancelInteraction: ((cancelledCalls, ctx) => {
+            cancelled.push({ cancelled: cancelledCalls, ctx });
+        }),
+        delivery: options.delivery ?? (options.stream ? "stream" : "final"),
+    });
+    Object.defineProperties(connector, {
+        sent: { get: () => sent, enumerable: true },
+        reactionsApplied: { get: () => reactionsApplied, enumerable: true },
+        finalized: { get: () => finalized, enumerable: true },
+        seeded: { get: () => seeded, enumerable: true },
+        progressed: { get: () => progressed, enumerable: true },
+        lifecycles: { get: () => lifecycles, enumerable: true },
+        streams: { get: () => streams, enumerable: true },
+        cancelled: { get: () => cancelled, enumerable: true },
+        interrupted: { get: () => interrupted, enumerable: true },
+        lastRef: { get: () => lastRef, enumerable: true },
+        acks: {
+            get: () => sent.filter((s) => s.ctx.final === false && s.ctx.previousRef === undefined),
+            enumerable: true,
+        },
+        edits: {
+            get: () => sent.filter((s) => s.ctx.mode === "stream" && s.ctx.final === false && s.ctx.previousRef !== undefined),
+            enumerable: true,
+        },
+    });
+    connector.finalText = () => {
+        for (let i = sent.length - 1; i >= 0; i--) {
+            if (sent[i].ctx.final)
+                return sent[i].message.text;
+        }
+        return undefined;
+    };
+    return connector;
+}
+//# sourceMappingURL=mock-channel-connector.js.map

package/dist/esm/v3/test/mock-channel-connector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-channel-connector.js","sourceRoot":"","sources":["../../../../src/v3/test/mock-channel-connector.ts"],"names":[],"mappings":"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"}

package/dist/esm/v3/test/mock-chat-agent.d.ts

@@ -13,6 +13,19 @@ type ChatAgentHandle = {
 /**
  * Options for `mockChatAgent`.
  */
+/**
+ * A channel delivery to seed on the `session.in` tail for the next boot's replay, alongside browser
+ * messages, so a test can check that recovery dispatches both kinds in the order they arrived.
+ */
+export type SeededChannelDelivery = {
+    channelEvent: {
+        event: unknown;
+        connectorId?: string;
+        source?: string;
+        headers?: Record<string, string>;
+        deliveryId?: string;
+    };
+};
 export type MockChatAgentOptions = {
     /** The chat session id passed into every wire payload. Defaults to `"test-chat"`. */
     chatId?: string;
@@ -147,6 +160,20 @@ export type MockChatAgentHarness = {
     }): Promise<MockChatAgentTurn>;
     /** Send a custom action and wait for the next turn-complete. */
     sendAction(action: unknown): Promise<MockChatAgentTurn>;
+    /**
+     * Deliver a `chat.event` webhook action: the `{ type, event, source, headers, deliveryId, externalDeliveryId }`
+     * envelope the hosted ingress appends to `session.in` with `actionSource: "webhook"`, so it
+     * bypasses `actionSchema` and reaches `onAction` typed by the listed events. Waits for the
+     * turn-complete the action (or the turn it becomes via `chat.turn()`) writes.
+     */
+    sendWebhookAction(args: {
+        type: string;
+        event: unknown;
+        source?: string;
+        headers?: Record<string, string>;
+        deliveryId?: string;
+        externalDeliveryId?: string;
+    }): Promise<MockChatAgentTurn>;
     /**
      * Deliver a message mid-turn without waiting for it, the way the browser's
      * steering path does. With a `pendingMessages` config the agent routes it into
@@ -157,6 +184,52 @@ export type MockChatAgentHarness = {
      * call this. Awaiting the turn first leaves nothing to steer.
      */
     sendPendingMessage(message: UIMessage): Promise<void>;
+    /**
+     * Deliver a channel event mid-turn without waiting for it, the way a Slack message lands while
+     * the agent is answering. With a `pendingMessages` config it can be steered into the running
+     * turn; otherwise, or when `shouldInject` declines, it runs as the next turn.
+     */
+    sendPendingChannelEvent(args: {
+        event: unknown;
+        connectorId?: string;
+        source?: string;
+        deliveryId?: string;
+    }): Promise<void>;
+    /**
+     * Deliver a verified channel event (Slack or any `chat.channels.*`
+     * connector) and wait for the next turn-complete. Mirrors what the hosted
+     * webhook ingress appends to `session.in`: a `submit-message` wire payload
+     * carrying `channelEvent` instead of `message`. The run resolves the
+     * connector by `connectorId`, maps the event with its `inbound()`, runs the
+     * turn, and posts the reply back through the connector's `send()`.
+     *
+     * `connectorId` defaults to `DEFAULT_TEST_CONNECTOR_ID`, which is also the id
+     * `recordingChannelConnector()` uses when you don't set one, so the common
+     * single-connector case lines up. Pass it explicitly for a connector with a
+     * custom id or for multi-connector agents.
+     */
+    sendChannelEvent(args: {
+        event: unknown;
+        connectorId?: string;
+        source?: string;
+        headers?: Record<string, string>;
+        deliveryId?: string;
+        externalDeliveryId?: string;
+    }): Promise<MockChatAgentTurn>;
+    /**
+     * Deliver a channel event without waiting for a turn. Mirrors an event that
+     * the run may not turn into a turn: a filtered or deduped delivery, or a
+     * stale interaction callback that is dropped (matches no pending tool call).
+     * Resolves once the run has had a chance to process and possibly drop it.
+     */
+    deliverChannelEvent(args: {
+        event: unknown;
+        connectorId?: string;
+        source?: string;
+        headers?: Record<string, string>;
+        deliveryId?: string;
+        externalDeliveryId?: string;
+    }): Promise<void>;
     /** Fire a stop signal. Does not wait for the turn — the task keeps running. */
     sendStop(message?: string): Promise<void>;
     /**
@@ -219,7 +292,7 @@ export type MockChatAgentHarness = {
      *
      * Effective on the next run boot only.
      */
-    seedSessionInTail(messages: UIMessage[]): void;
+    seedSessionInTail(entries: Array<UIMessage | SeededChannelDelivery>): void;
     /**
      * Append a `trigger: "close"` record to `session.in` — what the server does
      * when a session is closed from outside (dashboard, `sessions.close()`, MCP).
@@ -270,6 +343,13 @@ export type MockChatAgentHarness = {
     /** Every raw chunk (including control chunks) emitted since the harness was created. */
     readonly allRawChunks: unknown[];
 };
+/**
+ * Default `connectorId` used by {@link MockChatAgentHarness.sendChannelEvent}
+ * when the caller omits it. Matches the default `id` of
+ * {@link recordingChannelConnector}, so a single-connector agent needs no
+ * explicit id on either side.
+ */
+export declare const DEFAULT_TEST_CONNECTOR_ID = "test-channel";
 /**
  * Create an offline test harness for a `chat.agent` task.
  *

package/dist/esm/v3/test/mock-chat-agent.js

@@ -1,9 +1,37 @@
 import { resourceCatalog, sessionStreams } from "@trigger.dev/core/v3";
 import { runInMockTaskContext } from "@trigger.dev/core/v3/test";
 import { __setSessionCloseImplForTests, __setSessionOpenImplForTests, __setSessionStartImplForTests, } from "../sessions.js";
-import { __resetChatInputRouterForTests, __setReadChatSnapshotImplForTests, __setReplaySessionInTailImplForTests, __setReplaySessionOutTailImplForTests, __setWriteChatSnapshotImplForTests, } from "../ai.js";
+import { __resetChatInputRouterForTests, __setReadChatSnapshotImplForTests, __waitForChannelEgressForTests, __setReplaySessionInTailImplForTests, __setReplaySessionOutTailImplForTests, __setWriteChatSnapshotImplForTests, } from "../ai.js";
 import { createTestSessionHandle } from "./test-session-handle.js";
 import { reduceUIMessageChunks } from "../uiMessageChunks.js";
+/**
+ * Default `connectorId` used by {@link MockChatAgentHarness.sendChannelEvent}
+ * when the caller omits it. Matches the default `id` of
+ * {@link recordingChannelConnector}, so a single-connector agent needs no
+ * explicit id on either side.
+ */
+export const DEFAULT_TEST_CONNECTOR_ID = "test-channel";
+/**
+ * Wait for a channel turn's post-completion egress to land. The run loop
+ * writes the `trigger:turn-complete` chunk (which unblocks the harness's
+ * turn-complete latch) BEFORE it awaits the connector's final `send()` and
+ * its done/error reactions, and settles a per-chat latch once those have
+ * finished. Awaiting that latch, rather than draining timers, makes the
+ * connector's recorded sends and reactions deterministic for any connector
+ * latency. A latch that never settles is a runtime bug, so it fails loudly.
+ */
+async function settlePostTurnChannelEgress(chatId) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`channel egress for ${chatId} did not settle within 10s`)), 10_000);
+    });
+    try {
+        await Promise.race([__waitForChannelEgressForTests(chatId), timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 const CONTROL_CHUNK_TYPES = new Set(["trigger:turn-complete", "trigger:upgrade-required"]);
 function isControlChunk(chunk) {
     if (typeof chunk !== "object" || chunk === null)
@@ -88,6 +116,7 @@ export function mockChatAgent(agent, options = {}) {
     let sendSessionInput;
     let closeSessionInput;
     let runSignal;
+    let channelDeliveryCounter = 0;
     // A latch that resolves every time `trigger:turn-complete` appears on the chat stream.
     // We use a shared pending promise and replace it after each completion.
     let turnCompleteResolvers = [];
@@ -109,7 +138,7 @@ export function mockChatAgent(agent, options = {}) {
     let lastWrittenSnapshot;
     let seededReplayChunks = [];
     let seededReplayPartial;
-    let seededSessionInMessages = [];
+    let seededSessionInTail = [];
     const closeCalls = [];
     let failCloseCalls = 0;
     __resetChatInputRouterForTests();
@@ -137,11 +166,27 @@ export function mockChatAgent(agent, options = {}) {
         };
     });
     __setReplaySessionInTailImplForTests(async () => {
-        return seededSessionInMessages.map((message, i) => ({
-            message,
-            metadata: clientData,
-            seqNum: i + 1,
-        }));
+        const messages = [];
+        const channelEvents = [];
+        seededSessionInTail.forEach((entry, i) => {
+            if ("channelEvent" in entry) {
+                channelEvents.push({
+                    channelEvent: {
+                        connectorId: entry.channelEvent.connectorId ?? DEFAULT_TEST_CONNECTOR_ID,
+                        event: entry.channelEvent.event,
+                        source: entry.channelEvent.source ?? "custom",
+                        headers: entry.channelEvent.headers ?? {},
+                        deliveryId: entry.channelEvent.deliveryId ?? `dlv_seeded_${i + 1}`,
+                    },
+                    metadata: clientData,
+                    seqNum: i + 1,
+                });
+            }
+            else {
+                messages.push({ message: entry, metadata: clientData, seqNum: i + 1 });
+            }
+        });
+        return { messages, channelEvents };
     });
     // Install the session open override so `sessions.open(id)` returns a
     // SessionHandle with an in-memory `.out` that captures writes. The
@@ -344,6 +389,52 @@ export function mockChatAgent(agent, options = {}) {
                 metadata: clientData,
             });
         },
+        async sendWebhookAction(args) {
+            const deliveryId = args.deliveryId ?? `dlv_${++channelDeliveryCounter}`;
+            const turn = await sendPayloadAndWait({
+                chatId,
+                trigger: "action",
+                actionSource: "webhook",
+                action: {
+                    type: args.type,
+                    event: args.event,
+                    source: args.source ?? "custom",
+                    headers: args.headers ?? {},
+                    deliveryId,
+                    ...(args.externalDeliveryId ? { externalDeliveryId: args.externalDeliveryId } : {}),
+                },
+                metadata: clientData,
+            });
+            await settlePostTurnChannelEgress(chatId);
+            return turn;
+        },
+        async sendPendingChannelEvent(args) {
+            await harnessReady;
+            const seqBefore = sessionStreams.lastSeqNum(chatId, "in") ?? -1;
+            const deliveryId = args.deliveryId ?? `dlv_${++channelDeliveryCounter}`;
+            await sendSessionInput(sessionId, {
+                kind: "message",
+                payload: {
+                    chatId,
+                    trigger: "submit-message",
+                    channelEvent: {
+                        connectorId: args.connectorId ?? DEFAULT_TEST_CONNECTOR_ID,
+                        event: args.event,
+                        source: args.source ?? "custom",
+                        headers: {},
+                        deliveryId,
+                    },
+                    metadata: clientData,
+                },
+            });
+            const deadline = Date.now() + 5_000;
+            while ((sessionStreams.lastSeqNum(chatId, "in") ?? -1) <= seqBefore) {
+                if (Date.now() > deadline) {
+                    throw new Error(`sendPendingChannelEvent: ${deliveryId} never landed on session.in`);
+                }
+                await new Promise((resolve) => setTimeout(resolve, 5));
+            }
+        },
         async sendPendingMessage(message) {
             await harnessReady;
             const seqBefore = sessionStreams.lastSeqNum(chatId, "in") ?? -1;
@@ -371,6 +462,41 @@ export function mockChatAgent(agent, options = {}) {
                 await new Promise((resolve) => setTimeout(resolve, 5));
             }
         },
+        async sendChannelEvent(args) {
+            const deliveryId = args.deliveryId ?? `dlv_${++channelDeliveryCounter}`;
+            const turn = await sendPayloadAndWait({
+                chatId,
+                trigger: "submit-message",
+                channelEvent: {
+                    connectorId: args.connectorId ?? DEFAULT_TEST_CONNECTOR_ID,
+                    event: args.event,
+                    source: args.source ?? "custom",
+                    headers: args.headers ?? {},
+                    deliveryId,
+                    ...(args.externalDeliveryId ? { externalDeliveryId: args.externalDeliveryId } : {}),
+                },
+                metadata: clientData,
+            });
+            await settlePostTurnChannelEgress(chatId);
+            return turn;
+        },
+        async deliverChannelEvent(args) {
+            const deliveryId = args.deliveryId ?? `dlv_${++channelDeliveryCounter}`;
+            await sendPayloadAndWait({
+                chatId,
+                trigger: "submit-message",
+                channelEvent: {
+                    connectorId: args.connectorId ?? DEFAULT_TEST_CONNECTOR_ID,
+                    event: args.event,
+                    source: args.source ?? "custom",
+                    headers: args.headers ?? {},
+                    deliveryId,
+                    ...(args.externalDeliveryId ? { externalDeliveryId: args.externalDeliveryId } : {}),
+                },
+                metadata: clientData,
+            });
+            await settlePostTurnChannelEgress(chatId);
+        },
         async sendStop(message) {
             await harnessReady;
             await sendSessionInput(sessionId, { kind: "stop", message });
@@ -442,12 +568,12 @@ export function mockChatAgent(agent, options = {}) {
         seedSessionOutPartial(partial) {
             seededReplayPartial = partial;
         },
-        seedSessionInTail(messages) {
-            seededSessionInMessages = messages;
+        seedSessionInTail(entries) {
+            seededSessionInTail = entries;
             // The seeded tail occupies seqNums 1..n of the channel, so anything sent
             // live afterwards has to continue above it.
-            if (messages.length > 0) {
-                sessionStreams.setLastSeqNum(sessionId, "in", messages.length);
+            if (entries.length > 0) {
+                sessionStreams.setLastSeqNum(sessionId, "in", entries.length);
             }
         },
         async deliverSessionInAtSeq(message, seqNum) {