pi-feats 0.1.3 → 0.1.4

package/extensions/browser-harness/cdp/commands.ts

@@ -0,0 +1,260 @@
+import { Type, type Static, type TSchema } from "typebox";
+import { Compile } from "typebox/compile";
+import { type Result, err, ok } from "../util/result";
+import { type CdpError, cdpError } from "./errors";
+
+const cmd = <P extends TSchema, R extends TSchema>(params: P, result: R) => ({
+  params,
+  result,
+  validate: Compile(result),
+});
+
+const Empty = Type.Object({});
+
+const TargetInfo = Type.Object(
+  {
+    targetId: Type.String(),
+    type: Type.String(),
+    title: Type.String(),
+    url: Type.String(),
+    attached: Type.Optional(Type.Boolean()),
+    openerId: Type.Optional(Type.String()),
+    browserContextId: Type.Optional(Type.String()),
+  },
+  { additionalProperties: true },
+);
+
+const RemoteObject = Type.Object(
+  {
+    type: Type.String(),
+    subtype: Type.Optional(Type.String()),
+    className: Type.Optional(Type.String()),
+    value: Type.Optional(Type.Unknown()),
+    description: Type.Optional(Type.String()),
+    objectId: Type.Optional(Type.String()),
+  },
+  { additionalProperties: true },
+);
+
+const CallArgument = Type.Object(
+  {
+    value: Type.Optional(Type.Unknown()),
+    objectId: Type.Optional(Type.String()),
+    unserializableValue: Type.Optional(Type.String()),
+  },
+  { additionalProperties: true },
+);
+
+const ExceptionDetails = Type.Object(
+  { text: Type.String(), exception: Type.Optional(RemoteObject) },
+  { additionalProperties: true },
+);
+
+const AxValue = Type.Object({ value: Type.Optional(Type.Unknown()) }, { additionalProperties: true });
+
+const AxNode = Type.Object(
+  {
+    nodeId: Type.String(),
+    parentId: Type.Optional(Type.String()),
+    childIds: Type.Optional(Type.Array(Type.String())),
+    ignored: Type.Optional(Type.Boolean()),
+    role: Type.Optional(AxValue),
+    name: Type.Optional(AxValue),
+    value: Type.Optional(AxValue),
+    description: Type.Optional(AxValue),
+    properties: Type.Optional(
+      Type.Array(
+        Type.Object(
+          { name: Type.Optional(Type.String()), value: Type.Optional(AxValue) },
+          { additionalProperties: true },
+        ),
+      ),
+    ),
+    backendDOMNodeId: Type.Optional(Type.Number()),
+  },
+  { additionalProperties: true },
+);
+
+export type AxNodeResult = Static<typeof AxNode>;
+
+export const COMMANDS = {
+  "Target.attachToTarget": cmd(
+    Type.Object({ targetId: Type.String(), flatten: Type.Optional(Type.Boolean()) }),
+    Type.Object({ sessionId: Type.String() }),
+  ),
+  "Target.detachFromTarget": cmd(
+    Type.Object({ sessionId: Type.Optional(Type.String()) }),
+    Empty,
+  ),
+  "Target.createTarget": cmd(
+    Type.Object({
+      url: Type.String(),
+      newWindow: Type.Optional(Type.Boolean()),
+      background: Type.Optional(Type.Boolean()),
+      windowId: Type.Optional(Type.Number()),
+      openerId: Type.Optional(Type.String()),
+    }),
+    Type.Object({ targetId: Type.String() }),
+  ),
+  "Target.closeTarget": cmd(
+    Type.Object({ targetId: Type.String() }),
+    Type.Object({ success: Type.Optional(Type.Boolean()) }),
+  ),
+  "Target.activateTarget": cmd(Type.Object({ targetId: Type.String() }), Empty),
+  "Target.getTargetInfo": cmd(
+    Type.Object({ targetId: Type.Optional(Type.String()) }),
+    Type.Object({ targetInfo: TargetInfo }),
+  ),
+  "Target.getTargets": cmd(
+    Type.Object({}),
+    Type.Object({ targetInfos: Type.Array(TargetInfo) }),
+  ),
+  "Target.setDiscoverTargets": cmd(Type.Object({ discover: Type.Boolean() }), Empty),
+
+  "Browser.getWindowForTarget": cmd(
+    Type.Object({ targetId: Type.Optional(Type.String()) }),
+    Type.Object({ windowId: Type.Number(), bounds: Type.Optional(Type.Unknown()) }),
+  ),
+  "Browser.setDownloadBehavior": cmd(
+    Type.Object({
+      behavior: Type.String(),
+      downloadPath: Type.Optional(Type.String()),
+      eventsEnabled: Type.Optional(Type.Boolean()),
+    }),
+    Empty,
+  ),
+
+  "Page.enable": cmd(Type.Object({}), Empty),
+  "Page.bringToFront": cmd(Type.Object({}), Empty),
+  "Page.navigate": cmd(
+    Type.Object({ url: Type.String(), referrer: Type.Optional(Type.String()) }),
+    Type.Object({
+      frameId: Type.String(),
+      loaderId: Type.Optional(Type.String()),
+      errorText: Type.Optional(Type.String()),
+    }),
+  ),
+  "Page.reload": cmd(Type.Object({ ignoreCache: Type.Optional(Type.Boolean()) }), Empty),
+  "Page.getNavigationHistory": cmd(
+    Type.Object({}),
+    Type.Object({
+      currentIndex: Type.Number(),
+      entries: Type.Array(
+        Type.Object({ id: Type.Number(), url: Type.String(), title: Type.String() }),
+      ),
+    }),
+  ),
+  "Page.navigateToHistoryEntry": cmd(Type.Object({ entryId: Type.Number() }), Empty),
+  "Page.captureScreenshot": cmd(
+    Type.Object({
+      format: Type.Optional(Type.String()),
+      quality: Type.Optional(Type.Number()),
+      clip: Type.Optional(Type.Unknown()),
+      captureBeyondViewport: Type.Optional(Type.Boolean()),
+    }),
+    Type.Object({ data: Type.String() }),
+  ),
+  "Page.printToPDF": cmd(Type.Object({}, { additionalProperties: true }), Type.Object({ data: Type.String() })),
+  "Page.handleJavaScriptDialog": cmd(
+    Type.Object({ accept: Type.Boolean(), promptText: Type.Optional(Type.String()) }),
+    Empty,
+  ),
+
+  "Runtime.evaluate": cmd(
+    Type.Object(
+      {
+        expression: Type.String(),
+        returnByValue: Type.Optional(Type.Boolean()),
+        awaitPromise: Type.Optional(Type.Boolean()),
+        userGesture: Type.Optional(Type.Boolean()),
+      },
+      { additionalProperties: true },
+    ),
+    Type.Object({ result: RemoteObject, exceptionDetails: Type.Optional(ExceptionDetails) }),
+  ),
+  "Runtime.callFunctionOn": cmd(
+    Type.Object(
+      {
+        functionDeclaration: Type.String(),
+        objectId: Type.Optional(Type.String()),
+        arguments: Type.Optional(Type.Array(CallArgument)),
+        returnByValue: Type.Optional(Type.Boolean()),
+        awaitPromise: Type.Optional(Type.Boolean()),
+        userGesture: Type.Optional(Type.Boolean()),
+      },
+      { additionalProperties: true },
+    ),
+    Type.Object({ result: RemoteObject, exceptionDetails: Type.Optional(ExceptionDetails) }),
+  ),
+  "Runtime.releaseObject": cmd(Type.Object({ objectId: Type.String() }), Empty),
+
+  "DOM.getDocument": cmd(
+    Type.Object({ depth: Type.Optional(Type.Number()), pierce: Type.Optional(Type.Boolean()) }),
+    Type.Object({ root: Type.Object({ nodeId: Type.Number() }, { additionalProperties: true }) }),
+  ),
+  "DOM.querySelector": cmd(
+    Type.Object({ nodeId: Type.Number(), selector: Type.String() }),
+    Type.Object({ nodeId: Type.Number() }),
+  ),
+  "DOM.getBoxModel": cmd(
+    Type.Object({ nodeId: Type.Optional(Type.Number()), backendNodeId: Type.Optional(Type.Number()) }),
+    Type.Object({
+      model: Type.Object(
+        { content: Type.Array(Type.Number()), width: Type.Number(), height: Type.Number() },
+        { additionalProperties: true },
+      ),
+    }),
+  ),
+  "DOM.resolveNode": cmd(
+    Type.Object({ nodeId: Type.Optional(Type.Number()), backendNodeId: Type.Optional(Type.Number()) }),
+    Type.Object({ object: RemoteObject }),
+  ),
+  "DOM.setFileInputFiles": cmd(
+    Type.Object({
+      files: Type.Array(Type.String()),
+      nodeId: Type.Optional(Type.Number()),
+      backendNodeId: Type.Optional(Type.Number()),
+      objectId: Type.Optional(Type.String()),
+    }),
+    Empty,
+  ),
+
+  "Input.dispatchMouseEvent": cmd(Type.Object({}, { additionalProperties: true }), Empty),
+  "Input.dispatchKeyEvent": cmd(Type.Object({}, { additionalProperties: true }), Empty),
+  "Input.dispatchDragEvent": cmd(Type.Object({}, { additionalProperties: true }), Empty),
+  "Input.insertText": cmd(Type.Object({ text: Type.String() }), Empty),
+
+  "Network.getResponseBody": cmd(
+    Type.Object({ requestId: Type.String() }),
+    Type.Object({ body: Type.String(), base64Encoded: Type.Optional(Type.Boolean()) }),
+  ),
+  "Network.setExtraHTTPHeaders": cmd(
+    Type.Object({ headers: Type.Record(Type.String(), Type.String()) }),
+    Empty,
+  ),
+  "Emulation.setDeviceMetricsOverride": cmd(Type.Object({}, { additionalProperties: true }), Empty),
+  "Accessibility.getFullAXTree": cmd(
+    Type.Object({ depth: Type.Optional(Type.Number()) }, { additionalProperties: true }),
+    Type.Object({ nodes: Type.Array(AxNode) }),
+  ),
+};
+
+export type CdpMethod = keyof typeof COMMANDS;
+export type ParamsOf<M extends CdpMethod> = Static<(typeof COMMANDS)[M]["params"]>;
+export type ResultOf<M extends CdpMethod> = Static<(typeof COMMANDS)[M]["result"]>;
+
+export const decodeResult = <M extends CdpMethod>(
+  method: M,
+  raw: unknown,
+): Result<ResultOf<M>, CdpError> => {
+  const spec = COMMANDS[method];
+  if (spec === undefined) {
+    return err(cdpError("invalid_response", `unknown CDP method`, method));
+  }
+  if (!spec.validate.Check(raw)) {
+    const why = spec.validate.Errors(raw).map((e) => e.message).join("; ");
+    return err(cdpError("invalid_response", why, method));
+  }
+  // Guarded assertion: the check above proves `raw` matches COMMANDS[method].result, which TS cannot correlate from a generic key.
+  return ok(raw as ResultOf<M>);
+};

package/extensions/browser-harness/cdp/console-buffer.ts

@@ -0,0 +1,188 @@
+import { decodeEvent } from "./events";
+import { createRecordStore } from "./record-store";
+
+export type ConsoleLevel = "log" | "info" | "warn" | "error" | "debug";
+
+export type ConsoleRecord = {
+  seq: number;
+  timestampMs: number;
+  level: ConsoleLevel;
+  text: string;
+  source: "console-api" | "log-entry";
+  url?: string;
+  lineNumber?: number;
+  stackTrace?: string;
+};
+
+export type ConsoleFilter = {
+  levels?: ConsoleLevel[];
+  textPattern?: string;
+  sinceSeq?: number;
+  sinceMs?: number;
+  limit?: number;
+};
+
+export type ConsoleDrainResult = {
+  readonly records: ConsoleRecord[];
+  readonly total: number;
+  readonly bufferOverflowed: boolean;
+};
+
+export type ConsoleBuffer = {
+  ingestConsoleApi(p: unknown): void;
+  ingestLogEntry(p: unknown): void;
+  drain(filter: ConsoleFilter): ConsoleDrainResult;
+  clear(): void;
+};
+
+const PER_ARG_CAP = 2000;
+const MAX_STACK_FRAMES = 3;
+
+const compileTextMatcher = (pattern: string): ((text: string) => boolean) => {
+  if (pattern.length >= 2 && pattern.startsWith("/") && pattern.endsWith("/")) {
+    try {
+      const re = new RegExp(pattern.slice(1, -1));
+      return (text) => re.test(text);
+    } catch {}
+  }
+  return (text) => text.includes(pattern);
+};
+
+const truncateArg = (s: string): string =>
+  s.length > PER_ARG_CAP ? s.slice(0, PER_ARG_CAP) + "…" : s;
+
+const stringifyRemoteObject = (
+  arg: { type?: string; subtype?: string; value?: unknown; description?: string; unserializableValue?: string },
+): string => {
+  if (arg.unserializableValue !== undefined) return arg.unserializableValue;
+  if (arg.value !== undefined) {
+    if (typeof arg.value === "string") return arg.value;
+    try {
+      return JSON.stringify(arg.value);
+    } catch {
+      return String(arg.value);
+    }
+  }
+  if (arg.description !== undefined) return arg.description;
+  return arg.type ?? "";
+};
+
+const mapConsoleApiLevel = (type: string | undefined): ConsoleLevel => {
+  switch (type) {
+    case "error":
+    case "assert":
+      return "error";
+    case "warning":
+      return "warn";
+    case "debug":
+    case "trace":
+      return "debug";
+    case "info":
+      return "info";
+    default:
+      return "log";
+  }
+};
+
+const mapLogEntryLevel = (level: string | undefined): ConsoleLevel => {
+  switch (level) {
+    case "error":
+      return "error";
+    case "warning":
+      return "warn";
+    case "verbose":
+      return "debug";
+    default:
+      return "info";
+  }
+};
+
+const formatStackTrace = (
+  st: { callFrames?: ReadonlyArray<{ url?: string; lineNumber?: number; functionName?: string }> } | undefined,
+): string | undefined => {
+  const frames = st?.callFrames;
+  if (!frames || frames.length === 0) return undefined;
+  const top = frames.slice(0, MAX_STACK_FRAMES);
+  const rendered = top.map((f) => {
+    const fn = f.functionName !== undefined && f.functionName !== "" ? f.functionName : "<anonymous>";
+    const loc = f.url !== undefined && f.url !== "" ? `${f.url}:${(f.lineNumber ?? 0) + 1}` : "<unknown>";
+    return `  at ${fn} (${loc})`;
+  });
+  return rendered.join("\n");
+};
+
+export const createConsoleBuffer = (capacity = 500): ConsoleBuffer => {
+  const records = createRecordStore<number, ConsoleRecord>(capacity);
+  let nextSeq = 1;
+
+  const insert = (rec: ConsoleRecord): void => {
+    records.set(rec.seq, rec);
+  };
+
+  return {
+    ingestConsoleApi(p) {
+      const decoded = decodeEvent("Runtime.consoleAPICalled", p);
+      if (!decoded.success) return;
+      const params = decoded.data;
+      const level = mapConsoleApiLevel(params.type);
+      const argTexts = (params.args ?? []).map((a) => truncateArg(stringifyRemoteObject(a)));
+      const text = argTexts.join(" ");
+      const stack = level === "error" || level === "warn" ? formatStackTrace(params.stackTrace) : undefined;
+      const top = params.stackTrace?.callFrames?.[0];
+      const rec: ConsoleRecord = {
+        seq: nextSeq++,
+        timestampMs: Date.now(),
+        level,
+        text,
+        source: "console-api",
+        ...(top?.url !== undefined && top.url !== "" ? { url: top.url } : {}),
+        ...(top?.lineNumber !== undefined ? { lineNumber: top.lineNumber + 1 } : {}),
+        ...(stack !== undefined ? { stackTrace: stack } : {}),
+      };
+      insert(rec);
+    },
+
+    ingestLogEntry(p) {
+      const decoded = decodeEvent("Log.entryAdded", p);
+      const entry = decoded.success ? decoded.data.entry : undefined;
+      if (!entry) return;
+      const level = mapLogEntryLevel(entry.level);
+      const text = truncateArg(entry.text ?? "");
+      const stack = level === "error" || level === "warn" ? formatStackTrace(entry.stackTrace) : undefined;
+      const rec: ConsoleRecord = {
+        seq: nextSeq++,
+        timestampMs: Date.now(),
+        level,
+        text,
+        source: "log-entry",
+        ...(entry.url !== undefined && entry.url !== "" ? { url: entry.url } : {}),
+        ...(entry.lineNumber !== undefined ? { lineNumber: entry.lineNumber + 1 } : {}),
+        ...(stack !== undefined ? { stackTrace: stack } : {}),
+      };
+      insert(rec);
+    },
+
+    drain(filter) {
+      const matchText = filter.textPattern !== undefined ? compileTextMatcher(filter.textPattern) : undefined;
+      const levels = filter.levels && filter.levels.length > 0 ? new Set(filter.levels) : undefined;
+      const cutoff = filter.sinceMs !== undefined ? Date.now() - filter.sinceMs : undefined;
+      const sinceSeq = filter.sinceSeq;
+
+      const matched: ConsoleRecord[] = [];
+      for (const r of records.values()) {
+        if (sinceSeq !== undefined && r.seq <= sinceSeq) continue;
+        if (levels && !levels.has(r.level)) continue;
+        if (cutoff !== undefined && r.timestampMs < cutoff) continue;
+        if (matchText && !matchText(r.text)) continue;
+        matched.push({ ...r });
+      }
+
+      return records.page(matched, filter.limit);
+    },
+
+    clear() {
+      records.clear();
+      nextSeq = 1;
+    },
+  };
+};

package/extensions/browser-harness/cdp/discovery.ts

@@ -0,0 +1,198 @@
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { connect as netConnect } from "node:net";
+import { request as httpRequest } from "node:http";
+import { Type } from "typebox";
+import { Compile } from "typebox/compile";
+import { parseJson } from "../schemas/parse";
+import { type Result, err, ok } from "../util/result";
+import { userDataDirCandidates } from "../profile/paths";
+import { type CdpError, cdpError } from "./errors";
+import { errnoCode } from "../util/guards";
+
+const PORT_PROBE_DEADLINE_MS = 30_000;
+const PORT_PROBE_INTERVAL_MS = 1_000;
+
+const VersionResponse = Type.Object(
+  { webSocketDebuggerUrl: Type.Optional(Type.String()) },
+  { additionalProperties: true },
+);
+
+const versionValidator = Compile(VersionResponse);
+
+export type CdpEndpoint = {
+  readonly wsUrl: string;
+  readonly userDataDir?: string;
+};
+
+const probePort = (port: number): Promise<Result<void, CdpError>> =>
+  new Promise((resolve) => {
+    const sock = netConnect({ host: "127.0.0.1", port });
+    let settled = false;
+    const finish = (r: Result<void, CdpError>): void => {
+      if (settled) return;
+      settled = true;
+      sock.setTimeout(0);
+      sock.destroy();
+      resolve(r);
+    };
+    sock.setTimeout(1000, () => finish(err(cdpError("discovery_failed", "probe timeout"))));
+    sock.once("error", (e) => finish(err(cdpError("discovery_failed", e.message))));
+    sock.once("connect", () => finish(ok(undefined)));
+  });
+
+const waitForPort = async (port: number): Promise<Result<void, CdpError>> => {
+  const end = Date.now() + PORT_PROBE_DEADLINE_MS;
+  let lastMessage = "unknown";
+  while (Date.now() < end) {
+    const probe = await probePort(port);
+    if (probe.success) return probe;
+    lastMessage = probe.error.message;
+    await new Promise((r) => setTimeout(r, PORT_PROBE_INTERVAL_MS));
+  }
+  return err(cdpError(
+    "discovery_failed",
+    `Chrome's remote-debugging page is open, but DevTools is not live yet on 127.0.0.1:${port} — if Chrome opened a profile picker, choose your normal profile first, then tick the checkbox and click Allow if shown (last error: ${lastMessage})`,
+  ));
+};
+
+const isPortLive = async (port: number): Promise<boolean> => (await probePort(port)).success;
+
+// /json/version is authoritative: a stale DevToolsActivePort file may name a browser that has since exited while another now owns the port.
+const queryLiveWsUrl = (port: number, timeoutMs = 1_500): Promise<string | null> =>
+  new Promise<string | null>((resolve) => {
+    const req = httpRequest(
+      { host: "127.0.0.1", port, path: "/json/version", method: "GET", timeout: timeoutMs },
+      (res) => {
+        if (res.statusCode !== 200) {
+          res.resume();
+          resolve(null);
+          return;
+        }
+        const chunks: Buffer[] = [];
+        res.on("data", (c: Buffer) => chunks.push(c));
+        res.on("end", () => {
+          const parsed = parseJson(Buffer.concat(chunks).toString("utf8"), versionValidator);
+          resolve(parsed.success ? parsed.data.webSocketDebuggerUrl ?? null : null);
+        });
+      },
+    );
+    req.on("timeout", () => { req.destroy(); resolve(null); });
+    req.on("error", () => resolve(null));
+    req.end();
+  });
+
+const fallbackPorts = (): ReadonlyArray<number> => {
+  const ports = new Set<number>([9222]);
+  const fromEnv = process.env["BU_CDP_PORTS"];
+  if (fromEnv) {
+    for (const tok of fromEnv.split(",")) {
+      const n = Number(tok.trim());
+      if (Number.isInteger(n) && n > 0 && n < 65536) ports.add(n);
+    }
+  }
+  return Array.from(ports);
+};
+
+type Candidate = {
+  readonly port: number;
+  readonly path: string;
+  readonly mtimeMs: number;
+  readonly userDataDir: string;
+};
+
+// Read here rather than in the client: the daemon owns the only socket to Chrome, so an override the daemon cannot see has no effect.
+export const endpointFromEnv = (env: NodeJS.ProcessEnv = process.env): CdpEndpoint | undefined => {
+  const wsUrl = env["BU_CDP_WS"]?.trim();
+  return wsUrl ? { wsUrl } : undefined;
+};
+
+export const discoverEndpoint = async (): Promise<Result<CdpEndpoint, CdpError>> => {
+  const override = endpointFromEnv();
+  if (override) return ok(override);
+
+  const dirs = userDataDirCandidates();
+
+  const candidates: Candidate[] = [];
+  const readErrors: string[] = [];
+  for (const base of dirs) {
+    const portFile = join(base, "DevToolsActivePort");
+    let raw: string;
+    let mtimeMs = 0;
+    try {
+      raw = await readFile(portFile, "utf8");
+      try {
+        mtimeMs = (await stat(portFile)).mtimeMs;
+      } catch {}
+    } catch (e) {
+      // EPERM/EACCES is common under sandboxes; remember it and fall back to network probing rather than failing the whole discovery.
+      const code = errnoCode(e);
+      if (code === "ENOENT" || code === undefined) continue;
+      if (code === "EPERM" || code === "EACCES") {
+        readErrors.push(`${portFile}: ${code}`);
+        continue;
+      }
+      return err(cdpError("discovery_failed", `failed to read ${portFile}: ${e instanceof Error ? e.message : String(e)}`));
+    }
+    const lines = raw.trim().split("\n");
+    if (lines.length < 2) continue;
+    const port = lines[0]?.trim();
+    const path = lines[1]?.trim();
+    if (!port || !path) continue;
+    // An out-of-range port makes net.connect throw ERR_SOCKET_BAD_PORT synchronously, escaping discoverWsUrl instead of surfacing as a Result error.
+    const portNum = Number(port);
+    if (!Number.isInteger(portNum) || portNum <= 0 || portNum >= 65536) continue;
+    candidates.push({ port: portNum, path, mtimeMs, userDataDir: base });
+  }
+
+  if (candidates.length === 0) {
+    for (const port of fallbackPorts()) {
+      if (!(await isPortLive(port))) continue;
+      const live = await queryLiveWsUrl(port);
+      if (live) return ok({ wsUrl: live });
+    }
+    const permHint = readErrors.length > 0
+      ? `\n\nDevToolsActivePort reads were denied (${readErrors.join(", ")}); if you're running in a sandbox, grant read access to those files or set BU_CDP_WS / BU_CDP_PORTS to bypass file discovery.`
+      : "";
+    return err(cdpError(
+      "discovery_failed",
+      `DevToolsActivePort not found in ${dirs.join(", ")} — open chrome://inspect/#remote-debugging (or brave://inspect, edge://inspect) in your browser, tick the checkbox, click Allow, then retry. Or set BU_CDP_WS to a remote browser endpoint.${permHint}`,
+    ));
+  }
+
+  const byPort = new Map<number, Candidate>();
+  for (const c of candidates) {
+    const prev = byPort.get(c.port);
+    if (!prev || c.mtimeMs > prev.mtimeMs) byPort.set(c.port, c);
+  }
+  const unique = Array.from(byPort.values());
+
+  const liveChecks = await Promise.all(unique.map((c) => isPortLive(c.port)));
+  const liveCandidates = unique.filter((_, i) => liveChecks[i]);
+  const ordered = liveCandidates.length > 0 ? liveCandidates : unique;
+
+  // Some browsers disable the /json/version endpoint when remote debugging is toggled via chrome://inspect rather than a launch flag, hence the DevToolsActivePort fallback.
+  let lastErr: Result<CdpEndpoint, CdpError> | null = null;
+  for (const c of ordered) {
+    const ready = await waitForPort(c.port);
+    if (!ready.success) {
+      lastErr = err(ready.error);
+      continue;
+    }
+    const liveUrl = await queryLiveWsUrl(c.port);
+    return ok({ wsUrl: liveUrl ?? `ws://127.0.0.1:${c.port}${c.path}`, userDataDir: c.userDataDir });
+  }
+
+  for (const port of fallbackPorts()) {
+    if (byPort.has(port) || !(await isPortLive(port))) continue;
+    const liveUrl = await queryLiveWsUrl(port);
+    if (liveUrl) return ok({ wsUrl: liveUrl });
+  }
+
+  return lastErr ?? err(cdpError("discovery_failed", "no live DevTools endpoint among discovered candidates"));
+};
+
+export const discoverWsUrl = async (): Promise<Result<string, CdpError>> => {
+  const endpoint = await discoverEndpoint();
+  return endpoint.success ? ok(endpoint.data.wsUrl) : endpoint;
+};

package/extensions/browser-harness/cdp/errors.ts

@@ -0,0 +1,23 @@
+export type CdpErrorKind =
+  | "transport_closed"
+  | "timeout"
+  | "session_not_found"
+  | "remote_error"
+  | "discovery_failed"
+  | "invalid_response";
+
+export type CdpError = {
+  readonly kind: CdpErrorKind;
+  readonly message: string;
+  readonly method?: string;
+};
+
+// Chrome reports a dead session as a generic protocol error, so the message text is the only signal that a reattach — not a retry — is what will fix it.
+export const classifyRemoteError = (message: string): CdpErrorKind =>
+  message.includes("Session with given id not found") ? "session_not_found" : "remote_error";
+
+export const cdpError = (
+  kind: CdpErrorKind,
+  message: string,
+  method?: string,
+): CdpError => ({ kind, message, ...(method !== undefined ? { method } : {}) });