@vellumai/assistant 0.8.10 → 0.8.11-staging.1

package/src/tools/browser/cdp-client/__tests__/factory.test.ts

@@ -5,7 +5,7 @@ import type { ToolContext } from "../../../types.js";
 import { CdpError } from "../errors.js";
 
 type FakeClient = {
-  kind: "extension" | "local" | "cdp-inspect";
+  kind: "extension" | "local" | "cdp-inspect" | "host-bridge";
   conversationId: string;
   send: ReturnType<typeof mock>;
   dispose: ReturnType<typeof mock>;
@@ -20,6 +20,15 @@ function makeFakeExtensionClient(conversationId: string): FakeClient {
   };
 }
 
+function makeFakeHostBridgeClient(conversationId: string): FakeClient {
+  return {
+    kind: "host-bridge",
+    conversationId,
+    send: mock(async () => ({ ok: true, via: "host-bridge" })),
+    dispose: mock(() => {}),
+  };
+}
+
 function makeFakeLocalClient(conversationId: string): FakeClient {
   return {
     kind: "local",
@@ -50,6 +59,17 @@ const createExtensionCdpClientMock = mock(
   },
 );
 
+const createHostBridgeCdpClientMock = mock(
+  (
+    _proxy: HostBrowserProxy,
+    conversationId: string,
+    _sourceActorPrincipalId?: string,
+  ) => {
+    const client = makeFakeHostBridgeClient(conversationId);
+    return client;
+  },
+);
+
 const createLocalCdpClientMock = mock((conversationId: string) => {
   const client = makeFakeLocalClient(conversationId);
   lastLocalClient = client;
@@ -86,12 +106,17 @@ const logDebugCalls: Array<{ args: unknown[] }> = [];
 // suite stubs out.
 import * as realCdpInspectClient from "../cdp-inspect-client.js";
 import * as realExtensionCdpClient from "../extension-cdp-client.js";
+import * as realHostBridgeCdpClient from "../host-bridge-cdp-client.js";
 import * as realLocalCdpClient from "../local-cdp-client.js";
 
 mock.module("../extension-cdp-client.js", () => ({
   ...realExtensionCdpClient,
   createExtensionCdpClient: createExtensionCdpClientMock,
 }));
+mock.module("../host-bridge-cdp-client.js", () => ({
+  ...realHostBridgeCdpClient,
+  createHostBridgeCdpClient: createHostBridgeCdpClientMock,
+}));
 mock.module("../local-cdp-client.js", () => ({
   ...realLocalCdpClient,
   createLocalCdpClient: createLocalCdpClientMock,
@@ -161,6 +186,10 @@ const {
   _getDesktopAutoCooldownSince,
   recordDesktopAutoCooldown,
   isDesktopAutoCooldownActive,
+  _resetHostBridgeCooldown,
+  _getHostBridgeCooldownSince,
+  recordHostBridgeCooldown,
+  isHostBridgeCooldownActive,
 } = await import("../factory.js");
 
 /**
@@ -210,17 +239,40 @@ function makeUnavailableProxy(): HostBrowserProxy {
   } as unknown as HostBrowserProxy;
 }
 
+/**
+ * Create a fake HostBrowserProxy with actor-scoped availability, mirroring
+ * the real implementation: with an actor, only that actor's clients count;
+ * without one, any client counts.
+ */
+function makeActorScopedProxy(opts: {
+  extensionActors: string[];
+  bridgeActors: string[];
+}): HostBrowserProxy {
+  const allActors = [...opts.extensionActors, ...opts.bridgeActors];
+  return {
+    request: mock(async () => ({})),
+    isAvailable: (actor?: string) =>
+      actor == null ? allActors.length > 0 : allActors.includes(actor),
+    hasExtensionClient: (actor?: string) =>
+      actor == null
+        ? opts.extensionActors.length > 0
+        : opts.extensionActors.includes(actor),
+  } as unknown as HostBrowserProxy;
+}
+
 describe("getCdpClient", () => {
   beforeEach(() => {
     createExtensionCdpClientMock.mockClear();
     createLocalCdpClientMock.mockClear();
     createCdpInspectClientMock.mockClear();
+    createHostBridgeCdpClientMock.mockClear();
     lastExtensionClient = undefined;
     lastLocalClient = undefined;
     lastCdpInspectClient = undefined;
     cdpInspectEnabled = false;
     desktopAutoConfig = { enabled: true, cooldownMs: 30_000 };
     _resetDesktopAutoCooldown();
+    _resetHostBridgeCooldown();
     logWarnCalls.length = 0;
     logDebugCalls.length = 0;
     mockSingletonProxy = null;
@@ -785,6 +837,7 @@ describe("buildCandidateList", () => {
     cdpInspectEnabled = false;
     desktopAutoConfig = { enabled: true, cooldownMs: 30_000 };
     _resetDesktopAutoCooldown();
+    _resetHostBridgeCooldown();
     mockSingletonProxy = null;
   });
 
@@ -816,10 +869,11 @@ describe("buildCandidateList", () => {
     expect(candidates[0].kind).toBe("local");
   });
 
-  test("excludes extension candidate when only macOS SSE bridge is connected", () => {
+  test("uses host-bridge candidate when only macOS SSE bridge is connected", () => {
     // isAvailable() = true but hasExtensionClient() = false: only macOS bridge.
-    // The macOS bridge routes through localhost:9222 on the host, so it must
-    // NOT be included under the "extension" candidate kind.
+    // The bridge gets its own first-class candidate kind — it must NOT be
+    // labelled "extension" (it routes raw CDP through localhost:9222 on the
+    // host and cannot serve Vellum.* pseudo-methods).
     const fakeProxy = makeMacosBridgeOnlyProxy();
     mockSingletonProxy = fakeProxy;
     const ctx = makeContext({
@@ -829,6 +883,180 @@ describe("buildCandidateList", () => {
     const candidates = buildCandidateList(ctx);
 
     expect(candidates.every((c) => c.kind !== "extension")).toBe(true);
+    expect(candidates[0].kind).toBe("host-bridge");
+    expect(candidates[candidates.length - 1].kind).toBe("local");
+  });
+
+  test("host-bridge candidate is absent when an extension is connected", () => {
+    mockSingletonProxy = makeAvailableProxy();
+    const ctx = makeContext({ conversationId: "candidates-ext-no-bridge" });
+
+    const candidates = buildCandidateList(ctx);
+
+    expect(candidates[0].kind).toBe("extension");
+    expect(candidates.every((c) => c.kind !== "host-bridge")).toBe(true);
+  });
+
+  test("host-bridge candidate is absent when the proxy is unavailable", () => {
+    mockSingletonProxy = makeUnavailableProxy();
+    const ctx = makeContext({ conversationId: "candidates-no-bridge" });
+
+    const candidates = buildCandidateList(ctx);
+
+    expect(candidates.every((c) => c.kind !== "host-bridge")).toBe(true);
+    expect(candidates[0].kind).toBe("local");
+  });
+
+  test("host-bridge candidate is skipped while the bridge cooldown is active", () => {
+    mockSingletonProxy = makeMacosBridgeOnlyProxy();
+    const ctx = makeContext({ conversationId: "candidates-bridge-cooldown" });
+
+    recordHostBridgeCooldown();
+    const candidates = buildCandidateList(ctx);
+
+    expect(candidates.every((c) => c.kind !== "host-bridge")).toBe(true);
+
+    _resetHostBridgeCooldown();
+    const after = buildCandidateList(ctx);
+    expect(after[0].kind).toBe("host-bridge");
+  });
+
+  test("host-bridge cooldown is independent of the desktop-auto cooldown", () => {
+    mockSingletonProxy = makeMacosBridgeOnlyProxy();
+    const ctx = makeContext({
+      conversationId: "candidates-bridge-cooldown-independent",
+      transportInterface: "macos",
+    });
+
+    recordDesktopAutoCooldown();
+    const candidates = buildCandidateList(ctx);
+
+    // Desktop-auto cooldown suppresses cdp-inspect but not the bridge.
+    expect(candidates[0].kind).toBe("host-bridge");
+    expect(candidates.every((c) => c.kind !== "cdp-inspect")).toBe(true);
+    expect(isHostBridgeCooldownActive(30_000)).toBe(false);
+  });
+
+  test("host-bridge cooldown is scoped per actor", () => {
+    // One actor's missing debug port must not suppress another actor's
+    // only route to their own Chrome on a multi-actor cloud daemon.
+    mockSingletonProxy = makeActorScopedProxy({
+      extensionActors: [],
+      bridgeActors: ["actor-a", "actor-b"],
+    });
+
+    recordHostBridgeCooldown("actor-a");
+
+    const forA = buildCandidateList(
+      makeContext({
+        conversationId: "cooldown-actor-a",
+        sourceActorPrincipalId: "actor-a",
+      }),
+    );
+    expect(forA.every((c) => c.kind !== "host-bridge")).toBe(true);
+
+    const forB = buildCandidateList(
+      makeContext({
+        conversationId: "cooldown-actor-b",
+        sourceActorPrincipalId: "actor-b",
+      }),
+    );
+    expect(forB[0].kind).toBe("host-bridge");
+
+    // Actor-scoped cooldowns do not leak into the no-actor default slot.
+    expect(isHostBridgeCooldownActive(30_000)).toBe(false);
+    expect(isHostBridgeCooldownActive(30_000, "actor-a")).toBe(true);
+    expect(isHostBridgeCooldownActive(30_000, "actor-b")).toBe(false);
+  });
+
+
+  test("ordering on a macOS turn with bridge only: host-bridge > cdp-inspect > local", () => {
+    mockSingletonProxy = makeMacosBridgeOnlyProxy();
+    const ctx = makeContext({
+      conversationId: "candidates-bridge-order",
+      transportInterface: "macos",
+    });
+
+    const candidates = buildCandidateList(ctx);
+
+    expect(candidates.map((c) => c.kind)).toEqual([
+      "host-bridge",
+      "cdp-inspect",
+      "local",
+    ]);
+  });
+
+  test("host-bridge create() threads proxy + actor and never reads pinned tabs", () => {
+    const fakeProxy = makeMacosBridgeOnlyProxy();
+    mockSingletonProxy = fakeProxy;
+    const ctx = makeContext({
+      conversationId: "candidates-bridge-create",
+      sourceActorPrincipalId: "actor-1",
+    });
+
+    const candidates = buildCandidateList(ctx);
+    expect(candidates[0].kind).toBe("host-bridge");
+    candidates[0].create();
+
+    expect(createHostBridgeCdpClientMock).toHaveBeenCalledWith(
+      fakeProxy,
+      "candidates-bridge-create",
+      "actor-1",
+    );
+  });
+
+  test("multi-actor: another actor's extension does not select the extension candidate", () => {
+    // Actor A has an extension; actor B has only the bridge. B's
+    // conversation must get the host-bridge candidate, not an
+    // extension-labelled client that the proxy would route to B's bridge.
+    mockSingletonProxy = makeActorScopedProxy({
+      extensionActors: ["actor-a"],
+      bridgeActors: ["actor-b"],
+    });
+    const ctx = makeContext({
+      conversationId: "candidates-multi-actor-b",
+      sourceActorPrincipalId: "actor-b",
+    });
+
+    const candidates = buildCandidateList(ctx);
+
+    expect(candidates[0].kind).toBe("host-bridge");
+    expect(candidates.every((c) => c.kind !== "extension")).toBe(true);
+  });
+
+  test("multi-actor: the extension owner still gets the extension candidate", () => {
+    mockSingletonProxy = makeActorScopedProxy({
+      extensionActors: ["actor-a"],
+      bridgeActors: ["actor-b"],
+    });
+    const ctx = makeContext({
+      conversationId: "candidates-multi-actor-a",
+      sourceActorPrincipalId: "actor-a",
+    });
+
+    const candidates = buildCandidateList(ctx);
+
+    expect(candidates[0].kind).toBe("extension");
+    expect(candidates.every((c) => c.kind !== "host-bridge")).toBe(true);
+  });
+
+  test("multi-actor: actor with no clients at all gets neither proxy candidate", () => {
+    mockSingletonProxy = makeActorScopedProxy({
+      extensionActors: ["actor-a"],
+      bridgeActors: ["actor-b"],
+    });
+    const ctx = makeContext({
+      conversationId: "candidates-multi-actor-c",
+      sourceActorPrincipalId: "actor-c",
+    });
+
+    const candidates = buildCandidateList(ctx);
+
+    expect(
+      candidates.every(
+        (c) => c.kind !== "extension" && c.kind !== "host-bridge",
+      ),
+    ).toBe(true);
     expect(candidates[candidates.length - 1].kind).toBe("local");
   });
 
@@ -931,12 +1159,14 @@ describe("buildChainedClient failover", () => {
     createExtensionCdpClientMock.mockClear();
     createLocalCdpClientMock.mockClear();
     createCdpInspectClientMock.mockClear();
+    createHostBridgeCdpClientMock.mockClear();
     lastExtensionClient = undefined;
     lastLocalClient = undefined;
     lastCdpInspectClient = undefined;
     cdpInspectEnabled = false;
     desktopAutoConfig = { enabled: true, cooldownMs: 30_000 };
     _resetDesktopAutoCooldown();
+    _resetHostBridgeCooldown();
     logWarnCalls.length = 0;
     logDebugCalls.length = 0;
     mockSingletonProxy = null;
@@ -1030,6 +1260,94 @@ describe("buildChainedClient failover", () => {
     expect(createLocalCdpClientMock).toHaveBeenCalledTimes(1);
   });
 
+  test("fails over from host-bridge to local and records the bridge cooldown", async () => {
+    mockSingletonProxy = makeMacosBridgeOnlyProxy();
+
+    // Bridge fails like Chrome without a debug port: structured
+    // "unreachable" envelope → transport_error.
+    createHostBridgeCdpClientMock.mockImplementationOnce(
+      (_proxy: HostBrowserProxy, conversationId: string) => {
+        const c = makeFakeHostBridgeClient(conversationId);
+        c.send = mock(async () => {
+          throw new CdpError(
+            "transport_error",
+            "HTTP 404 from http://localhost:9222/json/list",
+            { cdpMethod: "Page.navigate" },
+          );
+        });
+        return c;
+      },
+    );
+
+    const ctx = makeContext({ conversationId: "failover-bridge-to-local" });
+
+    const client = getCdpClient(ctx);
+    const result = await client.send<{ ok: boolean; via: string }>(
+      "Page.navigate",
+      { url: "https://example.com" },
+    );
+
+    expect(result).toEqual({ ok: true, via: "local" });
+    expect(createHostBridgeCdpClientMock).toHaveBeenCalledTimes(1);
+    expect(createLocalCdpClientMock).toHaveBeenCalledTimes(1);
+    // Cooldown was recorded so the next candidate list skips the bridge.
+    expect(_getHostBridgeCooldownSince()).toBeGreaterThan(0);
+    expect(_getDesktopAutoCooldownSince()).toBe(0);
+    const after = buildCandidateList(ctx);
+    expect(after.every((c) => c.kind !== "host-bridge")).toBe(true);
+  });
+
+  test("host-bridge failover records the cooldown under the failing actor only", async () => {
+    mockSingletonProxy = makeActorScopedProxy({
+      extensionActors: [],
+      bridgeActors: ["actor-a", "actor-b"],
+    });
+    createHostBridgeCdpClientMock.mockImplementationOnce(
+      (_proxy: HostBrowserProxy, conversationId: string) => {
+        const c = makeFakeHostBridgeClient(conversationId);
+        c.send = mock(async () => {
+          throw new CdpError(
+            "transport_error",
+            "HTTP 404 from http://localhost:9222/json/list",
+            { cdpMethod: "Page.navigate" },
+          );
+        });
+        return c;
+      },
+    );
+
+    const client = getCdpClient(
+      makeContext({
+        conversationId: "cooldown-record-actor-a",
+        sourceActorPrincipalId: "actor-a",
+      }),
+    );
+    const result = await client.send<{ ok: boolean; via: string }>(
+      "Page.navigate",
+      { url: "https://example.com" },
+    );
+
+    expect(result).toEqual({ ok: true, via: "local" });
+    expect(_getHostBridgeCooldownSince("actor-a")).toBeGreaterThan(0);
+    expect(_getHostBridgeCooldownSince("actor-b")).toBe(0);
+    expect(_getHostBridgeCooldownSince()).toBe(0);
+  });
+
+  test("sticky host-bridge client rejects tab operations with a clear error", async () => {
+    mockSingletonProxy = makeMacosBridgeOnlyProxy();
+    const ctx = makeContext({ conversationId: "bridge-tab-ops" });
+
+    const client = getCdpClient(ctx);
+    await client.send("Page.navigate", { url: "https://example.com" });
+    expect(client.kind).toBe("host-bridge");
+
+    // The fake bridge client has no listTabs/selectTab/closeTab, so the
+    // chained client surfaces the not-supported transport_error.
+    await expect(client.listTabs()).rejects.toThrow(
+      "extension backend required",
+    );
+  });
+
   test("does NOT fail over on cdp_error -- propagates immediately", async () => {
     cdpInspectEnabled = true;
     const fakeProxy = makeAvailableProxy();
@@ -1245,12 +1563,14 @@ describe("desktop-auto cdp-inspect (macOS)", () => {
     createExtensionCdpClientMock.mockClear();
     createLocalCdpClientMock.mockClear();
     createCdpInspectClientMock.mockClear();
+    createHostBridgeCdpClientMock.mockClear();
     lastExtensionClient = undefined;
     lastLocalClient = undefined;
     lastCdpInspectClient = undefined;
     cdpInspectEnabled = false;
     desktopAutoConfig = { enabled: true, cooldownMs: 30_000 };
     _resetDesktopAutoCooldown();
+    _resetHostBridgeCooldown();
     logWarnCalls.length = 0;
     logDebugCalls.length = 0;
     mockSingletonProxy = null;
@@ -1597,12 +1917,14 @@ describe("pinned-mode selection", () => {
     createExtensionCdpClientMock.mockClear();
     createLocalCdpClientMock.mockClear();
     createCdpInspectClientMock.mockClear();
+    createHostBridgeCdpClientMock.mockClear();
     lastExtensionClient = undefined;
     lastLocalClient = undefined;
     lastCdpInspectClient = undefined;
     cdpInspectEnabled = false;
     desktopAutoConfig = { enabled: true, cooldownMs: 30_000 };
     _resetDesktopAutoCooldown();
+    _resetHostBridgeCooldown();
     logWarnCalls.length = 0;
     logDebugCalls.length = 0;
     mockSingletonProxy = null;
@@ -1811,12 +2133,14 @@ describe("buildPinnedCandidateList", () => {
     createExtensionCdpClientMock.mockClear();
     createLocalCdpClientMock.mockClear();
     createCdpInspectClientMock.mockClear();
+    createHostBridgeCdpClientMock.mockClear();
     lastExtensionClient = undefined;
     lastLocalClient = undefined;
     lastCdpInspectClient = undefined;
     cdpInspectEnabled = false;
     desktopAutoConfig = { enabled: true, cooldownMs: 30_000 };
     _resetDesktopAutoCooldown();
+    _resetHostBridgeCooldown();
     mockSingletonProxy = null;
   });
 
@@ -1892,6 +2216,54 @@ describe("buildPinnedCandidateList", () => {
       expect(cdpErr.message).toContain("no Chrome Extension connected");
     }
   });
+
+  test("host-bridge mode produces single host-bridge candidate when bridge-only", () => {
+    mockSingletonProxy = makeMacosBridgeOnlyProxy();
+    const ctx = makeContext({ conversationId: "bpl-bridge" });
+
+    const candidates = buildPinnedCandidateList(ctx, "host-bridge");
+
+    expect(candidates).toHaveLength(1);
+    expect(candidates[0].kind).toBe("host-bridge");
+    expect(candidates[0].reason).toContain("pinned mode: host-bridge");
+  });
+
+  test("host-bridge mode throws with diagnostics when proxy is unavailable", () => {
+    mockSingletonProxy = makeUnavailableProxy();
+    const ctx = makeContext({ conversationId: "bpl-bridge-absent" });
+
+    try {
+      buildPinnedCandidateList(ctx, "host-bridge");
+      expect(true).toBe(false); // should not reach
+    } catch (err) {
+      expect(err).toBeInstanceOf(CdpError);
+      const cdpErr = err as CdpError;
+      expect(cdpErr.code).toBe("transport_error");
+      expect(cdpErr.attemptDiagnostics![0]).toMatchObject({
+        candidateKind: "host-bridge",
+        stage: "candidate_selection",
+      });
+    }
+  });
+
+  test("host-bridge mode throws when an extension has since connected", () => {
+    // The sticky memo says host-bridge but a Chrome Extension is now
+    // available. Throwing trips acquireCdpClientWithMode's sticky-fallback
+    // retry, which clears the memo and re-runs auto so the conversation
+    // upgrades to the extension candidate.
+    mockSingletonProxy = makeAvailableProxy();
+    const ctx = makeContext({ conversationId: "bpl-bridge-ext-upgrade" });
+
+    try {
+      buildPinnedCandidateList(ctx, "host-bridge");
+      expect(true).toBe(false); // should not reach
+    } catch (err) {
+      expect(err).toBeInstanceOf(CdpError);
+      expect((err as CdpError).message).toContain(
+        "a Chrome Extension is now connected",
+      );
+    }
+  });
 });
 
 // ── Attempt diagnostics & fallback log tests ─────────────────────────────
@@ -1901,12 +2273,14 @@ describe("attempt diagnostics", () => {
     createExtensionCdpClientMock.mockClear();
     createLocalCdpClientMock.mockClear();
     createCdpInspectClientMock.mockClear();
+    createHostBridgeCdpClientMock.mockClear();
     lastExtensionClient = undefined;
     lastLocalClient = undefined;
     lastCdpInspectClient = undefined;
     cdpInspectEnabled = false;
     desktopAutoConfig = { enabled: true, cooldownMs: 30_000 };
     _resetDesktopAutoCooldown();
+    _resetHostBridgeCooldown();
     logWarnCalls.length = 0;
     logDebugCalls.length = 0;
     mockSingletonProxy = null;
@@ -2300,12 +2674,14 @@ describe("macOS host-browser proxy without extension registry", () => {
     createExtensionCdpClientMock.mockClear();
     createLocalCdpClientMock.mockClear();
     createCdpInspectClientMock.mockClear();
+    createHostBridgeCdpClientMock.mockClear();
     lastExtensionClient = undefined;
     lastLocalClient = undefined;
     lastCdpInspectClient = undefined;
     cdpInspectEnabled = false;
     desktopAutoConfig = { enabled: true, cooldownMs: 30_000 };
     _resetDesktopAutoCooldown();
+    _resetHostBridgeCooldown();
     logWarnCalls.length = 0;
     logDebugCalls.length = 0;
     mockSingletonProxy = null;

package/src/tools/browser/cdp-client/__tests__/host-bridge-cdp-client.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, mock, test } from "bun:test";
+
+import type { HostBrowserProxy } from "../../../../daemon/host-browser-proxy.js";
+import { CdpError } from "../errors.js";
+import {
+  createHostBridgeCdpClient,
+  HostBridgeCdpClient,
+} from "../host-bridge-cdp-client.js";
+
+type ProxyResult = { content: string; isError: boolean };
+
+function fakeProxy(
+  handler: (
+    input: unknown,
+    conversationId: string,
+    signal?: AbortSignal,
+  ) => Promise<ProxyResult> | ProxyResult,
+): {
+  proxy: HostBrowserProxy;
+  request: ReturnType<typeof mock>;
+} {
+  const request = mock(
+    async (
+      input: unknown,
+      conversationId: string,
+      signal?: AbortSignal,
+    ): Promise<ProxyResult> => handler(input, conversationId, signal),
+  );
+  const proxy = { request } as unknown as HostBrowserProxy;
+  return { proxy, request };
+}
+
+describe("HostBridgeCdpClient", () => {
+  test("kind is 'host-bridge' and exposes conversationId", () => {
+    const { proxy } = fakeProxy(async () => ({
+      content: "{}",
+      isError: false,
+    }));
+    const client = createHostBridgeCdpClient(proxy, "conv-bridge");
+    expect(client).toBeInstanceOf(HostBridgeCdpClient);
+    expect(client.kind).toBe("host-bridge");
+    expect(client.conversationId).toBe("conv-bridge");
+  });
+
+  test("send forwards raw CDP with no cdpSessionId or targetClientId", async () => {
+    const { proxy, request } = fakeProxy(async () => ({
+      content: JSON.stringify({ frameId: "frame-1" }),
+      isError: false,
+    }));
+
+    const client = createHostBridgeCdpClient(proxy, "conv-1", "actor-1");
+    const result = await client.send<{ frameId: string }>("Page.navigate", {
+      url: "https://example.com/",
+    });
+
+    expect(result).toEqual({ frameId: "frame-1" });
+    expect(request).toHaveBeenCalledTimes(1);
+    const call = request.mock.calls[0];
+    expect(call?.[0]).toEqual({
+      cdpMethod: "Page.navigate",
+      cdpParams: { url: "https://example.com/" },
+      cdpSessionId: undefined,
+    });
+    expect(call?.[1]).toBe("conv-1");
+    // sourceActorPrincipalId threads through; targetClientId is never set.
+    expect(call?.[3]).toBe("actor-1");
+    expect(call?.[4]).toBeUndefined();
+  });
+
+  test("bridge 'unreachable' envelope classifies as transport_error (failover-eligible)", async () => {
+    const { proxy } = fakeProxy(async () => ({
+      content: JSON.stringify({
+        code: "unreachable",
+        message: "HTTP 404 from http://localhost:9222/json/list",
+      }),
+      isError: true,
+    }));
+
+    const client = createHostBridgeCdpClient(proxy, "conv-err");
+    try {
+      await client.send("Page.captureScreenshot", {});
+      expect(true).toBe(false); // should not reach
+    } catch (err) {
+      expect(err).toBeInstanceOf(CdpError);
+      expect((err as CdpError).code).toBe("transport_error");
+      expect((err as CdpError).message).toContain("HTTP 404");
+    }
+  });
+
+  test.each(["listTabs", "selectTab", "closeTab"] as const)(
+    "%s throws transport_error locally without touching the proxy",
+    async (method) => {
+      const { proxy, request } = fakeProxy(async () => ({
+        content: "{}",
+        isError: false,
+      }));
+      const client = createHostBridgeCdpClient(proxy, "conv-tabs");
+
+      const call =
+        method === "listTabs" ? client.listTabs() : client[method](1);
+      await expect(call).rejects.toThrow(
+        `${method} is not supported by the host-bridge backend (extension backend required)`,
+      );
+      expect(request).not.toHaveBeenCalled();
+    },
+  );
+});

package/src/tools/browser/cdp-client/__tests__/types.test.ts

@@ -79,7 +79,12 @@ describe("cdp-client re-exports", () => {
   });
 
   test("ScopedCdpClient exposes kind and conversationId", () => {
-    const kinds: CdpClientKind[] = ["local", "extension", "cdp-inspect"];
+    const kinds: CdpClientKind[] = [
+      "local",
+      "extension",
+      "cdp-inspect",
+      "host-bridge",
+    ];
     for (const kind of kinds) {
       const scoped: ScopedCdpClient = {
         kind,