test(sdk): channel interaction coverage in the chat.agent test harness

Add a fire-and-forget deliverChannelEvent to the harness and loop-level tests
for the channel interaction paths: a resolved interaction callback resumes the
pending tool and finalizes the controls, and a stale callback that matches no
pending tool is dropped without running a turn or posting anything.

Author: ericallam

packages/trigger-sdk/src/v3/test/mock-chat-agent.ts

@@ -219,6 +219,20 @@ export type MockChatAgentHarness = {
     deliveryId?: 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;
+  }): Promise<void>;
+
   /** Fire a stop signal. Does not wait for the turn — the task keeps running. */
   sendStop(message?: string): Promise<void>;
 
@@ -691,6 +705,27 @@ export function mockChatAgent(
       return turn;
     },
 
+    async deliverChannelEvent(args) {
+      await harnessReady;
+      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: args.headers ?? {},
+            deliveryId,
+          },
+          metadata: clientData,
+        },
+      });
+      await settlePostTurnChannelEgress();
+    },
+
     async sendStop(message) {
       await harnessReady;
       await sendSessionInput(sessionId, { kind: "stop", message });

packages/trigger-sdk/test/chatChannels.test.ts

@@ -6,9 +6,10 @@ import {
   __makeChannelStreamEditorForTests,
   __makeChannelStreamTapForTests,
 } from "../src/v3/ai.js";
-import { simulateReadableStream, streamText } from "ai";
+import { simulateReadableStream, streamText, tool } from "ai";
 import { MockLanguageModelV3 } from "ai/test";
 import type { LanguageModelV3StreamPart } from "@ai-sdk/provider";
+import { z } from "zod";
 
 function textStream(text: string) {
   const chunks: LanguageModelV3StreamPart[] = [
@@ -178,6 +179,109 @@ describe("chat.agent channels", () => {
   });
 });
 
+describe("chat.agent channel interactions", () => {
+  function toolCallStream(toolCallId: string, toolName: string, input: unknown) {
+    return simulateReadableStream({
+      chunks: [
+        { type: "tool-input-start", id: toolCallId, toolName },
+        { type: "tool-input-delta", id: toolCallId, delta: JSON.stringify(input) },
+        { type: "tool-input-end", id: toolCallId },
+        { type: "tool-call", toolCallId, toolName, input: JSON.stringify(input) },
+        {
+          type: "finish",
+          finishReason: { unified: "tool-calls", raw: "tool_calls" },
+          usage: {
+            inputTokens: { total: 10, noCache: 10, cacheRead: undefined, cacheWrite: undefined },
+            outputTokens: { total: 10, text: 0, reasoning: undefined },
+          },
+        },
+      ] as LanguageModelV3StreamPart[],
+    });
+  }
+
+  it("resumes a pending tool from an interaction callback and finalizes the controls", async () => {
+    const TC = "tc_approve_1";
+    const requestApproval = tool({
+      description: "Request human approval before acting.",
+      inputSchema: z.object({ action: z.string() }),
+    });
+
+    let call = 0;
+    const model = new MockLanguageModelV3({
+      doStream: async () => ({
+        stream:
+          call++ === 0
+            ? toolCallStream(TC, "requestApproval", { action: "refund" })
+            : textStream("refund issued"),
+      }),
+    });
+
+    const channel = recordingChannelConnector<{ text?: string; callback?: boolean }>({
+      renderInteraction: (pending) => ({
+        text: `Approve ${(pending[0]!.input as { action: string }).action}?`,
+      }),
+      onInteraction: (event) =>
+        event?.callback ? { toolCallId: TC, output: { approved: true } } : null,
+    });
+
+    const agent = chat.agent({
+      id: "chatChannels.hitl-resolve",
+      channels: [channel],
+      run: async ({ messages, signal }) =>
+        streamText({ model, messages, tools: { requestApproval }, abortSignal: signal }),
+    });
+
+    const harness = mockChatAgent(agent, { chatId: "chan-hitl-1" });
+    try {
+      await harness.sendChannelEvent({ event: { text: "please refund", threadId: "chan-hitl-1" } });
+      expect(channel.finalText()).toBe("Approve refund?");
+      expect(channel.finalized).toHaveLength(0);
+
+      await harness.sendChannelEvent({ event: { callback: true } });
+      expect(channel.finalized).toHaveLength(1);
+      expect(channel.finalText()).toBe("refund issued");
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it("drops a stale interaction callback and runs no turn", async () => {
+    let modelCalls = 0;
+    const model = new MockLanguageModelV3({
+      doStream: async () => {
+        modelCalls += 1;
+        return { stream: textStream("should not run") };
+      },
+    });
+
+    const interactionEvents: unknown[] = [];
+    const channel = recordingChannelConnector<{ text?: string; callback?: boolean }>({
+      onInteraction: (event) => {
+        interactionEvents.push(event);
+        return event?.callback ? { toolCallId: "does-not-exist", output: {} } : null;
+      },
+    });
+
+    const agent = chat.agent({
+      id: "chatChannels.hitl-stale",
+      channels: [channel],
+      run: async ({ messages, signal }) => streamText({ model, messages, abortSignal: signal }),
+    });
+
+    const harness = mockChatAgent(agent, { chatId: "chan-hitl-2" });
+    try {
+      await harness.deliverChannelEvent({ event: { callback: true } });
+
+      expect(interactionEvents).toHaveLength(1);
+      expect(modelCalls).toBe(0);
+      expect(channel.sent).toHaveLength(0);
+      expect(channel.finalized).toHaveLength(0);
+    } finally {
+      await harness.close();
+    }
+  });
+});
+
 describe("makeChannelStreamEditor", () => {
   function streamConnector(send: (message: { text: string }) => Promise<{ ref?: string }>) {
     return { delivery: "stream" as const, send } as never;