@vellumai/assistant 0.6.2 → 0.6.3

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

@@ -0,0 +1,330 @@
+import { describe, expect, mock, test } from "bun:test";
+
+import type { HostBrowserProxy } from "../../../../daemon/host-browser-proxy.js";
+import { CdpError } from "../errors.js";
+import {
+  createExtensionCdpClient,
+  ExtensionCdpClient,
+} from "../extension-cdp-client.js";
+
+type ProxyResult = { content: string; isError: boolean };
+
+/**
+ * Build a fake HostBrowserProxy whose `request` method delegates to the
+ * provided handler. The returned object is structurally compatible with
+ * the parts of HostBrowserProxy that ExtensionCdpClient touches.
+ */
+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("ExtensionCdpClient", () => {
+  test("kind is 'extension' and exposes conversationId", () => {
+    const { proxy } = fakeProxy(async () => ({
+      content: "{}",
+      isError: false,
+    }));
+    const client = createExtensionCdpClient(proxy, "conv-abc");
+    expect(client).toBeInstanceOf(ExtensionCdpClient);
+    expect(client.kind).toBe("extension");
+    expect(client.conversationId).toBe("conv-abc");
+  });
+
+  test("happy path: send returns parsed JSON and forwards method/params/conversationId", async () => {
+    const { proxy, request } = fakeProxy(async () => ({
+      content: JSON.stringify({
+        product: "Chrome/123.0",
+        userAgent: "Mozilla/5.0",
+      }),
+      isError: false,
+    }));
+
+    const client = createExtensionCdpClient(proxy, "conv-1");
+    const result = await client.send<{ product: string; userAgent: string }>(
+      "Browser.getVersion",
+    );
+
+    expect(result).toEqual({
+      product: "Chrome/123.0",
+      userAgent: "Mozilla/5.0",
+    });
+    expect(request).toHaveBeenCalledTimes(1);
+    const call = request.mock.calls[0];
+    expect(call?.[0]).toEqual({
+      cdpMethod: "Browser.getVersion",
+      cdpParams: undefined,
+      cdpSessionId: undefined,
+    });
+    expect(call?.[1]).toBe("conv-1");
+    expect(call?.[2]).toBeUndefined();
+  });
+
+  test("params are forwarded verbatim to proxy.request", async () => {
+    const { proxy, request } = fakeProxy(async () => ({
+      content: JSON.stringify({ frameId: "frame-1", loaderId: "loader-1" }),
+      isError: false,
+    }));
+
+    const client = createExtensionCdpClient(proxy, "conv-2");
+    await client.send("Page.navigate", { url: "https://example.com/" });
+
+    expect(request).toHaveBeenCalledTimes(1);
+    expect(request.mock.calls[0]?.[0]).toEqual({
+      cdpMethod: "Page.navigate",
+      cdpParams: { url: "https://example.com/" },
+      cdpSessionId: undefined,
+    });
+  });
+
+  test("cdpSessionId from constructor is forwarded on every send", async () => {
+    const { proxy, request } = fakeProxy(async () => ({
+      content: "{}",
+      isError: false,
+    }));
+
+    const client = createExtensionCdpClient(proxy, "conv-3", "session-xyz");
+    await client.send("Runtime.evaluate", { expression: "1" });
+    await client.send("DOM.getDocument");
+
+    expect(request).toHaveBeenCalledTimes(2);
+    for (const call of request.mock.calls) {
+      expect((call?.[0] as { cdpSessionId?: string }).cdpSessionId).toBe(
+        "session-xyz",
+      );
+    }
+  });
+
+  test("result.isError === true throws CdpError('cdp_error') with .underlying === parsed", async () => {
+    const errorBody = {
+      code: -32000,
+      message: "Cannot find context with specified id",
+    };
+    const { proxy } = fakeProxy(async () => ({
+      content: JSON.stringify(errorBody),
+      isError: true,
+    }));
+
+    const client = createExtensionCdpClient(proxy, "conv-4");
+
+    let caught: unknown;
+    try {
+      await client.send("Runtime.evaluate", { expression: "boom" });
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(CdpError);
+    const err = caught as CdpError;
+    expect(err.code).toBe("cdp_error");
+    expect(err.message).toBe("Cannot find context with specified id");
+    expect(err.cdpMethod).toBe("Runtime.evaluate");
+    expect(err.cdpParams).toEqual({ expression: "boom" });
+    expect(err.underlying).toEqual(errorBody);
+  });
+
+  test("result.isError with non-string message falls back to default message", async () => {
+    const { proxy } = fakeProxy(async () => ({
+      content: JSON.stringify({ code: -32000 }),
+      isError: true,
+    }));
+
+    const client = createExtensionCdpClient(proxy, "conv-5");
+
+    let caught: unknown;
+    try {
+      await client.send("Target.attachToTarget");
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(CdpError);
+    const err = caught as CdpError;
+    expect(err.code).toBe("cdp_error");
+    expect(err.message).toBe("CDP error for Target.attachToTarget");
+    expect(err.underlying).toEqual({ code: -32000 });
+  });
+
+  test("non-JSON content throws CdpError('transport_error')", async () => {
+    const { proxy } = fakeProxy(async () => ({
+      content: "not json at all",
+      isError: false,
+    }));
+
+    const client = createExtensionCdpClient(proxy, "conv-6");
+
+    let caught: unknown;
+    try {
+      await client.send("Browser.getVersion");
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(CdpError);
+    const err = caught as CdpError;
+    expect(err.code).toBe("transport_error");
+    expect(err.cdpMethod).toBe("Browser.getVersion");
+    expect(err.underlying).toBeDefined();
+    // Underlying should be the JSON.parse error.
+    expect(err.underlying).toBeInstanceOf(Error);
+  });
+
+  test("result.content === 'Aborted' throws CdpError('aborted')", async () => {
+    const { proxy, request } = fakeProxy(async () => ({
+      content: "Aborted",
+      isError: true,
+    }));
+
+    const client = createExtensionCdpClient(proxy, "conv-7");
+
+    let caught: unknown;
+    try {
+      await client.send("Page.navigate", { url: "https://slow.example.com/" });
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(CdpError);
+    const err = caught as CdpError;
+    expect(err.code).toBe("aborted");
+    expect(err.cdpMethod).toBe("Page.navigate");
+    expect(err.cdpParams).toEqual({ url: "https://slow.example.com/" });
+    expect(request).toHaveBeenCalledTimes(1);
+  });
+
+  test("proxy.request throwing wraps as CdpError('transport_error') with .underlying", async () => {
+    const underlying = new Error("socket closed");
+    const { proxy } = fakeProxy(async () => {
+      throw underlying;
+    });
+
+    const client = createExtensionCdpClient(proxy, "conv-8");
+
+    let caught: unknown;
+    try {
+      await client.send("Runtime.evaluate", { expression: "1" });
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(CdpError);
+    const err = caught as CdpError;
+    expect(err.code).toBe("transport_error");
+    expect(err.message).toBe("socket closed");
+    expect(err.cdpMethod).toBe("Runtime.evaluate");
+    expect(err.cdpParams).toEqual({ expression: "1" });
+    expect(err.underlying).toBe(underlying);
+  });
+
+  test("proxy.request throwing non-Error wraps as CdpError('transport_error') with stringified message", async () => {
+    const { proxy } = fakeProxy(async () => {
+      throw "string error";
+    });
+
+    const client = createExtensionCdpClient(proxy, "conv-9");
+
+    let caught: unknown;
+    try {
+      await client.send("Browser.getVersion");
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(CdpError);
+    const err = caught as CdpError;
+    expect(err.code).toBe("transport_error");
+    expect(err.message).toBe("string error");
+    expect(err.underlying).toBe("string error");
+  });
+
+  test("send after dispose throws CdpError('disposed') without calling proxy", async () => {
+    const { proxy, request } = fakeProxy(async () => ({
+      content: "{}",
+      isError: false,
+    }));
+
+    const client = createExtensionCdpClient(proxy, "conv-10");
+    client.dispose();
+    // dispose is idempotent
+    client.dispose();
+
+    let caught: unknown;
+    try {
+      await client.send("Browser.getVersion");
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(CdpError);
+    const err = caught as CdpError;
+    expect(err.code).toBe("disposed");
+    expect(err.cdpMethod).toBe("Browser.getVersion");
+    expect(request).not.toHaveBeenCalled();
+  });
+
+  test("send with already-aborted signal throws CdpError('aborted') without calling proxy", async () => {
+    const { proxy, request } = fakeProxy(async () => ({
+      content: "{}",
+      isError: false,
+    }));
+
+    const client = createExtensionCdpClient(proxy, "conv-11");
+    const controller = new AbortController();
+    controller.abort();
+
+    let caught: unknown;
+    try {
+      await client.send("Browser.getVersion", undefined, controller.signal);
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(CdpError);
+    const err = caught as CdpError;
+    expect(err.code).toBe("aborted");
+    expect(err.message).toBe("Aborted before send");
+    expect(err.cdpMethod).toBe("Browser.getVersion");
+    expect(request).not.toHaveBeenCalled();
+  });
+
+  test("signal that aborts after proxy resolve throws CdpError('aborted')", async () => {
+    const controller = new AbortController();
+    const { proxy } = fakeProxy(async () => {
+      // Abort the signal before we return, simulating race between
+      // proxy resolution and the caller's abort.
+      controller.abort();
+      return { content: JSON.stringify({ ok: true }), isError: false };
+    });
+
+    const client = createExtensionCdpClient(proxy, "conv-12");
+
+    let caught: unknown;
+    try {
+      await client.send("Browser.getVersion", undefined, controller.signal);
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(CdpError);
+    const err = caught as CdpError;
+    expect(err.code).toBe("aborted");
+    expect(err.message).toBe("CDP call aborted");
+    expect(err.cdpMethod).toBe("Browser.getVersion");
+  });
+});

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

@@ -0,0 +1,377 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { HostBrowserProxy } from "../../../../daemon/host-browser-proxy.js";
+import type { ToolContext } from "../../../types.js";
+import { CdpError } from "../errors.js";
+
+type FakeClient = {
+  kind: "extension" | "local" | "cdp-inspect";
+  conversationId: string;
+  send: ReturnType<typeof mock>;
+  dispose: ReturnType<typeof mock>;
+};
+
+function makeFakeExtensionClient(conversationId: string): FakeClient {
+  return {
+    kind: "extension",
+    conversationId,
+    send: mock(async () => ({ ok: true, via: "extension" })),
+    dispose: mock(() => {}),
+  };
+}
+
+function makeFakeLocalClient(conversationId: string): FakeClient {
+  return {
+    kind: "local",
+    conversationId,
+    send: mock(async () => ({ ok: true, via: "local" })),
+    dispose: mock(() => {}),
+  };
+}
+
+function makeFakeCdpInspectClient(conversationId: string): FakeClient {
+  return {
+    kind: "cdp-inspect",
+    conversationId,
+    send: mock(async () => ({ ok: true, via: "cdp-inspect" })),
+    dispose: mock(() => {}),
+  };
+}
+
+let lastExtensionClient: FakeClient | undefined;
+let lastLocalClient: FakeClient | undefined;
+let lastCdpInspectClient: FakeClient | undefined;
+
+const createExtensionCdpClientMock = mock(
+  (_proxy: HostBrowserProxy, conversationId: string) => {
+    const client = makeFakeExtensionClient(conversationId);
+    lastExtensionClient = client;
+    return client;
+  },
+);
+
+const createLocalCdpClientMock = mock((conversationId: string) => {
+  const client = makeFakeLocalClient(conversationId);
+  lastLocalClient = client;
+  return client;
+});
+
+const createCdpInspectClientMock = mock(
+  (conversationId: string, _options: unknown) => {
+    const client = makeFakeCdpInspectClient(conversationId);
+    lastCdpInspectClient = client;
+    return client;
+  },
+);
+
+/**
+ * Mutable config state. Tests flip `cdpInspectEnabled` to control
+ * the factory's config-based selection without needing a real config
+ * file.
+ */
+let cdpInspectEnabled = false;
+
+mock.module("../extension-cdp-client.js", () => ({
+  createExtensionCdpClient: createExtensionCdpClientMock,
+}));
+mock.module("../local-cdp-client.js", () => ({
+  createLocalCdpClient: createLocalCdpClientMock,
+}));
+mock.module("../cdp-inspect-client.js", () => ({
+  createCdpInspectClient: createCdpInspectClientMock,
+}));
+mock.module("../../../../config/loader.js", () => ({
+  getConfig: () => ({
+    hostBrowser: {
+      cdpInspect: {
+        enabled: cdpInspectEnabled,
+        host: "localhost",
+        port: 9222,
+        probeTimeoutMs: 500,
+      },
+    },
+  }),
+}));
+
+// Import under test AFTER mock.module calls so that the factory's
+// top-level imports resolve to our fakes.
+const { getCdpClient } = await import("../factory.js");
+
+/**
+ * Minimal ToolContext suitable for factory tests. Only the fields the
+ * factory reads (`conversationId` and `hostBrowserProxy`) need to be
+ * populated; other required fields are cast away.
+ */
+function makeContext(
+  overrides: Partial<ToolContext> & { conversationId: string },
+): ToolContext {
+  return overrides as unknown as ToolContext;
+}
+
+describe("getCdpClient", () => {
+  beforeEach(() => {
+    createExtensionCdpClientMock.mockClear();
+    createLocalCdpClientMock.mockClear();
+    createCdpInspectClientMock.mockClear();
+    lastExtensionClient = undefined;
+    lastLocalClient = undefined;
+    lastCdpInspectClient = undefined;
+    cdpInspectEnabled = false;
+  });
+
+  test("routes to ExtensionCdpClient when hostBrowserProxy is set", () => {
+    const fakeProxy = {
+      request: mock(async () => ({})),
+    } as unknown as HostBrowserProxy;
+    const ctx = makeContext({
+      conversationId: "test-convo",
+      hostBrowserProxy: fakeProxy,
+    });
+
+    const client = getCdpClient(ctx);
+
+    expect(client.kind).toBe("extension");
+    expect(client.conversationId).toBe("test-convo");
+    expect(createExtensionCdpClientMock).toHaveBeenCalledTimes(1);
+    expect(createExtensionCdpClientMock).toHaveBeenCalledWith(
+      fakeProxy,
+      "test-convo",
+    );
+    expect(createLocalCdpClientMock).not.toHaveBeenCalled();
+    expect(createCdpInspectClientMock).not.toHaveBeenCalled();
+  });
+
+  test("extension wins even when cdpInspect is enabled", () => {
+    cdpInspectEnabled = true;
+    const fakeProxy = {
+      request: mock(async () => ({})),
+    } as unknown as HostBrowserProxy;
+    const ctx = makeContext({
+      conversationId: "ext-wins",
+      hostBrowserProxy: fakeProxy,
+    });
+
+    const client = getCdpClient(ctx);
+
+    expect(client.kind).toBe("extension");
+    expect(createExtensionCdpClientMock).toHaveBeenCalledTimes(1);
+    expect(createCdpInspectClientMock).not.toHaveBeenCalled();
+    expect(createLocalCdpClientMock).not.toHaveBeenCalled();
+  });
+
+  test("routes to CdpInspectClient when cdpInspect is enabled and extension is absent", () => {
+    cdpInspectEnabled = true;
+    const ctx = makeContext({
+      conversationId: "inspect-convo",
+      hostBrowserProxy: undefined,
+    });
+
+    const client = getCdpClient(ctx);
+
+    expect(client.kind).toBe("cdp-inspect");
+    expect(client.conversationId).toBe("inspect-convo");
+    expect(createCdpInspectClientMock).toHaveBeenCalledTimes(1);
+    expect(createCdpInspectClientMock).toHaveBeenCalledWith("inspect-convo", {
+      host: "localhost",
+      port: 9222,
+      discoveryTimeoutMs: 500,
+    });
+    expect(createExtensionCdpClientMock).not.toHaveBeenCalled();
+    expect(createLocalCdpClientMock).not.toHaveBeenCalled();
+  });
+
+  test("routes to LocalCdpClient when cdpInspect is disabled and extension is absent", () => {
+    cdpInspectEnabled = false;
+    const ctx = makeContext({
+      conversationId: "local-convo",
+      hostBrowserProxy: undefined,
+    });
+
+    const client = getCdpClient(ctx);
+
+    expect(client.kind).toBe("local");
+    expect(client.conversationId).toBe("local-convo");
+    expect(createLocalCdpClientMock).toHaveBeenCalledTimes(1);
+    expect(createLocalCdpClientMock).toHaveBeenCalledWith("local-convo");
+    expect(createExtensionCdpClientMock).not.toHaveBeenCalled();
+    expect(createCdpInspectClientMock).not.toHaveBeenCalled();
+  });
+
+  test("routes to LocalCdpClient when hostBrowserProxy key is omitted", () => {
+    const ctx = makeContext({ conversationId: "another-convo" });
+
+    const client = getCdpClient(ctx);
+
+    expect(client.kind).toBe("local");
+    expect(client.conversationId).toBe("another-convo");
+    expect(createLocalCdpClientMock).toHaveBeenCalledTimes(1);
+    expect(createLocalCdpClientMock).toHaveBeenCalledWith("another-convo");
+    expect(createExtensionCdpClientMock).not.toHaveBeenCalled();
+    expect(createCdpInspectClientMock).not.toHaveBeenCalled();
+  });
+
+  test("forwards send() through the manager to the extension-backed client", async () => {
+    const fakeProxy = {
+      request: mock(async () => ({})),
+    } as unknown as HostBrowserProxy;
+    const ctx = makeContext({
+      conversationId: "send-ext",
+      hostBrowserProxy: fakeProxy,
+    });
+
+    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: "extension" });
+    expect(lastExtensionClient?.send).toHaveBeenCalledTimes(1);
+    expect(lastExtensionClient?.send).toHaveBeenCalledWith(
+      "Page.navigate",
+      { url: "https://example.com" },
+      undefined,
+    );
+    expect(lastLocalClient).toBeUndefined();
+    expect(lastCdpInspectClient).toBeUndefined();
+  });
+
+  test("forwards send() through the manager to the local-backed client", async () => {
+    const ctx = makeContext({ conversationId: "send-local" });
+
+    const client = getCdpClient(ctx);
+    const result = await client.send<{ ok: boolean; via: string }>(
+      "Runtime.evaluate",
+      { expression: "1+1" },
+    );
+
+    expect(result).toEqual({ ok: true, via: "local" });
+    expect(lastLocalClient?.send).toHaveBeenCalledTimes(1);
+    expect(lastLocalClient?.send).toHaveBeenCalledWith(
+      "Runtime.evaluate",
+      { expression: "1+1" },
+      undefined,
+    );
+    expect(lastExtensionClient).toBeUndefined();
+    expect(lastCdpInspectClient).toBeUndefined();
+  });
+
+  test("forwards send() through the manager to the cdp-inspect-backed client", async () => {
+    cdpInspectEnabled = true;
+    const ctx = makeContext({ conversationId: "send-inspect" });
+
+    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: "cdp-inspect" });
+    expect(lastCdpInspectClient?.send).toHaveBeenCalledTimes(1);
+    expect(lastCdpInspectClient?.send).toHaveBeenCalledWith(
+      "Page.navigate",
+      { url: "https://example.com" },
+      undefined,
+    );
+    expect(lastExtensionClient).toBeUndefined();
+    expect(lastLocalClient).toBeUndefined();
+  });
+
+  test("propagates CdpError thrown by the underlying client", async () => {
+    const ctx = makeContext({ conversationId: "err-local" });
+    const client = getCdpClient(ctx);
+    const thrown = new CdpError("cdp_error", "kaboom", {
+      cdpMethod: "Page.navigate",
+    });
+    lastLocalClient!.send = mock(async () => {
+      throw thrown;
+    });
+
+    await expect(
+      client.send("Page.navigate", { url: "https://example.com" }),
+    ).rejects.toBe(thrown);
+  });
+
+  test("propagates caller AbortSignal to the underlying client", async () => {
+    const ctx = makeContext({ conversationId: "abort-local" });
+    const client = getCdpClient(ctx);
+    const controller = new AbortController();
+    let sawSignal: AbortSignal | undefined;
+    lastLocalClient!.send = mock(
+      async (
+        _method: string,
+        _params?: Record<string, unknown>,
+        signal?: AbortSignal,
+      ) => {
+        sawSignal = signal;
+        if (signal?.aborted) {
+          throw new CdpError("aborted", "aborted before send");
+        }
+        return {};
+      },
+    );
+
+    controller.abort();
+    await expect(
+      client.send("Page.navigate", { url: "https://x" }, controller.signal),
+    ).rejects.toMatchObject({ code: "aborted" });
+    expect(sawSignal).toBe(controller.signal);
+  });
+
+  test("dispose() tears down the underlying client and rejects further sends", async () => {
+    const ctx = makeContext({ conversationId: "dispose-local" });
+    const client = getCdpClient(ctx);
+
+    client.dispose();
+    expect(lastLocalClient?.dispose).toHaveBeenCalledTimes(1);
+
+    // A second dispose is a no-op.
+    client.dispose();
+    expect(lastLocalClient?.dispose).toHaveBeenCalledTimes(1);
+
+    await expect(client.send("Runtime.evaluate")).rejects.toMatchObject({
+      code: "disposed",
+    });
+  });
+
+  test("dispose() on an extension-backed client tears down the extension client", () => {
+    const fakeProxy = {
+      request: mock(async () => ({})),
+    } as unknown as HostBrowserProxy;
+    const ctx = makeContext({
+      conversationId: "dispose-ext",
+      hostBrowserProxy: fakeProxy,
+    });
+
+    const client = getCdpClient(ctx);
+    client.dispose();
+
+    expect(lastExtensionClient?.dispose).toHaveBeenCalledTimes(1);
+  });
+
+  test("dispose() on a cdp-inspect-backed client tears down the inspect client", () => {
+    cdpInspectEnabled = true;
+    const ctx = makeContext({ conversationId: "dispose-inspect" });
+
+    const client = getCdpClient(ctx);
+    client.dispose();
+
+    expect(lastCdpInspectClient?.dispose).toHaveBeenCalledTimes(1);
+  });
+
+  test("send() after dispose() on a cdp-inspect-backed client rejects with disposed", async () => {
+    cdpInspectEnabled = true;
+    const ctx = makeContext({ conversationId: "post-dispose-inspect" });
+
+    const client = getCdpClient(ctx);
+    client.dispose();
+
+    // Double dispose is a no-op.
+    client.dispose();
+    expect(lastCdpInspectClient?.dispose).toHaveBeenCalledTimes(1);
+
+    await expect(client.send("Page.navigate")).rejects.toMatchObject({
+      code: "disposed",
+    });
+  });
+});