feat(channels): the Web Channel, its browser client and WebSockets.use

.changeset/channels-web.md

@@ -0,0 +1,5 @@
+---
+"agents": minor
+---
+
+Add the Web Channel (`agents/experimental/channels/web`) and its client (`agents/experimental/channels/web/client`), which connect browsers and terminals to a conversation over the agent's WebSockets: live transcript and turns, approvals, client tool results, and creating, forking, resetting, listing and following conversations. `WebSockets` gains `use` for protocol handlers that run before the configured ones.

packages/agents/package.json

@@ -397,6 +397,16 @@
       "import": "./dist/experimental/channels/telegram/index.js",
       "require": "./dist/experimental/channels/telegram/index.js"
     },
+    "./experimental/channels/web": {
+      "types": "./dist/experimental/channels/web/index.d.ts",
+      "import": "./dist/experimental/channels/web/index.js",
+      "require": "./dist/experimental/channels/web/index.js"
+    },
+    "./experimental/channels/web/client": {
+      "types": "./dist/experimental/channels/web/client.d.ts",
+      "import": "./dist/experimental/channels/web/client.js",
+      "require": "./dist/experimental/channels/web/client.js"
+    },
     "./tsconfig": "./agents.tsconfig.json",
     "./vite": {
       "types": "./dist/vite.d.ts",

packages/agents/scripts/build.ts

@@ -51,7 +51,9 @@ const entries = [
   "src/experimental/channels/index.ts",
   "src/experimental/channels/email/index.ts",
   "src/experimental/channels/slack/index.ts",
-  "src/experimental/channels/telegram/index.ts"
+  "src/experimental/channels/telegram/index.ts",
+  "src/experimental/channels/web/index.ts",
+  "src/experimental/channels/web/client.ts"
 ];
 
 for (const entry of entries) {

packages/agents/src/experimental/channels/__tests__/apply-chunks.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { applyChunks } from "../apply-chunks";
+
+describe("applyChunks", () => {
+  it("keeps provider metadata from a part's start and end", () => {
+    const message = applyChunks({ id: "m1", role: "assistant", parts: [] }, [
+      { type: "reasoning-start", id: "r", providerMetadata: { a: 1 } },
+      { type: "reasoning-delta", id: "r", delta: "thinking" },
+      { type: "reasoning-end", id: "r", providerMetadata: { b: 2 } },
+      { type: "text-start", id: "t" },
+      { type: "text-delta", id: "t", delta: "Hi" },
+      { type: "text-end", id: "t" }
+    ]);
+    expect(message.parts).toEqual([
+      { type: "reasoning", text: "thinking", providerMetadata: { a: 1, b: 2 } },
+      { type: "text", text: "Hi" }
+    ]);
+  });
+});

packages/agents/src/experimental/channels/__tests__/web-client.test.ts

@@ -0,0 +1,103 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { WebChannelClient } from "../web/client";
+import type { ServerFrame } from "../web/protocol";
+
+/** A WebSocket the test opens, feeds and inspects. */
+class FakeSocket extends EventTarget {
+  static readonly OPEN = 1;
+  static sockets: FakeSocket[] = [];
+  readyState = FakeSocket.OPEN;
+  readonly sent: unknown[] = [];
+
+  constructor(readonly url: string) {
+    super();
+    FakeSocket.sockets.push(this);
+  }
+
+  send(data: string): void {
+    this.sent.push(JSON.parse(data));
+  }
+
+  close(): void {
+    this.readyState = 3;
+    this.dispatchEvent(new Event("close"));
+  }
+
+  receive(frame: ServerFrame): void {
+    this.dispatchEvent(
+      new MessageEvent("message", { data: JSON.stringify(frame) })
+    );
+  }
+}
+
+const snapshot = (conversationId: string): ServerFrame => ({
+  type: "channels:snapshot",
+  conversationId,
+  you: { id: "alice" },
+  operations: ["conversation-create"],
+  messages: [],
+  turns: []
+});
+
+const latest = () => FakeSocket.sockets.at(-1) as FakeSocket;
+
+describe("WebChannelClient", () => {
+  beforeEach(() => {
+    FakeSocket.sockets = [];
+    vi.stubGlobal("WebSocket", FakeSocket);
+  });
+  afterEach(() => vi.unstubAllGlobals());
+
+  it("lists conversations, and keeps the latest list in its state", async () => {
+    const client = new WebChannelClient("ws://example.com/channels/room/main");
+    latest().receive(snapshot("main"));
+
+    const listed = client.listConversations();
+    const request = latest().sent.at(-1) as { requestId: string };
+    expect(request).toMatchObject({ type: "channels:list-conversations" });
+    const conversations = [
+      { id: "main", busy: false },
+      { id: "f1", parent: "main", busy: true }
+    ];
+    latest().receive({
+      type: "channels:conversations",
+      conversationId: "main",
+      requestId: request.requestId,
+      conversations
+    });
+    expect(await listed).toEqual(conversations);
+    expect(client.state.conversations).toEqual(conversations);
+
+    // A pushed list replaces it.
+    latest().receive({
+      type: "channels:conversations",
+      conversationId: "main",
+      conversations: conversations.slice(0, 1)
+    });
+    expect(client.state.conversations).toEqual(conversations.slice(0, 1));
+    client.close();
+  });
+
+  it("follows another conversation by reconnecting to its URL", async () => {
+    const client = new WebChannelClient("ws://example.com/channels/room/main");
+    const first = latest();
+    first.receive(snapshot("main"));
+    const unacked = client.send({ type: "conversation-create" });
+
+    client.follow("f1");
+    await expect(unacked).rejects.toThrow("Switched conversation");
+    expect(first.readyState).toBe(3);
+    expect(latest().url).toBe("ws://example.com/channels/room/f1");
+    expect(FakeSocket.sockets).toHaveLength(2);
+    expect(client.state.connected).toBe(false);
+
+    // Frames from the socket left behind are ignored.
+    first.receive(snapshot("main"));
+    latest().receive(snapshot("f1"));
+    expect(client.state).toMatchObject({
+      connected: true,
+      conversationId: "f1"
+    });
+    client.close();
+  });
+});

packages/agents/src/experimental/channels/apply-chunks.ts

@@ -0,0 +1,125 @@
+import type {
+  MessagePart,
+  ResponseChunk,
+  ToolPart,
+  TranscriptMessage
+} from "./protocol";
+
+/** Apply a response's chunks to the message it builds or extends. */
+export function applyChunks(
+  message: TranscriptMessage,
+  chunks: readonly ResponseChunk[]
+): TranscriptMessage {
+  const parts: MessagePart[] = message.parts.map((part) => ({ ...part }));
+  let metadata = message.metadata;
+  type TextPart = Extract<MessagePart, { type: "text" | "reasoning" }>;
+  const open = new Map<string, TextPart>();
+
+  const toolPart = (toolCallId: string) =>
+    parts.find(
+      (part): part is ToolPart =>
+        part.type === "tool" && part.toolCallId === toolCallId
+    );
+
+  for (const chunk of chunks) {
+    switch (chunk.type) {
+      case "text-start":
+      case "reasoning-start": {
+        const kind = chunk.type === "text-start" ? "text" : "reasoning";
+        const part: TextPart = {
+          type: kind,
+          text: "",
+          ...(chunk.providerMetadata !== undefined && {
+            providerMetadata: chunk.providerMetadata
+          })
+        };
+        open.set(`${kind}:${chunk.id}`, part);
+        parts.push(part);
+        break;
+      }
+      case "text-delta":
+      case "reasoning-delta": {
+        const kind = chunk.type === "text-delta" ? "text" : "reasoning";
+        const part = open.get(`${kind}:${chunk.id}`);
+        if (part) part.text += chunk.delta;
+        break;
+      }
+      case "text-end":
+      case "reasoning-end": {
+        const key = `${chunk.type.split("-")[0]}:${chunk.id}`;
+        const part = open.get(key);
+        if (part && chunk.providerMetadata !== undefined) {
+          part.providerMetadata = {
+            ...part.providerMetadata,
+            ...chunk.providerMetadata
+          };
+        }
+        open.delete(key);
+        break;
+      }
+      case "tool-input-start":
+      case "tool-input-available":
+      case "tool-input-error": {
+        const { type, ...call } = chunk;
+        const existing = toolPart(chunk.toolCallId);
+        const next: ToolPart = {
+          ...existing,
+          ...call,
+          type: "tool",
+          state:
+            type === "tool-input-start"
+              ? "input-streaming"
+              : type === "tool-input-available"
+                ? "input-available"
+                : "output-error"
+        };
+        if (existing) parts[parts.indexOf(existing)] = next;
+        else parts.push(next);
+        break;
+      }
+      case "tool-input-delta":
+        break;
+      case "tool-approval-request":
+      case "tool-output-available":
+      case "tool-output-error":
+      case "tool-output-denied": {
+        const part = toolPart(chunk.toolCallId);
+        if (!part) break;
+        if (chunk.type === "tool-approval-request") {
+          part.state = "approval-requested";
+          part.approval = { id: chunk.approvalId };
+        } else if (chunk.type === "tool-output-available") {
+          part.state = "output-available";
+          part.output = chunk.output;
+          part.preliminary = chunk.preliminary;
+        } else if (chunk.type === "tool-output-error") {
+          part.state = "output-error";
+          part.errorText = chunk.errorText;
+        } else {
+          part.state = "output-denied";
+        }
+        break;
+      }
+      case "data": {
+        if (chunk.transient) break;
+        const { transient: _transient, ...part } = chunk;
+        const index = parts.findIndex(
+          (p) =>
+            p.type === "data" &&
+            p.name === chunk.name &&
+            p.id !== undefined &&
+            p.id === chunk.id
+        );
+        if (index === -1) parts.push(part);
+        else parts[index] = part;
+        break;
+      }
+      case "metadata":
+        metadata = { ...metadata, ...chunk.metadata };
+        break;
+      default:
+        parts.push(chunk);
+    }
+  }
+  return { ...message, parts, ...(metadata && { metadata }) };
+}