pi-browser-harness 0.10.2 → 0.11.0

package/src/util/guards.ts

@@ -0,0 +1,30 @@
+export const isRecord = (v: unknown): v is Readonly<Record<string, unknown>> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+export const asRecord = (v: unknown): Readonly<Record<string, unknown>> | undefined =>
+  isRecord(v) ? v : undefined;
+
+export const asString = (v: unknown): string | undefined => (typeof v === "string" ? v : undefined);
+
+export const asNumber = (v: unknown): number | undefined => (typeof v === "number" ? v : undefined);
+
+export const asBoolean = (v: unknown): boolean | undefined => (typeof v === "boolean" ? v : undefined);
+
+export const asArrayOf = <T>(
+  v: unknown,
+  item: (x: unknown) => T | undefined,
+): ReadonlyArray<T> | undefined => {
+  if (!Array.isArray(v)) return undefined;
+  const out: T[] = [];
+  for (const x of v) {
+    const parsed = item(x);
+    if (parsed === undefined) return undefined;
+    out.push(parsed);
+  }
+  return out;
+};
+
+export const errnoCode = (e: unknown): string | undefined => {
+  if (!(e instanceof Error) || !("code" in e)) return undefined;
+  return asString(e.code);
+};

package/src/util/js-template.ts

@@ -1,19 +1,4 @@
-/**
- * Build a JavaScript source string with safely-interpolated values.
- * Every interpolated value is JSON.stringify'd, so strings, numbers,
- * objects, and special characters all become valid JS literals.
- *
- * This is the ONLY supported way to interpolate untrusted values into
- * evaluation source — never use raw template literals for JS that
- * crosses the CDP boundary. The static parts of the template (the
- * `strings` array) must remain hard-coded; only the `${...}` slots
- * are sanitized.
- *
- * Values must be JSON-serializable: BigInt and Symbol throw at runtime;
- * functions and undefined serialize to `undefined`/omitted, which yields
- * a ReferenceError when evaluated. Pass strings, numbers, booleans,
- * plain objects, or arrays.
- */
+// The ONLY supported way to interpolate untrusted values into evaluation source — never use raw template literals for JS crossing the CDP boundary.
 export const safeJs = (
   strings: TemplateStringsArray,
   ...values: ReadonlyArray<unknown>

package/src/util/mutex.ts

@@ -1,8 +1,3 @@
-/**
- * Lightweight async mutex (~10 lines). Acquire returns a release function.
- * When the mutex is free, acquire() resolves immediately. When held,
- * callers are queued and execute serially in FIFO order.
- */
 export type Mutex = {
   acquire(): Promise<() => void>;
 };

package/src/util/result.ts

@@ -7,9 +7,3 @@ export const err = <E>(error: E): Result<never, E> => ({ success: false, error }
 
 export const map = <T, U, E>(r: Result<T, E>, f: (t: T) => U): Result<U, E> =>
   r.success ? ok(f(r.data)) : r;
-
-export const andThen = <T, U, E>(r: Result<T, E>, f: (t: T) => Result<U, E>): Result<U, E> =>
-  r.success ? f(r.data) : r;
-
-export const mapErr = <T, E, F>(r: Result<T, E>, f: (e: E) => F): Result<T, F> =>
-  r.success ? r : err(f(r.error));

package/src/util/sharp-shim.ts

@@ -1,10 +1,4 @@
-// Typed minimal shim for the optional `sharp` dependency. Sharp is a heavy
-// native module not installed in every workspace; we import dynamically and
-// distinguish "missing" (no install) from "error" (installed but threw).
-//
-// We declare only the surface we use. The dynamic import returns `unknown`
-// at the boundary; the cast inside loadSharp() is the documented escape
-// hatch — every other consumer sees the typed SharpFactory.
+// `sharp` is an optional dependency not installed in every workspace, so the import must stay dynamic and unresolvable to tsc.
 
 export type SharpInstance = {
   metadata(): Promise<{ width?: number; height?: number }>;
@@ -20,26 +14,25 @@ export type SharpLoad =
   | { readonly kind: "missing" }
   | { readonly kind: "error"; readonly message: string };
 
+const SHARP_SPECIFIER: string = "sharp";
+
+const MISSING_MODULE_MARKERS: ReadonlyArray<string> = [
+  "Cannot find module",
+  "MODULE_NOT_FOUND",
+  "ERR_MODULE_NOT_FOUND",
+];
+
 export const loadSharp = async (): Promise<SharpLoad> => {
   let mod: unknown;
   try {
-    // sharp is an optional dependency; it may not be installed.
-    // @ts-ignore — optional peer dependency not required at compile time
-    mod = await import("sharp");
+    mod = await import(SHARP_SPECIFIER);
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
-    if (
-      msg.includes("Cannot find module") ||
-      msg.includes("MODULE_NOT_FOUND") ||
-      msg.includes("ERR_MODULE_NOT_FOUND")
-    ) {
-      return { kind: "missing" };
-    }
+    if (MISSING_MODULE_MARKERS.some((marker) => msg.includes(marker))) return { kind: "missing" };
     return { kind: "error", message: msg };
   }
   if (mod === null || mod === undefined) return { kind: "missing" };
-  // The CommonJS sharp module's default export IS the factory. ESM-wrapped
-  // sharp puts it on .default. Probe both.
+  // The CommonJS sharp module's default export IS the factory; ESM-wrapped sharp puts it on .default.
   const m = mod as { default?: unknown };
   const candidate: unknown = typeof m.default === "function" ? m.default : mod;
   if (typeof candidate !== "function") {

package/src/util/tool.ts

@@ -1,7 +1,6 @@
 import type { TSchema, Static } from "typebox";
 import type {
   AgentToolResult,
-  AgentToolUpdateCallback,
   ExtensionAPI,
   ExtensionContext,
   Theme,
@@ -9,8 +8,7 @@ import type {
   ToolRenderResultOptions,
 } from "@mariozechner/pi-coding-agent";
 import type { Component } from "@mariozechner/pi-tui";
-import { access } from "node:fs/promises";
-import { DAEMON_SOCKET_PATH } from "../daemon/protocol";
+import { daemonSocketMayExist } from "../daemon/spawn";
 import type { BrowserClient } from "../client";
 import type { Result } from "./result";
 
@@ -55,17 +53,11 @@ export type BrowserToolDefinition<S extends TSchema> = {
   readonly handler: ToolHandler<S>;
   readonly renderCall?: (args: Static<S>, theme: Theme) => Component;
   readonly renderResult?: (result: AgentToolResult<unknown>, expanded: boolean, theme: Theme) => Component;
-  /** If true, the tool acquires the client's mutation mutex before executing.
-   *  This ensures that two serialized tools never run concurrently,
-   *  preventing race conditions on shared CDP session/page state. */
-  readonly serialized?: boolean;
+  readonly concurrency: "serialized" | "parallel";
   readonly ensureAlive?: boolean;
 };
 
-// Type-erased entry for the registry's heterogeneous TOOLS array.
-// renderCall accepts `never` so any concrete args type satisfies it via
-// function-parameter contravariance (a handler that takes SpecificT is
-// assignable to one that takes never, because never is a subtype of everything).
+// renderCall accepts `never` so any concrete args type satisfies it via function-parameter contravariance.
 export type AnyBrowserToolDefinition = Omit<BrowserToolDefinition<TSchema>, "renderCall" | "renderResult"> & {
   readonly renderCall?: (args: never, theme: Theme) => Component;
   readonly renderResult?: (result: AgentToolResult<unknown>, expanded: boolean, theme: Theme) => Component;
@@ -78,10 +70,12 @@ export const defineBrowserTool = <S extends TSchema>(
 type OkDetails = { readonly ok: true } & Readonly<Record<string, unknown>>;
 type ErrDetails = { readonly ok: false; readonly kind: ToolErrKind; readonly message: string } & Readonly<Record<string, unknown>>;
 
+type ErrorFlagged<D> = AgentToolResult<D> & { readonly isError?: boolean };
+
 const toToolResult = (
   r: Result<ToolOk, ToolErr>,
   toolName: string,
-): AgentToolResult<OkDetails | ErrDetails> => {
+): ErrorFlagged<OkDetails | ErrDetails> => {
   if (r.success) {
     const details: OkDetails = { ok: true, ...(r.data.details ?? {}) };
     return {
@@ -96,10 +90,7 @@ const toToolResult = (
     ...(r.error.details ?? {}),
   };
   return {
-    // isError is an extension the pi-coding-agent runtime picks up from the result object;
-    // AgentToolResult<T> itself doesn't declare it but the runtime reads it via duck-typing.
-    // We cast through unknown to avoid widening the return type.
-    ...(({ isError: true }) as unknown as object),
+    isError: true,
     content: [{ type: "text", text: `${toolName} failed (${r.error.kind}): ${r.error.message}` }],
     details,
   };
@@ -110,10 +101,9 @@ export const registerBrowserTool = (
   client: BrowserClient,
   def: AnyBrowserToolDefinition,
 ): void => {
-  // AnyBrowserToolDefinition is type-erased; we recover the schema-typed surface
-  // by casting def to the generic form. The cast is safe because defineBrowserTool
-  // ensures the handler, parameters, and renderCall were all created with the same S.
   type S = TSchema;
+  const defRenderCall = def.renderCall;
+  const defRenderResult = def.renderResult;
   const td: ToolDefinition<S> = {
     name: def.name,
     label: def.label,
@@ -121,35 +111,26 @@ export const registerBrowserTool = (
     promptSnippet: def.promptSnippet,
     promptGuidelines: [...def.promptGuidelines],
     parameters: def.parameters,
-    ...(def.renderCall
+    ...(defRenderCall
       ? {
           renderCall: (args: Static<S>, theme: Theme, _ctx: Parameters<NonNullable<ToolDefinition<S>["renderCall"]>>[2]) =>
-            // Non-null assertion safe: this branch only runs when renderCall was provided.
-            // Cast from never->Component to unknown->Component: safe because at runtime
-            // args is always the concrete Static<S> value the tool was defined with.
-            (def.renderCall as (args: unknown, theme: Theme) => Component)(args, theme),
+            // Sanctioned cast: at runtime args is always the concrete Static<S> value the tool was defined with.
+            (defRenderCall as (args: unknown, theme: Theme) => Component)(args, theme),
         }
       : {}),
-    ...(def.renderResult
+    ...(defRenderResult
       ? {
           renderResult: (
             result: AgentToolResult<unknown>,
             options: ToolRenderResultOptions,
             theme: Theme,
             _ctx: Parameters<NonNullable<ToolDefinition<S>["renderResult"]>>[3],
-          ) =>
-            // Non-null assertion safe: this branch only runs when renderResult was provided.
-            def.renderResult!(result, options.expanded ?? false, theme),
+          ) => defRenderResult(result, options.expanded ?? false, theme),
         }
       : {}),
     async execute(_toolCallId, args, signal, onUpdate, extensionCtx) {
       if (def.ensureAlive !== false) {
-        // Check daemon socket exists before attempting browser control.
-        // If missing, the user hasn't run /browser-setup yet. Return a clear
-        // error so the agent knows to direct the user to initialize.
-        try {
-          await access(DAEMON_SOCKET_PATH);
-        } catch {
+        if (!(await daemonSocketMayExist())) {
           return toToolResult(
             {
               success: false,
@@ -169,12 +150,8 @@ export const registerBrowserTool = (
           );
         }
       }
-      // Serialized tools acquire the client's mutation mutex so that only one
-      // mutation tool runs at a time. Observation tools skip this and run freely
-      // in parallel. AbortSignal is checked after acquiring the lock so that a
-      // cancelled task doesn't hold the mutex forever.
       let release: (() => void) | undefined;
-      if (def.serialized) {
+      if (def.concurrency !== "parallel") {
         const acquire = await client.mutationMutex().acquire();
         release = acquire;
         if (signal?.aborted) {
@@ -191,13 +168,11 @@ export const registerBrowserTool = (
           signal,
           onUpdate: (u) => {
             if (onUpdate) {
-              // AgentToolUpdateCallback expects AgentToolResult<TDetails>; we use unknown for TDetails.
               const update: AgentToolResult<OkDetails> = {
                 content: [{ type: "text", text: u.text }],
                 details: { ok: true, ...(u.details ?? {}) },
               };
-              // Cast needed: onUpdate is AgentToolUpdateCallback<unknown> (generic TDetails).
-              (onUpdate as AgentToolUpdateCallback<OkDetails>)(update);
+              onUpdate(update);
             }
           },
           extensionCtx,

package/src/util/truncate.ts

@@ -33,3 +33,9 @@ export const applyTruncation = async (output: string, prefix: string): Promise<T
   const text = `${t.content}\n\n[Output truncated: ${t.outputLines} of ${t.totalLines} lines (${formatSize(t.outputBytes)} of ${formatSize(t.totalBytes)}). ${formatSize(omitted)} omitted. Full output: ${file}]`;
   return { text, fullOutputPath: file, wasTruncated: true };
 };
+
+export const formatBytes = (n: number): string => {
+  if (n >= 1_048_576) return `${(n / 1_048_576).toFixed(1)} MB`;
+  if (n >= 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${n} B`;
+};

package/tsconfig.json

@@ -1,21 +1,6 @@
 {
+  "extends": "./tsconfig.base.json",
   "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "strict": true,
-    "noImplicitAny": true,
-    "strictNullChecks": true,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "noImplicitReturns": true,
-    "noFallthroughCasesInSwitch": true,
-    "noUncheckedIndexedAccess": true,
-    "exactOptionalPropertyTypes": true,
-    "noPropertyAccessFromIndexSignature": true,
-    "forceConsistentCasingInFileNames": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
     "outDir": "./dist",
     "rootDir": "./src",
     "declaration": true,

package/skills/deep-research/SKILL.md

@@ -1,66 +0,0 @@
----
-name: deep-research
-description: Use when the user asks you to research a topic on the web, do deep research, investigate something across multiple sources, or produce a cited report / literature review from the live web. Decomposes the question, fans out isolated web-search-researcher subagents (one per sub-question) that scrape the real browser, then synthesizes a source-cited Markdown report. Trigger phrases include "research", "deep research", "look this up and cite sources", "investigate", "compare X and Y with sources".
----
-
-# Deep Research
-
-Turn a research question into a **cited Markdown report** by fanning out to isolated `web-search-researcher` subagents that use the real browser, then synthesizing their distilled findings. Every claim in the final report carries a source link.
-
-This runs on two browser tools — `browser_web_search` (ranked SERP, links only) and `browser_read_page` (URL → clean article text) — used *inside the subagents*, not by you directly. Both tools open their own isolated tabs, so **the fan-out never disturbs the user's tabs or current page.** You do not need `/browser-setup` to have been run by you; if the browser isn't connected the subagents' first tool call will report `not_connected` — relay that and ask the user to run `/browser-setup`.
-
-## Workflow
-
-### 1. Decompose
-
-Break the question into **3–6 focused sub-questions**, each independently answerable from the web. Cover the distinct facets — definitions, current state, competing options, trade-offs, recent changes — not slight rewordings of the same thing. Aim for coverage: if you synthesized perfect answers to all sub-questions, the original question should be fully answered.
-
-State the sub-questions to the user before dispatching (a short numbered list) so the plan is visible.
-
-### 2. Fan out
-
-Dispatch **one `web-search-researcher` subagent per sub-question**, in parallel where the runtime allows. Each subagent runs in isolated context and returns a distilled, source-linked finding (claims + urls) — not raw pages. Give each subagent exactly one sub-question plus any constraints (recency, specific ecosystem, authoritative sources to prefer).
-
-Do not do the searching yourself — that is the subagents' job, and their isolation is what keeps your context clean enough to synthesize well.
-
-### 3. Assess coverage — loop with a hard ceiling
-
-After each round of findings, self-assess: **is every sub-question answered, or did findings surface new gaps worth a follow-up search?**
-
-- If gaps remain and you are under the ceiling, dispatch a second round of researchers targeting only the gaps (rephrased or newly discovered sub-questions).
-- **Hard ceiling:** at most **2 rounds** and **8 researcher subagents total**. When you hit either limit, stop searching, synthesize with what you have, and list the unresolved gaps explicitly in the report. Never loop indefinitely chasing completeness.
-
-Handle subagent-reported tool failures:
-- A subagent reporting a `browser_web_search` `invalid_state` with `reason: "captcha"` means a bot wall. **Surface this to the user immediately** and do not spawn a tight retry loop — ask whether to continue, wait, or narrow scope.
-- `reason: "no_results"` is already handled inside the subagent (one rephrase); if it still comes back empty, treat that sub-question as a gap.
-
-### 4. Synthesize a cited report
-
-Merge the distilled findings into a **Markdown report written to a file** (e.g. `research-<topic-slug>.md` in the working directory — tell the user the path). Structure:
-
-```
-# {The research question}
-
-## Summary
-{A few paragraphs answering the question, synthesized across sources.}
-
-## {Sub-topic / sub-question 1}
-{Findings, in prose. Every claim carries a source link inline: … as shown in [Title](url).}
-
-## {Sub-topic 2}
-...
-
-## Open questions / gaps
-{Anything the ceiling left unresolved, or where sources conflicted.}
-
-## Sources
-{Deduplicated list of every URL cited, with titles.}
-```
-
-Rules for the report:
-- **Every factual claim carries a source link** — inline `[title](url)`. No unsourced assertions.
-- **Attribute conflicts.** Where sources disagree, present both and cite each.
-- **Distinguish synthesis from quotation.** Don't fabricate precision the sources didn't provide.
-- **Be honest about gaps.** The gaps section is mandatory when the ceiling cut off coverage — an incomplete-but-honest report beats a complete-looking-but-padded one.
-
-After writing the file, give the user a short chat summary and the file path — don't paste the whole report into the conversation.

package/src/cdp/event-queue.ts

@@ -1,128 +0,0 @@
-/**
- * Shared transport primitives for CdpTransport implementations.
- *
- * Both the WebSocket transport (transport.ts, talking to Chrome directly) and
- * the daemon transport (daemon-transport.ts, talking to the daemon over a Unix
- * socket) need an identical single-consumer async event queue plus the same
- * pending-request bookkeeping. This module is the single source of truth for
- * that shared machinery.
- */
-
-import { type Result, err } from "../util/result";
-import { type CdpError, cdpError } from "./errors";
-import type { CdpEvent } from "./types";
-
-export type CdpResult = Result<unknown, CdpError>;
-
-/**
- * A single-consumer async queue of CDP events.
- *
- * `push` enqueues an event (dropped silently after `end`). `end` terminates the
- * stream — any pending and future iterator `next()` calls resolve `done:true`.
- * `iter` is the AsyncIterable consumed by one for-await loop; a second consumer
- * would silently steal events from the first.
- */
-export type EventQueue = {
-  readonly push: (e: CdpEvent) => void;
-  readonly end: () => void;
-  readonly iter: AsyncIterable<CdpEvent>;
-};
-
-export 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);
-            }),
-        };
-      },
-    },
-  };
-};
-
-/** An in-flight CDP request awaiting its response or timeout. */
-export type Pending = {
-  readonly resolve: (v: Result<unknown, CdpError>) => void;
-  readonly timer: ReturnType<typeof setTimeout>;
-  readonly method: string;
-};
-
-/**
- * Reject every in-flight request with a transport_closed error and clear the
- * map. Called from each transport's cleanup path when the underlying connection
- * goes away.
- */
-export const rejectAllPending = (pending: Map<number, Pending>, reason: string): void => {
-  for (const [, p] of pending) {
-    clearTimeout(p.timer);
-    p.resolve(err(cdpError("transport_closed", reason, p.method)));
-  }
-  pending.clear();
-};
-
-/**
- * Send a CDP request and return a promise that settles when the matching
- * response arrives, the request times out, or the send throws.
- *
- * The transport supplies a `send` callback that puts the already-serialized
- * payload onto its wire (WebSocket frame or Unix-socket line); everything else
- * — registering the pending entry, the timeout timer, and synchronous send
- * failure handling — is identical across transports and lives here.
- *
- * `timeoutLabel` is the transport's prefix for the timeout error message
- * (e.g. "CDP" or "Daemon").
- */
-export const sendWithTimeout = (
-  pending: Map<number, Pending>,
-  id: number,
-  method: string,
-  timeoutMs: number,
-  timeoutLabel: string,
-  send: () => void,
-): Promise<CdpResult> =>
-  new Promise((resolve) => {
-    const timer = setTimeout(() => {
-      pending.delete(id);
-      resolve(err(cdpError("timeout", `${timeoutLabel} timeout after ${timeoutMs}ms: ${method}`, method)));
-    }, timeoutMs);
-    pending.set(id, { resolve, timer, method });
-    try {
-      send();
-    } catch (e) {
-      clearTimeout(timer);
-      pending.delete(id);
-      resolve(err(cdpError("transport_closed", e instanceof Error ? e.message : String(e), method)));
-    }
-  });
-
-/**
- * Register a close listener, returning an unsubscribe function. Identical
- * across transports, so it lives here.
- */
-export const makeOnClose = (closeListeners: Set<() => void>) =>
-  (cb: () => void): (() => void) => {
-    closeListeners.add(cb);
-    return () => closeListeners.delete(cb);
-  };

package/src/cdp/transport.ts

@@ -1,156 +0,0 @@
-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";
-import { type Pending, makeEventQueue, makeOnClose, rejectAllPending, sendWithTimeout } from "./event-queue";
-
-const DEFAULT_TIMEOUT_MS = 15_000;
-
-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>();
-
-  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 => {
-    rejectAllPending(pending, reason);
-    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 sendWithTimeout(pending, id, method, timeoutMs, "CDP", () => sock.send(json));
-    },
-    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: makeOnClose(closeListeners),
-  };
-};

package/src/cdp/window-binding.ts

@@ -1,15 +0,0 @@
-import type { BrowserClient } from "../client";
-
-/**
- * Capture the real Chrome windowId of a freshly-created harness window and bind
- * it as the session's durable window identity. Best-effort: a failed CDP call
- * leaves the previous binding untouched. Call this on every code path that
- * spawns a NEW dedicated window (newWindow:true), so the windowId never points
- * at a window that has since been replaced.
- */
-export const bindHarnessWindowId = async (client: BrowserClient, targetId: string): Promise<void> => {
-  const r = await client.session().callBrowser("Browser.getWindowForTarget", { targetId });
-  if (!r.success) return;
-  const wid = (r.data as { windowId?: number }).windowId;
-  if (typeof wid === "number") client.ownership().setHarnessWindowId(wid);
-};