pi-browser-harness 0.1.0 → 0.3.1

package/src/cdp/session.ts

@@ -0,0 +1,139 @@
+import { type Result, err, ok } from "../util/result";
+import { type CdpError, cdpError } from "./errors";
+import type { DialogInfo } from "./types";
+import { isInternalUrl } from "./types";
+import type { CdpTransport } from "./transport";
+
+export type CdpSession = {
+  attachFirstPage(): Promise<Result<{ readonly targetId: string; readonly sessionId: string }, CdpError>>;
+  switchTo(targetId: string): Promise<Result<void, CdpError>>;
+  current(): { readonly sessionId: string; readonly targetId: string } | null;
+  call(method: string, params?: Record<string, unknown>, opts?: { timeoutMs?: number }): Promise<Result<unknown, CdpError>>;
+  callOnTarget(method: string, params: Record<string, unknown>, sessionId: string, opts?: { timeoutMs?: number }): Promise<Result<unknown, CdpError>>;
+  callBrowser(method: string, params?: Record<string, unknown>, opts?: { timeoutMs?: number }): Promise<Result<unknown, CdpError>>;
+  takeDialog(): DialogInfo | null;
+  drainPageInfoInvalidations(): boolean;
+};
+
+export const createCdpSession = (transport: CdpTransport): CdpSession => {
+  let sessionId: string | null = null;
+  let targetId: string | null = null;
+  let dialog: DialogInfo | null = null;
+  let pageInfoDirty = false;
+
+  let activeConsumer: Promise<void> = Promise.resolve();
+
+  const consumeEvents = async (): Promise<void> => {
+    for await (const ev of transport.events()) {
+      if (ev.method === "Page.javascriptDialogOpening") {
+        const params = ev.params as Partial<DialogInfo> | undefined;
+        dialog = {
+          type: (params?.type as DialogInfo["type"]) ?? "alert",
+          message: params?.message ?? "",
+          ...(params?.defaultPrompt !== undefined ? { defaultPrompt: params.defaultPrompt } : {}),
+        };
+        continue;
+      }
+      // Page.javascriptDialogClosed is intentionally NOT cleared here —
+      // the dialog stays in the buffer until takeDialog() is called.
+      // This prevents fast dismiss flows from dropping a dialog the agent
+      // was about to read. (Fix for spec §7 predictability bug #2.)
+      if (ev.method === "Page.frameNavigated" || ev.method === "Page.loadEventFired") {
+        pageInfoDirty = true;
+      }
+    }
+  };
+
+  const restartConsumer = (): void => {
+    activeConsumer = activeConsumer.then(() => consumeEvents()).catch((e: unknown) => {
+      // The .then() chain calls consumeEvents() which iterates the transport's
+      // events() AsyncIterable. The iterable resolves cleanly on close (returns
+      // {done:true}); any rejection here is an unexpected bug in the event
+      // handler, not a normal termination. Surface it on stderr so it's not lost.
+      console.warn("[pi-browser-harness] CDP event consumer crashed:", e);
+    });
+  };
+
+  restartConsumer();
+  transport.onClose(() => {
+    sessionId = null;
+    targetId = null;
+    pageInfoDirty = false;
+    // Do NOT clear `dialog` here — same rationale as inside consumeEvents:
+    // the agent may have a pending takeDialog() call that should still see it.
+    restartConsumer();
+  });
+
+  // TODO(perf): the four enable calls are sequential here for predictability.
+  // Switching to Promise.all over a single WS pipelines the round-trips and
+  // saves ~3× on tab-switch latency. Defer until session.ts has tests.
+  const enableDomains = async (sid: string): Promise<void> => {
+    for (const d of ["Page", "DOM", "Runtime", "Network"]) {
+      await transport.request(`${d}.enable`, {}, { sessionId: sid });
+    }
+  };
+
+  // CDP response shapes are documented in chromedevtools.github.io but not
+  // available as TypeScript types. We cast `as` from `unknown` only in this
+  // file (the CDP boundary). Each cast is paired with the CDP method that
+  // produced the response. Adding runtime guards for every shape would be
+  // noise — Chrome's protocol is stable enough that a wrong cast surfaces
+  // as a clear Error in normal use.
+  return {
+    async attachFirstPage() {
+      const targets = await transport.request("Target.getTargets", {}, { sessionId: null });
+      if (!targets.success) return targets;
+      const data = targets.data as { targetInfos: ReadonlyArray<{ targetId: string; type: string; url: string }> };
+      let pages = data.targetInfos.filter((t) => t.type === "page" && !isInternalUrl(t.url));
+      if (pages.length === 0) {
+        const created = await transport.request("Target.createTarget", { url: "about:blank" }, { sessionId: null });
+        if (!created.success) return created;
+        const c = created.data as { targetId: string };
+        pages = [{ targetId: c.targetId, type: "page", url: "about:blank" }];
+      }
+      const first = pages[0];
+      if (!first) return err(cdpError("invalid_response", "no page targets after creation"));
+      const attached = await transport.request("Target.attachToTarget", { targetId: first.targetId, flatten: true }, { sessionId: null });
+      if (!attached.success) return attached;
+      const a = attached.data as { sessionId: string };
+      sessionId = a.sessionId;
+      targetId = first.targetId;
+      await enableDomains(a.sessionId);
+      return ok({ targetId: first.targetId, sessionId: a.sessionId });
+    },
+    async switchTo(tid) {
+      const activated = await transport.request("Target.activateTarget", { targetId: tid }, { sessionId: null });
+      if (!activated.success) return activated;
+      const attached = await transport.request("Target.attachToTarget", { targetId: tid, flatten: true }, { sessionId: null });
+      if (!attached.success) return attached;
+      const a = attached.data as { sessionId: string };
+      sessionId = a.sessionId;
+      targetId = tid;
+      pageInfoDirty = true;
+      await enableDomains(a.sessionId);
+      return ok(undefined);
+    },
+    current() {
+      return sessionId && targetId ? { sessionId, targetId } : null;
+    },
+    call(method, params = {}, opts = {}) {
+      return transport.request(method, params, { sessionId, ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}) });
+    },
+    callOnTarget(method, params, sid, opts = {}) {
+      return transport.request(method, params, { sessionId: sid, ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}) });
+    },
+    callBrowser(method, params = {}, opts = {}) {
+      return transport.request(method, params, { sessionId: null, ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}) });
+    },
+    takeDialog() {
+      const d = dialog;
+      dialog = null;
+      return d;
+    },
+    drainPageInfoInvalidations() {
+      const dirty = pageInfoDirty;
+      pageInfoDirty = false;
+      return dirty;
+    },
+  };
+};

package/src/cdp/transport.ts

@@ -0,0 +1,221 @@
+import WebSocket from "ws";
+import { type Result, err, ok } from "../util/result";
+import { type CdpError, cdpError } from "./errors";
+import { isCdpRawMessage } from "./types";
+import type { CdpEvent, CdpRawMessage } from "./types";
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+type Pending = {
+  readonly resolve: (v: Result<unknown, CdpError>) => void;
+  readonly timer: ReturnType<typeof setTimeout>;
+  readonly method: string;
+};
+
+export type CdpTransport = {
+  connect(url: string, opts?: { timeoutMs?: number }): Promise<Result<void, CdpError>>;
+  close(): Promise<void>;
+  request(
+    method: string,
+    params: Record<string, unknown>,
+    opts?: { sessionId?: string | null; timeoutMs?: number },
+  ): Promise<Result<unknown, CdpError>>;
+  // Returns the current event queue's iterator. After close()+reconnect, callers
+  // must re-call events() — the old iterator will have received done:true.
+  events(): AsyncIterable<CdpEvent>;
+  state(): "open" | "closed" | "connecting";
+  onClose(cb: () => void): () => void;
+};
+
+export const createCdpTransport = (): CdpTransport => {
+  let ws: WebSocket | null = null;
+  let nextId = 1;
+  const pending = new Map<number, Pending>();
+  const closeListeners = new Set<() => void>();
+
+  type EventQueue = {
+    readonly push: (e: CdpEvent) => void;
+    readonly end: () => void;
+    readonly iter: AsyncIterable<CdpEvent>;
+  };
+
+  const makeEventQueue = (): EventQueue => {
+    const buf: CdpEvent[] = [];
+    const waiters: Array<(v: IteratorResult<CdpEvent>) => void> = [];
+    let ended = false;
+    return {
+      push(e) {
+        if (ended) return;
+        const w = waiters.shift();
+        if (w) w({ value: e, done: false });
+        else buf.push(e);
+      },
+      end() {
+        ended = true;
+        // value: undefined as unknown as CdpEvent is the correct iterator-protocol
+        // pattern: when done=true the value field is conventionally undefined but
+        // the TS type still requires CdpEvent.
+        for (const w of waiters.splice(0)) w({ value: undefined as unknown as CdpEvent, done: true });
+      },
+      iter: {
+        [Symbol.asyncIterator]() {
+          return {
+            next: (): Promise<IteratorResult<CdpEvent>> =>
+              new Promise((resolve) => {
+                const next = buf.shift();
+                if (next) resolve({ value: next, done: false });
+                else if (ended) resolve({ value: undefined as unknown as CdpEvent, done: true });
+                else waiters.push(resolve);
+              }),
+          };
+        },
+      },
+    };
+  };
+
+  let queue = makeEventQueue();
+
+  const handleMessage = (raw: string): void => {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    if (!isCdpRawMessage(parsed)) return;
+    const msg: CdpRawMessage = parsed;
+    if (msg.id === undefined) {
+      if (msg.method) {
+        queue.push({
+          method: msg.method,
+          params: msg.params,
+          ...(msg.sessionId !== undefined ? { sessionId: msg.sessionId } : {}),
+        });
+      }
+      return;
+    }
+    const p = pending.get(msg.id);
+    if (!p) return;
+    pending.delete(msg.id);
+    clearTimeout(p.timer);
+    if (msg.error) {
+      const kind = msg.error.message.includes("Session with given id not found")
+        ? "session_not_found"
+        : "remote_error";
+      p.resolve(err(cdpError(kind, msg.error.message, p.method)));
+      return;
+    }
+    p.resolve(ok(msg.result));
+  };
+
+  const cleanup = (reason: string): void => {
+    for (const [, p] of pending) {
+      clearTimeout(p.timer);
+      p.resolve(err(cdpError("transport_closed", reason, p.method)));
+    }
+    pending.clear();
+    queue.end();
+    queue = makeEventQueue();
+    for (const cb of closeListeners) cb();
+  };
+
+  return {
+    connect(url, opts = {}): Promise<Result<void, CdpError>> {
+      const timeoutMs = opts.timeoutMs ?? 10_000;
+      return new Promise((resolve) => {
+        let settled = false;
+        const settle = (r: Result<void, CdpError>): void => {
+          if (settled) return;
+          settled = true;
+          resolve(r);
+        };
+        try {
+          ws = new WebSocket(url);
+        } catch (e) {
+          settle(err(cdpError("transport_closed", e instanceof Error ? e.message : String(e))));
+          return;
+        }
+        const timer = setTimeout(() => {
+          ws?.close();
+          ws = null;
+          settle(err(cdpError("timeout", `CDP WebSocket connection timed out after ${timeoutMs}ms`)));
+        }, timeoutMs);
+        ws.onopen = () => {
+          clearTimeout(timer);
+          settle(ok(undefined));
+        };
+        ws.onmessage = (ev: WebSocket.MessageEvent) => {
+          const data = ev.data;
+          handleMessage(typeof data === "string" ? data : data.toString());
+        };
+        ws.onerror = () => {
+          clearTimeout(timer);
+          settle(err(cdpError("transport_closed", "CDP WebSocket error during connection")));
+        };
+        ws.onclose = () => {
+          clearTimeout(timer);
+          ws = null;
+          cleanup("WebSocket closed");
+          // If onopen already settled the connect promise, this settle is a no-op
+          // (guarded by `settled`). cleanup() above still runs unconditionally so
+          // pending requests are rejected and the event queue is rotated.
+          settle(err(cdpError("transport_closed", "CDP WebSocket closed")));
+        };
+      });
+    },
+    close(): Promise<void> {
+      if (ws) {
+        try { ws.close(1000, "Shutdown"); } catch { /* best effort */ }
+        ws = null;
+      }
+      cleanup("close() called");
+      return Promise.resolve();
+    },
+    request(method, params, opts = {}): Promise<Result<unknown, CdpError>> {
+      const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+      const sessionId = opts.sessionId ?? null;
+      if (!ws || ws.readyState !== WebSocket.OPEN) {
+        return Promise.resolve(err(cdpError("transport_closed", "Browser not connected. Is Chrome running?", method)));
+      }
+      // Bind to a local const so the non-null is guaranteed even across microtasks
+      // between the readyState check and the send() call.
+      const sock = ws;
+      const id = nextId++;
+      const payload: Record<string, unknown> = { id, method, params };
+      if (sessionId) payload["sessionId"] = sessionId;
+      const json = JSON.stringify(payload);
+      return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+          pending.delete(id);
+          resolve(err(cdpError("timeout", `CDP timeout after ${timeoutMs}ms: ${method}`, method)));
+        }, timeoutMs);
+        pending.set(id, { resolve, timer, method });
+        try {
+          sock.send(json);
+        } catch (e) {
+          clearTimeout(timer);
+          pending.delete(id);
+          resolve(err(cdpError("transport_closed", e instanceof Error ? e.message : String(e), method)));
+        }
+      });
+    },
+    events(): AsyncIterable<CdpEvent> {
+      // Single-consumer: each connection's event stream may be iterated by
+      // exactly one for-await loop. Calling events() multiple times returns
+      // the same iterable; the second consumer will silently steal events
+      // from the first. After a reconnect, the previous iterator is ended
+      // and callers must re-call events() to receive new events.
+      return queue.iter;
+    },
+    state(): "open" | "closed" | "connecting" {
+      if (!ws) return "closed";
+      if (ws.readyState === WebSocket.CONNECTING) return "connecting";
+      if (ws.readyState === WebSocket.OPEN) return "open";
+      return "closed";
+    },
+    onClose(cb): () => void {
+      closeListeners.add(cb);
+      return () => closeListeners.delete(cb);
+    },
+  };
+};

package/src/cdp/types.ts

@@ -0,0 +1,72 @@
+export type CdpEvent = {
+  readonly method: string;
+  readonly params: unknown;
+  readonly sessionId?: string;
+};
+
+export type CdpRawMessage = {
+  readonly id?: number;
+  readonly method?: string;
+  readonly params?: Record<string, unknown>;
+  readonly result?: unknown;
+  readonly error?: { readonly message: string; readonly code?: number };
+  readonly sessionId?: string;
+};
+
+export type DialogInfo = {
+  readonly type: "alert" | "confirm" | "prompt" | "beforeunload";
+  readonly message: string;
+  readonly defaultPrompt?: string;
+};
+
+export type TabInfo = {
+  readonly targetId: string;
+  readonly title: string;
+  readonly url: string;
+};
+
+export type PageInfo = {
+  readonly url: string;
+  readonly title: string;
+  readonly width: number;
+  readonly height: number;
+  readonly scrollX: number;
+  readonly scrollY: number;
+  readonly pageWidth: number;
+  readonly pageHeight: number;
+};
+
+export type DaemonStatus = {
+  readonly alive: boolean;
+  readonly sessionId: string | null;
+  readonly namespace: string;
+  readonly remoteBrowserId?: string;
+};
+
+const INTERNAL_PREFIXES: ReadonlyArray<string> = [
+  "chrome://", "chrome-untrusted://", "devtools://", "chrome-extension://", "about:",
+];
+
+export const isInternalUrl = (url: string): boolean =>
+  INTERNAL_PREFIXES.some((p) => url.startsWith(p));
+
+const isObject = (v: unknown): v is Readonly<Record<string, unknown>> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+export const isCdpRawMessage = (v: unknown): v is CdpRawMessage => {
+  if (!isObject(v)) return false;
+  const id = v["id"];
+  if (id !== undefined && typeof id !== "number") return false;
+  const method = v["method"];
+  if (method !== undefined && typeof method !== "string") return false;
+  const sessionId = v["sessionId"];
+  if (sessionId !== undefined && typeof sessionId !== "string") return false;
+  const errVal = v["error"];
+  if (errVal !== undefined) {
+    if (!isObject(errVal)) return false;
+    if (typeof errVal["message"] !== "string") return false;
+    const code = errVal["code"];
+    if (code !== undefined && typeof code !== "number") return false;
+  }
+  return true;
+};

package/src/client.ts

@@ -0,0 +1,232 @@
+import { type Result, err, ok } from "./util/result";
+import { safeJs } from "./util/js-template";
+import { discoverWsUrl } from "./cdp/discovery";
+import { type CdpError, cdpError } from "./cdp/errors";
+import type { CdpTransport } from "./cdp/transport";
+import { createCdpTransport } from "./cdp/transport";
+import { type CdpSession, createCdpSession } from "./cdp/session";
+import type { DaemonStatus, DialogInfo, PageInfo, TabInfo } from "./cdp/types";
+
+export type BrowserClientOptions = {
+  readonly namespace: string;
+  readonly remote?: { readonly cdpUrl: string; readonly browserId: string };
+};
+
+export type BrowserClient = {
+  readonly namespace: string;
+  ensureAlive(): Promise<Result<void, CdpError>>;
+  status(): DaemonStatus;
+  start(): Promise<Result<void, CdpError>>;
+  stop(): Promise<void>;
+  evaluateJs(expression: string, sessionId?: string): Promise<Result<unknown, CdpError>>;
+  pageInfo(): Promise<Result<PageInfo | { readonly dialog: DialogInfo }, CdpError>>;
+  takeDialog(): DialogInfo | null;
+  listTabs(includeInternal?: boolean): Promise<Result<ReadonlyArray<TabInfo>, CdpError>>;
+  switchTab(targetId: string): Promise<Result<void, CdpError>>;
+  newTab(url?: string): Promise<Result<string, CdpError>>;
+  current(): { readonly sessionId: string; readonly targetId: string } | null;
+  session(): CdpSession;
+  transport(): CdpTransport;
+};
+
+const HEALTH_TTL_MS = 30_000;
+const PAGE_INFO_TTL_MS = 1_000;
+
+const parsePageInfoPayload = (v: unknown): Result<PageInfo, CdpError> => {
+  if (typeof v !== "object" || v === null) {
+    return err(cdpError("invalid_response", "page info payload is not an object"));
+  }
+  const o = v as Readonly<Record<string, unknown>>;
+  const fields: ReadonlyArray<readonly [string, "string" | "number"]> = [
+    ["url", "string"], ["title", "string"],
+    ["w", "number"], ["h", "number"],
+    ["sx", "number"], ["sy", "number"],
+    ["pw", "number"], ["ph", "number"],
+  ];
+  for (const [k, t] of fields) {
+    if (typeof o[k] !== t) {
+      return err(cdpError("invalid_response", `page info field ${k} has wrong type (expected ${t})`));
+    }
+  }
+  return ok({
+    url: o["url"] as string,
+    title: o["title"] as string,
+    width: o["w"] as number,
+    height: o["h"] as number,
+    scrollX: o["sx"] as number,
+    scrollY: o["sy"] as number,
+    pageWidth: o["pw"] as number,
+    pageHeight: o["ph"] as number,
+  });
+};
+
+export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient => {
+  const transport = createCdpTransport();
+  const session = createCdpSession(transport);
+  let lastHealth = 0;
+  let pageCache: { readonly info: PageInfo; readonly at: number } | null = null;
+  let remote: BrowserClientOptions["remote"] | null = opts.remote ?? null;
+
+  const start = async (): Promise<Result<void, CdpError>> => {
+    if (transport.state() === "open" && session.current()) return ok(undefined);
+    const envUrl = process.env["BU_CDP_WS"];
+    let wsUrl: string;
+    if (remote?.cdpUrl) {
+      wsUrl = remote.cdpUrl;
+    } else if (envUrl) {
+      wsUrl = envUrl;
+    } else {
+      const discovered = await discoverWsUrl();
+      if (!discovered.success) return discovered;
+      wsUrl = discovered.data;
+    }
+    const connected = await transport.connect(wsUrl, { timeoutMs: 10_000 });
+    if (!connected.success) return connected;
+    if (!remote) {
+      remote = { cdpUrl: wsUrl, browserId: wsUrl.split("/").pop() ?? "unknown" };
+    }
+    const attached = await session.attachFirstPage();
+    if (!attached.success) {
+      await transport.close();
+      return attached;
+    }
+    lastHealth = Date.now();
+    pageCache = null;
+    return ok(undefined);
+  };
+
+  const stop = async (): Promise<void> => {
+    await transport.close();
+    pageCache = null;
+    lastHealth = 0;
+  };
+
+  const ensureAlive = async (): Promise<Result<void, CdpError>> => {
+    if (transport.state() !== "open" || !session.current()) {
+      await stop();
+      return start();
+    }
+    if (Date.now() - lastHealth < HEALTH_TTL_MS) return ok(undefined);
+    const probe = await transport.request("Target.getTargets", {}, { sessionId: null, timeoutMs: 2_000 });
+    if (!probe.success) {
+      await stop();
+      return start();
+    }
+    lastHealth = Date.now();
+    // Verify the page session is still responsive (handles the case where the
+    // browser transport is alive but the page target crashed, e.g. localhost died).
+    const jsProbe = await session.call("Runtime.evaluate", {
+      expression: "1", returnByValue: true,
+    }, { timeoutMs: 2_000 });
+    if (!jsProbe.success && jsProbe.error.kind === "session_not_found") {
+      const reattached = await session.attachFirstPage();
+      if (reattached.success) {
+        pageCache = null;
+        return ok(undefined);
+      }
+      await stop();
+      return start();
+    }
+    return ok(undefined);
+  };
+
+  const evaluateJs = async (expression: string, sessionId?: string): Promise<Result<unknown, CdpError>> => {
+    // Heuristic IIFE wrap: legacy convenience that lets agents write
+    // `return foo` instead of `(() => foo)()`. False-positive on substring
+    // `"return "` inside string literals or comments — agents that hit this
+    // can pass an explicit IIFE instead.
+    const wrapped = expression.includes("return ") && !expression.trim().startsWith("(")
+      ? `(function(){${expression}})()`
+      : expression;
+    const r = sessionId
+      ? await session.callOnTarget("Runtime.evaluate", { expression: wrapped, returnByValue: true, awaitPromise: true }, sessionId)
+      : await session.call("Runtime.evaluate", { expression: wrapped, returnByValue: true, awaitPromise: true });
+    if (!r.success) return r;
+    const data = r.data as { result?: { value?: unknown }; exceptionDetails?: unknown };
+    if (data.exceptionDetails) {
+      return err(cdpError("remote_error", `JS evaluation failed: ${JSON.stringify(data.exceptionDetails)}`, "Runtime.evaluate"));
+    }
+    return ok(data.result?.value);
+  };
+
+  const readPageInfo = async (): Promise<Result<PageInfo, CdpError>> => {
+    const dirty = session.drainPageInfoInvalidations();
+    if (pageCache && !dirty && Date.now() - pageCache.at < PAGE_INFO_TTL_MS) return ok(pageCache.info);
+    const expr = safeJs`JSON.stringify({url:location.href,title:document.title,w:innerWidth,h:innerHeight,sx:scrollX,sy:scrollY,pw:document.documentElement.scrollWidth,ph:document.documentElement.scrollHeight})`;
+    const raw = await evaluateJs(expr);
+    if (!raw.success) return raw;
+    if (typeof raw.data !== "string") return err(cdpError("invalid_response", "page info evaluation did not return a string"));
+    let parsedRaw: unknown;
+    try {
+      parsedRaw = JSON.parse(raw.data);
+    } catch (e) {
+      return err(cdpError("invalid_response", `page info JSON.parse failed: ${e instanceof Error ? e.message : String(e)}`));
+    }
+    const info = parsePageInfoPayload(parsedRaw);
+    if (!info.success) return info;
+    pageCache = { info: info.data, at: Date.now() };
+    return ok(info.data);
+  };
+
+  const pageInfo = async (): Promise<Result<PageInfo | { readonly dialog: DialogInfo }, CdpError>> => {
+    const d = session.takeDialog();
+    if (d) return ok({ dialog: d });
+    return readPageInfo();
+  };
+
+  const listTabs = async (includeInternal = true): Promise<Result<ReadonlyArray<TabInfo>, CdpError>> => {
+    const r = await session.callBrowser("Target.getTargets");
+    if (!r.success) return r;
+    const data = r.data as { targetInfos: ReadonlyArray<{ targetId: string; type: string; title: string; url: string }> };
+    const tabs = data.targetInfos
+      .filter((t) => t.type === "page")
+      .filter((t) => includeInternal || !t.url.startsWith("chrome://"))
+      .map((t): TabInfo => ({ targetId: t.targetId, title: t.title, url: t.url }));
+    return ok(tabs);
+  };
+
+  const switchTab = async (targetId: string): Promise<Result<void, CdpError>> => {
+    const r = await session.switchTo(targetId);
+    if (!r.success) return r;
+    pageCache = null;
+    // Best-effort: mark the tab title with a green circle so the user can
+    // see which tab the agent attached to. CSP or detached frames may
+    // block the eval; we don't surface that as a switchTab failure.
+    await session.call("Runtime.evaluate", {
+      expression: safeJs`if(!document.title.startsWith('🟢'))document.title='🟢 '+document.title`,
+    });
+    return ok(undefined);
+  };
+
+  const newTab = async (url?: string): Promise<Result<string, CdpError>> => {
+    const created = await session.callBrowser("Target.createTarget", { url: "about:blank" });
+    if (!created.success) return created;
+    const c = created.data as { targetId: string };
+    const switched = await switchTab(c.targetId);
+    if (!switched.success) return switched;
+    if (url && url !== "about:blank") {
+      const nav = await session.call("Page.navigate", { url });
+      if (!nav.success) return nav;
+      pageCache = null;
+    }
+    return ok(c.targetId);
+  };
+
+  const status = (): DaemonStatus => ({
+    alive: transport.state() === "open" && session.current() !== null,
+    sessionId: session.current()?.sessionId ?? null,
+    namespace: opts.namespace,
+    ...(remote?.browserId !== undefined ? { remoteBrowserId: remote.browserId } : {}),
+  });
+
+  return {
+    namespace: opts.namespace,
+    ensureAlive, status, start, stop,
+    evaluateJs, pageInfo,
+    takeDialog: () => session.takeDialog(),
+    listTabs, switchTab, newTab,
+    current: () => session.current(),
+    session: () => session,
+    transport: () => transport,
+  };
+};