@vellumai/assistant 0.6.3 → 0.6.4

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

@@ -9,8 +9,11 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 
 import {
+  buildBrowserWsUrl,
   DevToolsDiscoveryError,
   type DevToolsTarget,
+  discoverTargetsViaWs,
+  isHttpDiscoveryFallbackEligible,
   listDevToolsTargets,
   pickDefaultTarget,
   probeDevToolsJsonVersion,
@@ -741,3 +744,264 @@ describe("pickDefaultTarget", () => {
     expect(pickDefaultTarget(targets).id).toBe("only");
   });
 });
+
+// ---------------------------------------------------------------------------
+// buildBrowserWsUrl — loopback enforcement and URL construction.
+// ---------------------------------------------------------------------------
+
+describe("buildBrowserWsUrl", () => {
+  test("builds ws URL for localhost", () => {
+    expect(buildBrowserWsUrl("localhost", 9222)).toBe(
+      "ws://localhost:9222/devtools/browser",
+    );
+  });
+
+  test("builds ws URL for 127.0.0.1", () => {
+    expect(buildBrowserWsUrl("127.0.0.1", 9333)).toBe(
+      "ws://127.0.0.1:9333/devtools/browser",
+    );
+  });
+
+  test("wraps bare ::1 in brackets", () => {
+    expect(buildBrowserWsUrl("::1", 9222)).toBe(
+      "ws://[::1]:9222/devtools/browser",
+    );
+  });
+
+  test("accepts [::1] (already bracketed)", () => {
+    expect(buildBrowserWsUrl("[::1]", 9222)).toBe(
+      "ws://[::1]:9222/devtools/browser",
+    );
+  });
+
+  test("is case-insensitive for LOCALHOST", () => {
+    expect(buildBrowserWsUrl("LOCALHOST", 9222)).toBe(
+      "ws://localhost:9222/devtools/browser",
+    );
+  });
+
+  test("rejects non-loopback hosts with non_loopback", () => {
+    expect(() => buildBrowserWsUrl("192.168.1.1", 9222)).toThrow(
+      DevToolsDiscoveryError,
+    );
+    try {
+      buildBrowserWsUrl("evil.com", 9222);
+    } catch (e) {
+      expect((e as DevToolsDiscoveryError).code).toBe("non_loopback");
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isHttpDiscoveryFallbackEligible — determines which errors trigger fallback.
+// ---------------------------------------------------------------------------
+
+describe("isHttpDiscoveryFallbackEligible", () => {
+  test("returns true for invalid_response", () => {
+    const err = new DevToolsDiscoveryError("invalid_response", "bad");
+    expect(isHttpDiscoveryFallbackEligible(err)).toBe(true);
+  });
+
+  test("returns true for unreachable", () => {
+    const err = new DevToolsDiscoveryError("unreachable", "gone");
+    expect(isHttpDiscoveryFallbackEligible(err)).toBe(true);
+  });
+
+  test("returns false for non_loopback", () => {
+    const err = new DevToolsDiscoveryError("non_loopback", "nope");
+    expect(isHttpDiscoveryFallbackEligible(err)).toBe(false);
+  });
+
+  test("returns false for non_chrome", () => {
+    const err = new DevToolsDiscoveryError("non_chrome", "Firefox");
+    expect(isHttpDiscoveryFallbackEligible(err)).toBe(false);
+  });
+
+  test("returns false for timeout", () => {
+    const err = new DevToolsDiscoveryError("timeout", "too slow");
+    expect(isHttpDiscoveryFallbackEligible(err)).toBe(false);
+  });
+
+  test("returns false for no_targets", () => {
+    const err = new DevToolsDiscoveryError("no_targets", "empty");
+    expect(isHttpDiscoveryFallbackEligible(err)).toBe(false);
+  });
+
+  test("returns false for non-DevToolsDiscoveryError", () => {
+    expect(isHttpDiscoveryFallbackEligible(new Error("random"))).toBe(false);
+    expect(isHttpDiscoveryFallbackEligible("string")).toBe(false);
+    expect(isHttpDiscoveryFallbackEligible(null)).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// discoverTargetsViaWs — target enumeration via CDP Target.getTargets.
+// ---------------------------------------------------------------------------
+
+describe("discoverTargetsViaWs", () => {
+  /**
+   * Minimal fake transport that resolves Target.getTargets with the
+   * provided target infos.
+   */
+  function fakeTransport(targetInfos: unknown[]) {
+    return {
+      send: async () => ({ targetInfos }),
+      addEventListener: () => () => {},
+      dispose: () => {},
+    } as unknown as import("../../cdp-inspect/ws-transport.js").CdpWsTransport;
+  }
+
+  test("filters page targets and constructs ws URLs", async () => {
+    const transport = fakeTransport([
+      {
+        targetId: "A",
+        type: "page",
+        title: "Example",
+        url: "https://example.com/",
+      },
+      {
+        targetId: "B",
+        type: "service_worker",
+        title: "sw",
+        url: "https://example.com/sw.js",
+      },
+      {
+        targetId: "C",
+        type: "page",
+        title: "Another",
+        url: "https://another.com/",
+      },
+    ]);
+
+    const targets = await discoverTargetsViaWs({
+      transport,
+      host: "127.0.0.1",
+      port: 9222,
+    });
+
+    expect(targets).toHaveLength(2);
+    expect(targets[0]!.id).toBe("A");
+    expect(targets[0]!.webSocketDebuggerUrl).toBe(
+      "ws://127.0.0.1:9222/devtools/page/A",
+    );
+    expect(targets[1]!.id).toBe("C");
+    expect(targets[1]!.webSocketDebuggerUrl).toBe(
+      "ws://127.0.0.1:9222/devtools/page/C",
+    );
+  });
+
+  test("throws no_targets when no page targets exist", async () => {
+    const transport = fakeTransport([
+      {
+        targetId: "B",
+        type: "service_worker",
+        title: "sw",
+        url: "https://example.com/sw.js",
+      },
+    ]);
+
+    const error = await discoverTargetsViaWs({
+      transport,
+      host: "127.0.0.1",
+      port: 9222,
+    }).catch((e: unknown) => e);
+
+    expect(error).toBeInstanceOf(DevToolsDiscoveryError);
+    expect((error as DevToolsDiscoveryError).code).toBe("no_targets");
+  });
+
+  test("throws no_targets when targetInfos is empty", async () => {
+    const transport = fakeTransport([]);
+
+    const error = await discoverTargetsViaWs({
+      transport,
+      host: "127.0.0.1",
+      port: 9222,
+    }).catch((e: unknown) => e);
+
+    expect(error).toBeInstanceOf(DevToolsDiscoveryError);
+    expect((error as DevToolsDiscoveryError).code).toBe("no_targets");
+  });
+
+  test("throws ws_fallback_failed when targetInfos is missing", async () => {
+    const transport = {
+      send: async () => ({}),
+      addEventListener: () => () => {},
+      dispose: () => {},
+    } as unknown as import("../../cdp-inspect/ws-transport.js").CdpWsTransport;
+
+    const error = await discoverTargetsViaWs({
+      transport,
+      host: "127.0.0.1",
+      port: 9222,
+    }).catch((e: unknown) => e);
+
+    expect(error).toBeInstanceOf(DevToolsDiscoveryError);
+    expect((error as DevToolsDiscoveryError).code).toBe("ws_fallback_failed");
+  });
+
+  test("rejects non-loopback host before calling transport", async () => {
+    let transportCalled = false;
+    const transport = {
+      send: async () => {
+        transportCalled = true;
+        return { targetInfos: [] };
+      },
+      addEventListener: () => () => {},
+      dispose: () => {},
+    } as unknown as import("../../cdp-inspect/ws-transport.js").CdpWsTransport;
+
+    const error = await discoverTargetsViaWs({
+      transport,
+      host: "evil.com",
+      port: 9222,
+    }).catch((e: unknown) => e);
+
+    expect(error).toBeInstanceOf(DevToolsDiscoveryError);
+    expect((error as DevToolsDiscoveryError).code).toBe("non_loopback");
+    expect(transportCalled).toBe(false);
+  });
+
+  test("skips entries with empty or missing targetId", async () => {
+    const transport = fakeTransport([
+      { targetId: "", type: "page", title: "Empty ID", url: "https://a.com/" },
+      { type: "page", title: "Missing ID", url: "https://b.com/" },
+      {
+        targetId: "valid",
+        type: "page",
+        title: "Valid",
+        url: "https://c.com/",
+      },
+    ]);
+
+    const targets = await discoverTargetsViaWs({
+      transport,
+      host: "127.0.0.1",
+      port: 9222,
+    });
+
+    expect(targets).toHaveLength(1);
+    expect(targets[0]!.id).toBe("valid");
+  });
+
+  test("constructs IPv6 ws URLs with brackets", async () => {
+    const transport = fakeTransport([
+      {
+        targetId: "A",
+        type: "page",
+        title: "Page",
+        url: "https://example.com/",
+      },
+    ]);
+
+    const targets = await discoverTargetsViaWs({
+      transport,
+      host: "::1",
+      port: 9222,
+    });
+
+    expect(targets[0]!.webSocketDebuggerUrl).toBe(
+      "ws://[::1]:9222/devtools/page/A",
+    );
+  });
+});

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

@@ -1,21 +1,28 @@
 /**
- * DevTools HTTP discovery helpers for the `cdp-inspect` backend.
+ * DevTools discovery helpers for the `cdp-inspect` backend.
  *
- * These helpers are pure HTTP/domain logic — they do not own a
- * websocket transport, a session manager, or any CDP command state.
- * They exist so the higher-level `cdp-inspect` client can:
+ * Two discovery strategies are provided:
  *
- * 1. Probe `/json/version` to verify that a loopback port is actually
- *    a Chrome/Chromium DevTools endpoint (and not some other service
- *    that happens to be listening).
- * 2. Enumerate available page targets via `/json/list`.
- * 3. Pick a sensible default target when the caller doesn't specify
- *    one explicitly.
+ * **HTTP discovery** (primary path):
+ *   1. Probe `/json/version` to verify that a loopback port is actually
+ *      a Chrome/Chromium DevTools endpoint.
+ *   2. Enumerate available page targets via `/json/list`.
+ *   3. Pick a sensible default target when the caller doesn't specify
+ *      one explicitly.
  *
- * Safety boundary: **only loopback hosts are allowed**. A non-loopback
- * host is rejected *before* any network I/O so that this module can
- * never be coerced into making cross-origin requests on behalf of an
- * attacker-controlled config value.
+ * **WS-only discovery** (fallback path):
+ *   When the HTTP endpoints (`/json/version`, `/json/list`) are
+ *   unavailable (e.g. extension/proxy environments that expose only
+ *   the WebSocket debugger), the client can fall back to a direct
+ *   WebSocket connection to the well-known browser endpoint
+ *   (`ws://<host>:<port>/devtools/browser`) and use CDP
+ *   `Target.getTargets` to enumerate targets instead.
+ *
+ * Safety boundary: **only loopback hosts are allowed** for both
+ * strategies. A non-loopback host is rejected *before* any network
+ * I/O so that this module can never be coerced into making
+ * cross-origin requests on behalf of an attacker-controlled config
+ * value.
  */
 
 /**
@@ -31,7 +38,22 @@ export type DevToolsDiscoveryErrorCode =
   | "non_chrome"
   | "invalid_response"
   | "no_targets"
-  | "timeout";
+  | "timeout"
+  | "ws_fallback_failed";
+
+/**
+ * Canonical discovery-code constants for callers that need stable,
+ * typo-safe comparisons without repeating raw string literals.
+ */
+export const DEVTOOLS_DISCOVERY_CODE = {
+  UNREACHABLE: "unreachable",
+  NON_LOOPBACK: "non_loopback",
+  NON_CHROME: "non_chrome",
+  INVALID_RESPONSE: "invalid_response",
+  NO_TARGETS: "no_targets",
+  TIMEOUT: "timeout",
+  WS_FALLBACK_FAILED: "ws_fallback_failed",
+} as const satisfies Record<string, DevToolsDiscoveryErrorCode>;
 
 /**
  * Single error type thrown by all discovery helpers. Mirrors the
@@ -126,14 +148,26 @@ function assertWsUrlLoopback(wsUrl: string): void {
   }
 }
 
+/**
+ * Normalize a loopback host string for use in a URL. IPv6 bare form
+ * (`::1`) is wrapped in square brackets (`[::1]`) as required by
+ * RFC 3986; all other hosts are lowercased and returned as-is.
+ *
+ * This is the single source of truth for IPv6 bracket normalization
+ * across both HTTP and WS URL construction in this module.
+ */
+function normalizeHostForWsUrl(host: string): string {
+  const normalized = host.toLowerCase();
+  return normalized === "::1" ? "[::1]" : normalized;
+}
+
 /**
  * Build a fetch-ready loopback URL. `host` is assumed to have already
  * been validated by {@link assertLoopback}. IPv6 bare form (`::1`) is
  * wrapped in square brackets for URL correctness.
  */
 function buildUrl(host: string, port: number, pathname: string): string {
-  const normalized = host.toLowerCase();
-  const hostSegment = normalized === "::1" ? "[::1]" : normalized;
+  const hostSegment = normalizeHostForWsUrl(host);
   return `http://${hostSegment}:${port}${pathname}`;
 }
 
@@ -576,3 +610,135 @@ function isUtilityTarget(target: DevToolsTarget): boolean {
   if (url === "about:blank") return true;
   return false;
 }
+
+// ---------------------------------------------------------------------------
+// WS-only discovery fallback
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a well-known browser-level WebSocket debugger URL from a
+ * loopback host and port. The resulting URL follows the standard
+ * Chrome DevTools pattern: `ws://<host>:<port>/devtools/browser`.
+ *
+ * Enforces the same loopback check as {@link probeDevToolsJsonVersion}
+ * so this function can never produce a URL that points outside the
+ * local machine. IPv6 bare form (`::1`) is wrapped in square brackets.
+ *
+ * Exported for use by the `cdp-inspect` client's WS fallback path and
+ * for unit testing.
+ */
+export function buildBrowserWsUrl(host: string, port: number): string {
+  assertLoopback(host);
+  const hostSegment = normalizeHostForWsUrl(host);
+  return `ws://${hostSegment}:${port}/devtools/browser`;
+}
+
+/**
+ * Determine whether an HTTP discovery error is eligible for the
+ * WS-only fallback. Only `invalid_response` and `unreachable` qualify
+ * — these indicate the HTTP endpoints are absent or the server doesn't
+ * speak the JSON discovery protocol. Errors like `non_loopback`,
+ * `non_chrome`, and `timeout` should *not* trigger the fallback because
+ * they indicate a fundamental safety or configuration problem.
+ */
+export function isHttpDiscoveryFallbackEligible(
+  err: unknown,
+): err is DevToolsDiscoveryError {
+  if (!(err instanceof DevToolsDiscoveryError)) return false;
+  return err.code === "invalid_response" || err.code === "unreachable";
+}
+
+/**
+ * Target info returned by CDP `Target.getTargets`. A subset of the
+ * full `TargetInfo` — we only need enough to build a
+ * {@link DevToolsTarget} for the attach step.
+ */
+interface CdpTargetInfo {
+  targetId: string;
+  type: string;
+  title: string;
+  url: string;
+}
+
+/**
+ * Enumerate page targets via a direct WebSocket connection to the
+ * browser-level DevTools endpoint. Uses CDP `Target.getTargets` instead
+ * of the HTTP `/json/list` endpoint.
+ *
+ * This function is the core of the WS-only fallback: when the HTTP
+ * discovery endpoints are absent, the caller connects to the well-known
+ * `ws://<host>:<port>/devtools/browser` URL and uses this function to
+ * discover page targets.
+ *
+ * The transport is provided by the caller (the cdp-inspect client's
+ * attach method) so this function doesn't own the socket lifecycle.
+ *
+ * Returns a filtered list of page targets. Throws `no_targets` when no
+ * page targets are found.
+ *
+ * @param transport - An already-connected {@link CdpWsTransport}.
+ * @param host - The loopback host, used to construct per-target ws URLs.
+ * @param port - The port, used to construct per-target ws URLs.
+ * @param signal - Optional abort signal for the CDP call.
+ */
+export async function discoverTargetsViaWs(opts: {
+  transport: import("./ws-transport.js").CdpWsTransport;
+  host: string;
+  port: number;
+  signal?: AbortSignal;
+}): Promise<DevToolsTarget[]> {
+  assertLoopback(opts.host);
+
+  const result = await opts.transport.send<{
+    targetInfos?: CdpTargetInfo[];
+  }>("Target.getTargets", undefined, { signal: opts.signal });
+
+  const targetInfos = result?.targetInfos;
+  if (!Array.isArray(targetInfos)) {
+    throw new DevToolsDiscoveryError(
+      "ws_fallback_failed",
+      "Target.getTargets did not return a targetInfos array.",
+    );
+  }
+
+  const hostSegment = normalizeHostForWsUrl(opts.host);
+
+  const targets: DevToolsTarget[] = [];
+  for (const info of targetInfos) {
+    if (
+      typeof info !== "object" ||
+      info === null ||
+      typeof info.type !== "string"
+    ) {
+      continue;
+    }
+    if (info.type !== "page") continue;
+
+    const id =
+      typeof info.targetId === "string" && info.targetId.length > 0
+        ? info.targetId
+        : "";
+    if (!id) continue;
+
+    const title = typeof info.title === "string" ? info.title : "";
+    const url = typeof info.url === "string" ? info.url : "";
+    // In WS-only mode, Chrome does not provide per-target ws URLs via
+    // the HTTP API. Construct the standard DevTools per-page URL so
+    // downstream code has a consistent shape. Note: the cdp-inspect
+    // client does not actually use this URL to connect — it uses
+    // Target.attachToTarget on the browser-level transport instead.
+    const webSocketDebuggerUrl = `ws://${hostSegment}:${opts.port}/devtools/page/${id}`;
+
+    targets.push({ id, type: "page", title, url, webSocketDebuggerUrl });
+  }
+
+  if (targets.length === 0) {
+    throw new DevToolsDiscoveryError(
+      "no_targets",
+      "No usable page targets returned by CDP Target.getTargets. " +
+        "Ensure at least one browser tab is open.",
+    );
+  }
+
+  return targets;
+}