@vellumai/assistant 0.8.3 → 0.8.5

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

@@ -0,0 +1,402 @@
+/**
+ * Tests that listTabs, selectTab, and closeTab are properly forwarded through
+ * the real buildChainedClient wrapper.
+ *
+ * Per the test-flat-mocks-trap rule, these tests use the REAL buildChainedClient
+ * function with a mock candidate — NOT a flat fake that has the methods defined
+ * directly on the scoped client.
+ */
+
+import { describe, expect, mock, test } from "bun:test";
+
+import type { BrowserBackend, CdpCommand, CdpResult } from "../../../../browser-session/types.js";
+import { CdpError } from "../errors.js";
+import type { BackendCandidate, CdpClient, TabInfo } from "../types.js";
+
+// Import buildChainedClient directly. Since this test file does not mock
+// any of factory.ts's imports, we import directly.
+const { buildChainedClient } = await import("../factory.js");
+
+// ── Helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Create a BrowserBackend that delegates CDP sends through a CdpClient.
+ * This is the real wiring that factory.ts uses — the backend wraps the
+ * client's send method via dispatchThroughClient.
+ */
+function makeBackendFromClient(client: CdpClient, kind: "extension" | "local" | "cdp-inspect"): BrowserBackend {
+  return {
+    kind,
+    isAvailable: () => true,
+    send: async (command: CdpCommand, signal?: AbortSignal): Promise<CdpResult> => {
+      try {
+        const result = await client.send(command.method, command.params, signal);
+        return { result };
+      } catch (err) {
+        if (err instanceof CdpError) {
+          return {
+            error: { code: -1, message: err.message, data: err },
+          };
+        }
+        throw err;
+      }
+    },
+    dispose: () => client.dispose(),
+  };
+}
+
+interface FakeClientWithTabMethods extends CdpClient {
+  kind: "extension";
+  conversationId: string;
+  listTabsMock: ReturnType<typeof mock>;
+  selectTabMock: ReturnType<typeof mock>;
+  closeTabMock: ReturnType<typeof mock>;
+}
+
+function makeFakeExtensionClientWithTabMethods(
+  conversationId: string,
+): FakeClientWithTabMethods {
+  const listTabsMock = mock(async (): Promise<TabInfo[]> => [
+    {
+      tabId: 1,
+      windowId: 10,
+      url: "https://example.com",
+      title: "Example",
+      active: true,
+      pinned: false,
+    },
+  ]);
+  const selectTabMock = mock(async (_tabId: number) => ({
+    tabId: 42,
+    windowId: 10,
+    url: "https://example.com",
+    title: "Example",
+    clientId: "clientA",
+  }));
+  const closeTabMock = mock(async (_tabId: number) => ({
+    closed: true as const,
+    tabId: 99,
+  }));
+
+  return {
+    kind: "extension",
+    conversationId,
+    listTabsMock,
+    selectTabMock,
+    closeTabMock,
+    send: mock(async () => ({ ok: true })) as unknown as CdpClient["send"],
+    dispose: mock(() => {}),
+    listTabs: listTabsMock,
+    selectTab: selectTabMock,
+    closeTab: closeTabMock,
+  };
+}
+
+/**
+ * Build a BackendCandidate that wraps a fake extension client with tab methods.
+ */
+function makeCandidateFromClient(
+  conversationId: string,
+  fakeClient: CdpClient,
+  kind: "extension" | "local" | "cdp-inspect",
+): BackendCandidate {
+  return {
+    kind,
+    reason: `test ${kind} client`,
+    create() {
+      return {
+        client: fakeClient,
+        backend: makeBackendFromClient(fakeClient, kind),
+      };
+    },
+  };
+}
+
+// ── Helpers for fresh-client (pre-sticky) tests ───────────────────────
+
+/**
+ * A fake extension client whose `send` method returns Vellum.* pseudo-responses
+ * so that fresh-client tab calls can succeed without a prior `send("Runtime.*")`.
+ * This simulates how the real ExtensionCdpClient handles Vellum.listTabs etc.
+ * through the dispatcher before chrome.debugger.sendCommand.
+ */
+function makeFakeExtensionClientForFreshPath(conversationId: string) {
+  return {
+    kind: "extension" as const,
+    conversationId,
+    send: mock(
+      async (method: string, params?: Record<string, unknown>): Promise<unknown> => {
+        if (method === "Vellum.listTabs") {
+          return {
+            tabs: [
+              {
+                tabId: 1,
+                windowId: 10,
+                url: "https://example.com",
+                title: "Example",
+                active: true,
+                pinned: false,
+              },
+            ],
+          };
+        }
+        if (method === "Vellum.selectTab") {
+          return {
+            tabId: params?.tabId,
+            windowId: 10,
+            url: "https://example.com",
+            title: "Example",
+            clientId: "clientA",
+          };
+        }
+        if (method === "Vellum.closeTab") {
+          return { closed: true, tabId: params?.tabId };
+        }
+        return {};
+      },
+    ) as unknown as CdpClient["send"],
+    dispose: mock(() => {}),
+    // These must be present so active?.client.listTabs etc. check passes
+    listTabs: mock(async (): Promise<TabInfo[]> => []),
+    selectTab: mock(async (_tabId: number) => ({
+      tabId: _tabId,
+      windowId: 10,
+      url: "https://example.com",
+      title: "Example",
+      clientId: "clientA",
+    })),
+    closeTab: mock(async (_tabId: number) => ({
+      closed: true as const,
+      tabId: _tabId,
+    })),
+  };
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────
+
+describe("buildChainedClient — tab management methods", () => {
+  test("listTabs is forwarded to the underlying client after backend becomes sticky", async () => {
+    const conversationId = "conv-tabs-list";
+    const fakeClient = makeFakeExtensionClientWithTabMethods(conversationId);
+    const candidate = makeCandidateFromClient(conversationId, fakeClient, "extension");
+
+    const scoped = buildChainedClient(conversationId, [candidate]);
+
+    // Establish sticky by sending a command first
+    await scoped.send("Runtime.evaluate", {});
+
+    const tabs = await scoped.listTabs();
+    expect(tabs).toHaveLength(1);
+    expect(tabs[0].tabId).toBe(1);
+    expect(tabs[0].active).toBe(true);
+    expect(fakeClient.listTabsMock).toHaveBeenCalledTimes(1);
+
+    scoped.dispose();
+  });
+
+  test("selectTab is forwarded to the underlying client", async () => {
+    const conversationId = "conv-tabs-select";
+    const fakeClient = makeFakeExtensionClientWithTabMethods(conversationId);
+    const candidate = makeCandidateFromClient(conversationId, fakeClient, "extension");
+
+    const scoped = buildChainedClient(conversationId, [candidate]);
+
+    // Establish sticky
+    await scoped.send("Runtime.evaluate", {});
+
+    const result = await scoped.selectTab(42);
+    expect(result.tabId).toBe(42);
+    expect(result.clientId).toBe("clientA");
+    expect(fakeClient.selectTabMock).toHaveBeenCalledWith(42);
+
+    scoped.dispose();
+  });
+
+  test("closeTab is forwarded to the underlying client", async () => {
+    const conversationId = "conv-tabs-close";
+    const fakeClient = makeFakeExtensionClientWithTabMethods(conversationId);
+    const candidate = makeCandidateFromClient(conversationId, fakeClient, "extension");
+
+    const scoped = buildChainedClient(conversationId, [candidate]);
+
+    // Establish sticky
+    await scoped.send("Runtime.evaluate", {});
+
+    const result = await scoped.closeTab(99);
+    expect(result.closed).toBe(true);
+    expect(result.tabId).toBe(99);
+    expect(fakeClient.closeTabMock).toHaveBeenCalledWith(99);
+
+    scoped.dispose();
+  });
+
+  test("listTabs throws transport_error when backend does not support it", async () => {
+    const conversationId = "conv-tabs-no-list";
+    // A local client without listTabs/selectTab/closeTab
+    const noTabsClient: CdpClient & {
+      kind: "local";
+      conversationId: string;
+    } = {
+      kind: "local",
+      conversationId,
+      send: mock(async () => ({})) as unknown as CdpClient["send"],
+      dispose: mock(() => {}),
+    };
+    const candidate = makeCandidateFromClient(
+      conversationId,
+      noTabsClient,
+      "local",
+    );
+
+    const scoped = buildChainedClient(conversationId, [candidate]);
+
+    // Establish sticky
+    await scoped.send("Runtime.evaluate", {});
+
+    let caught: unknown;
+    try {
+      await scoped.listTabs();
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(CdpError);
+    expect((caught as CdpError).code).toBe("transport_error");
+
+    scoped.dispose();
+  });
+
+  test("selectTab throws transport_error when backend does not support it", async () => {
+    const conversationId = "conv-tabs-no-select";
+    const noTabsClient: CdpClient & {
+      kind: "local";
+      conversationId: string;
+    } = {
+      kind: "local",
+      conversationId,
+      send: mock(async () => ({})) as unknown as CdpClient["send"],
+      dispose: mock(() => {}),
+    };
+    const candidate = makeCandidateFromClient(
+      conversationId,
+      noTabsClient,
+      "local",
+    );
+
+    const scoped = buildChainedClient(conversationId, [candidate]);
+
+    // Establish sticky
+    await scoped.send("Runtime.evaluate", {});
+
+    let caught: unknown;
+    try {
+      await scoped.selectTab(42);
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(CdpError);
+    expect((caught as CdpError).code).toBe("transport_error");
+
+    scoped.dispose();
+  });
+
+  test("closeTab throws transport_error when backend does not support it", async () => {
+    const conversationId = "conv-tabs-no-close";
+    const noTabsClient: CdpClient & {
+      kind: "local";
+      conversationId: string;
+    } = {
+      kind: "local",
+      conversationId,
+      send: mock(async () => ({})) as unknown as CdpClient["send"],
+      dispose: mock(() => {}),
+    };
+    const candidate = makeCandidateFromClient(
+      conversationId,
+      noTabsClient,
+      "local",
+    );
+
+    const scoped = buildChainedClient(conversationId, [candidate]);
+
+    // Establish sticky
+    await scoped.send("Runtime.evaluate", {});
+
+    let caught: unknown;
+    try {
+      await scoped.closeTab(77);
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(CdpError);
+    expect((caught as CdpError).code).toBe("transport_error");
+
+    scoped.dispose();
+  });
+});
+
+describe("buildChainedClient — fresh-client tab calls (no prior send)", () => {
+  test("listTabs on a fresh client triggers failover walk and returns tabs", async () => {
+    const conversationId = "conv-fresh-list";
+    const fakeClient = makeFakeExtensionClientForFreshPath(conversationId);
+    const candidate = makeCandidateFromClient(conversationId, fakeClient, "extension");
+    const scoped = buildChainedClient(conversationId, [candidate]);
+
+    // Call listTabs WITHOUT establishing sticky — this is the production scenario
+    const tabs = await scoped.listTabs();
+    expect(tabs).toHaveLength(1);
+    expect(tabs[0].tabId).toBe(1);
+    expect(tabs[0].active).toBe(true);
+
+    scoped.dispose();
+  });
+
+  test("selectTab on a fresh client triggers failover walk and returns tab info", async () => {
+    const conversationId = "conv-fresh-select";
+    const fakeClient = makeFakeExtensionClientForFreshPath(conversationId);
+    const candidate = makeCandidateFromClient(conversationId, fakeClient, "extension");
+    const scoped = buildChainedClient(conversationId, [candidate]);
+
+    const result = await scoped.selectTab(42);
+    expect(result.tabId).toBe(42);
+    expect(result.clientId).toBe("clientA");
+
+    scoped.dispose();
+  });
+
+  test("closeTab on a fresh client triggers failover walk and returns closed status", async () => {
+    const conversationId = "conv-fresh-close";
+    const fakeClient = makeFakeExtensionClientForFreshPath(conversationId);
+    const candidate = makeCandidateFromClient(conversationId, fakeClient, "extension");
+    const scoped = buildChainedClient(conversationId, [candidate]);
+
+    const result = await scoped.closeTab(99);
+    expect(result.closed).toBe(true);
+    expect(result.tabId).toBe(99);
+
+    scoped.dispose();
+  });
+
+  test("listTabs on fresh non-extension client throws transport_error after sticky established", async () => {
+    const conversationId = "conv-fresh-no-list";
+    const noTabsClient: CdpClient & { kind: "local"; conversationId: string } = {
+      kind: "local",
+      conversationId,
+      send: mock(async () => ({})) as unknown as CdpClient["send"],
+      dispose: mock(() => {}),
+    };
+    const candidate = makeCandidateFromClient(conversationId, noTabsClient, "local");
+    const scoped = buildChainedClient(conversationId, [candidate]);
+
+    // No prior send — fresh client, non-extension backend
+    let caught: unknown;
+    try {
+      await scoped.listTabs();
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(CdpError);
+    expect((caught as CdpError).code).toBe("transport_error");
+
+    scoped.dispose();
+  });
+});

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

@@ -2382,4 +2382,32 @@ describe("macOS host-browser proxy without extension registry", () => {
     );
     expect(result).toEqual({ ok: true, via: "extension" });
   });
+  test("setCdpSessionId is forwarded to the underlying client through buildChainedClient", async () => {
+    // This test exercises the real chained-client path that integrates
+    // the extension CdpClient. Without it, the test suite would only ever
+    // instantiate getCdpClient(), which returns the scopedClient directly.
+    // buildChainedClient (used by the navigator executor) wraps that
+    // client and must forward setCdpSessionId calls to the underlying
+    // extension client — otherwise --new-tab would silently fail to
+    // re-target CDP commands.
+    const fakeProxy = makeAvailableProxy();
+    mockSingletonProxy = fakeProxy;
+    const ctx = makeContext({ conversationId: "set-session-id-test" });
+    const client = getCdpClient(ctx);
+    // The scopedClient should expose setCdpSessionId (which it didn't
+    // before the fix).
+    expect(typeof client.setCdpSessionId).toBe("function");
+    // Call it; it should reach the underlying extension client without error.
+    // (The fake client's setCdpSessionId is a no-op in this test, but in
+    // production ExtensionCdpClient.setCdpSessionId updates cdpSessionId to
+    // re-target follow-on commands at a specific tab.)
+    const newTabId = "12345";
+    client.setCdpSessionId(newTabId);
+    // Verify the client is still functional after the session ID call.
+    const result = await client.send<{ ok: boolean; via: string }>(
+      "Page.navigate",
+      { url: "https://example.com" },
+    );
+    expect(result).toEqual({ ok: true, via: "extension" });
+  });
 });

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

@@ -88,6 +88,10 @@ describe("cdp-client re-exports", () => {
           throw new CdpError("disposed", "stub");
         },
         dispose: () => {},
+        setCdpSessionId: () => {},
+        listTabs: async () => [],
+        selectTab: async (_tabId: number) => ({ tabId: _tabId }),
+        closeTab: async (_tabId: number) => ({ closed: true as const, tabId: _tabId }),
       };
       expect(scoped.kind).toBe(kind);
       expect(scoped.conversationId).toBe("conv-123");

package/src/tools/browser/cdp-client/cdp-inspect-client.ts

@@ -700,6 +700,28 @@ export class CdpInspectClient implements ScopedCdpClient {
     }
   }
 
+  /**
+   * CdpInspectClient doesn't support re-targeting to a specific tab/session.
+   * It connects directly to a remote CDP endpoint, which manages targets
+   * globally. This method is a no-op to satisfy the {@link ScopedCdpClient}
+   * interface.
+   */
+  setCdpSessionId(): void {
+    // no-op
+  }
+
+  async listTabs(): Promise<never> {
+    throw new CdpError("transport_error", "listTabs is not supported by the cdp-inspect backend (extension backend required)");
+  }
+
+  async selectTab(_tabId: number): Promise<never> {
+    throw new CdpError("transport_error", "selectTab is not supported by the cdp-inspect backend (extension backend required)");
+  }
+
+  async closeTab(_tabId: number): Promise<never> {
+    throw new CdpError("transport_error", "closeTab is not supported by the cdp-inspect backend (extension backend required)");
+  }
+
   dispose(): void {
     if (this.disposed) return;
     this.disposed = true;

package/src/tools/browser/cdp-client/extension-cdp-client.ts

@@ -2,7 +2,7 @@ import type { HostBrowserProxy } from "../../../daemon/host-browser-proxy.js";
 import { getLogger } from "../../../util/logger.js";
 import type { CdpErrorCode } from "./errors.js";
 import { CdpError } from "./errors.js";
-import type { CdpClientKind, ScopedCdpClient } from "./types.js";
+import type { CdpClientKind, ScopedCdpClient, TabInfo } from "./types.js";
 
 const log = getLogger("extension-cdp-client");
 
@@ -43,7 +43,7 @@ export class ExtensionCdpClient implements ScopedCdpClient {
   constructor(
     private readonly proxy: HostBrowserProxy,
     public readonly conversationId: string,
-    private readonly cdpSessionId?: string,
+    private cdpSessionId?: string,
     /**
      * Caller's actor principal id. When provided, the proxy will refuse to
      * dispatch this CDP command to a host_browser-capable client owned by a
@@ -182,6 +182,46 @@ export class ExtensionCdpClient implements ScopedCdpClient {
     // it here. In-flight requests will be cancelled by the AbortSignal
     // the tool passes in, or by conversation teardown.
   }
+
+  /**
+   * Update the `cdpSessionId` used on subsequent {@link send} calls.
+   *
+   * Used by the navigate executor after opening a new tab via the
+   * `Vellum.createTab` pseudo-CDP method: the returned tabId becomes
+   * this client's pinned target so the follow-on `Page.navigate`
+   * (and every command on this conversation thereafter) routes to
+   * the freshly-created tab instead of the user's currently-active
+   * tab.
+   */
+  setCdpSessionId(cdpSessionId: string | undefined): void {
+    this.cdpSessionId = cdpSessionId;
+  }
+
+  /** List all open browser tabs via `Vellum.listTabs`. */
+  async listTabs(): Promise<TabInfo[]> {
+    const result = await this.send<{ tabs: TabInfo[] }>("Vellum.listTabs", {});
+    return Array.isArray(result?.tabs) ? result.tabs : [];
+  }
+
+  /** Select (activate) an existing tab via `Vellum.selectTab`. */
+  async selectTab(tabId: number): Promise<{
+    tabId?: number;
+    windowId?: number;
+    url?: string;
+    title?: string;
+    clientId?: string;
+  }> {
+    return this.send("Vellum.selectTab", { tabId });
+  }
+
+  /** Close a browser tab via `Vellum.closeTab`. */
+  async closeTab(tabId: number): Promise<{
+    closed: boolean;
+    tabId: number;
+    clientId?: string;
+  }> {
+    return this.send("Vellum.closeTab", { tabId });
+  }
 }
 
 /**