pi-browser-harness 0.10.2 → 0.11.0

package/src/cdp/target-factory.ts

@@ -1,48 +1,15 @@
-/**
- * The single place harness tabs and windows are created.
- *
- * Every tab the harness opens must land in the pinned profile, so all creation
- * paths (client.newTab, browser_open_urls, isolated tabs for web_search /
- * read_page) funnel through here. A missed call site would silently act in
- * another profile — with that profile's cookies and logins.
- *
- * Two mechanisms, chosen by whether a profile is pinned:
- *
- *   unpinned — `Target.createTarget`, exactly as before: `newWindow: true` for
- *              a fresh dedicated window, `openerId` for siblings inside it.
- *
- *   pinned   — the window comes from a command-line launch into the profile
- *              (see profile/launch.ts), and further tabs come from
- *              `window.open(..., '_blank')` evaluated in an owned page with
- *              `userGesture: true`. That is the only CDP-reachable way to place
- *              a tab in a non-default browser context: createTarget rejects a
- *              foreign browserContextId outright, and `openerId` does NOT
- *              inherit the opener's context (verified — it lands in the
- *              focus-derived default context, in a different window).
- *              window.open keeps both the context and the window, recursively.
- *
- * Correlation: window.open returns no target id, so each spawn carries a unique
- * `about:blank#pi-<uuid>` token and the new target is found by that token.
- * Set-difference polling would be wrong here — isolated tabs run concurrently
- * (browser_read_page is registered unserialized).
- */
+// `window.open` with userGesture is the only CDP-reachable way into a non-default browser context: createTarget rejects a foreign browserContextId and `openerId` does not inherit the opener's context.
 
 import { randomUUID } from "node:crypto";
 import type { BrowserClient } from "../client";
 import { type Result, err, ok } from "../util/result";
 import { type CdpError, cdpError } from "./errors";
 
-/** How long to wait for a window.open-spawned target to appear. */
 const SPAWN_DEADLINE_MS = 8_000;
 const SPAWN_POLL_MS = 100;
 
 export type HarnessWindow = {
-  /** Target id of the window's seed tab. */
   readonly targetId: string;
-  /**
-   * True when this call created the window. The seed tab is then a blank tab
-   * the caller may use directly, instead of opening a second one.
-   */
   readonly freshlyCreated: boolean;
 };
 
@@ -56,23 +23,15 @@ type PageTarget = {
 const listPageTargets = async (client: BrowserClient): Promise<Result<ReadonlyArray<PageTarget>, CdpError>> => {
   const r = await client.session().callBrowser("Target.getTargets");
   if (!r.success) return r;
-  const data = r.data as { targetInfos: ReadonlyArray<PageTarget> };
-  return ok(data.targetInfos.filter((t) => t.type === "page"));
+  return ok(r.data.targetInfos.filter((t) => t.type === "page"));
 };
 
-/** A CDP session id for driving `targetId`, reusing the active one when possible. */
 const sessionForTarget = async (client: BrowserClient, targetId: string): Promise<Result<string, CdpError>> => {
   const current = client.current();
   if (current?.targetId === targetId) return ok(current.sessionId);
-  const attached = await client.session().callBrowser("Target.attachToTarget", { targetId, flatten: true });
-  if (!attached.success) return attached;
-  return ok((attached.data as { sessionId: string }).sessionId);
+  return client.session().attach(targetId);
 };
 
-/**
- * Spawn a tab from `openerTargetId` via window.open, so it inherits the
- * opener's profile and window, and return its target id.
- */
 const spawnTabViaOpener = async (
   client: BrowserClient,
   openerTargetId: string,
@@ -92,8 +51,7 @@ const spawnTabViaOpener = async (
     session.data,
   );
   if (!opened.success) return opened;
-  const result = opened.data as { result?: { value?: unknown } };
-  if (result.result?.value !== true) {
+  if (opened.data.result.value !== true) {
     return err(cdpError(
       "invalid_response",
       "the browser blocked window.open in the pinned profile's window — the page may have navigated away; retry, or run /browser-profile to re-seed",
@@ -113,29 +71,13 @@ const spawnTabViaOpener = async (
   return err(cdpError("timeout", `the tab opened in the pinned profile did not report back within ${SPAWN_DEADLINE_MS}ms`));
 };
 
-/**
- * In-flight window creation, per client. Isolated tabs run concurrently
- * (browser_read_page is registered unserialized), so two of them starting at
- * once would otherwise each find "no harness window" and create one — two blank
- * windows before, and two launched profile windows now. Callers share the first
- * call's result instead.
- */
 const inFlight = new WeakMap<BrowserClient, Promise<Result<HarnessWindow, CdpError>>>();
 
-/**
- * The harness window for this session, creating it when absent.
- *
- * Reuses a live owned tab when one exists — including after the user closed the
- * original seed — so reconnects don't scatter windows.
- */
 export const ensureHarnessWindow = async (client: BrowserClient): Promise<Result<HarnessWindow, CdpError>> => {
   const pending = inFlight.get(client);
   if (pending) {
     const shared = await pending;
-    // `freshlyCreated` is a claim on the seed tab, and only the caller that
-    // started the creation may hold it. Everyone waiting on the same window
-    // must open a tab of their own beside it, or two callers would drive the
-    // very same tab.
+    // `freshlyCreated` is a claim on the seed tab that only the caller which started the creation may hold, or two callers would drive the same tab.
     return shared.success ? ok({ targetId: shared.data.targetId, freshlyCreated: false }) : shared;
   }
   const attempt = ensureHarnessWindowUncoordinated(client).finally(() => inFlight.delete(client));
@@ -152,11 +94,7 @@ const ensureHarnessWindowUncoordinated = async (
 
   const ownership = client.ownership();
   const pinnedCtx = client.profileContextId();
-  // A tab may only be reused when we can prove which profile it is in. With a
-  // pin set but no context resolved yet — a fresh connection, or a browser that
-  // restarted — the recorded tabs cannot be verified, so we seed a new window
-  // rather than risk adopting one from the wrong profile. (Sessions close their
-  // owned tabs on shutdown, so this is the normal, no-cost case.)
+  // With a pin set but no context resolved yet, a recorded tab's profile cannot be verified, so seed a new window rather than risk adopting one from the wrong profile.
   const canReuse = client.profilePin() === null || pinnedCtx !== undefined;
   const inPinnedProfile = (targetId: string): boolean => {
     if (!pinnedCtx) return true;
@@ -183,26 +121,18 @@ const ensureHarnessWindowUncoordinated = async (
   return ok({ targetId: seeded.data, freshlyCreated: true });
 };
 
-/** Unpinned path: a fresh dedicated window, exactly as the harness always did. */
 const createDedicatedWindow = async (client: BrowserClient): Promise<Result<string, CdpError>> => {
   const created = await client.session().callBrowser("Target.createTarget", { url: "about:blank", newWindow: true });
   if (!created.success) return created;
-  const { targetId } = created.data as { targetId: string };
+  const { targetId } = created.data;
   const ownership = client.ownership();
   ownership.setHarnessWindow(targetId);
   ownership.add(targetId);
-  const win = await client.session().callBrowser("Browser.getWindowForTarget", { targetId });
-  if (win.success) {
-    const windowId = (win.data as { windowId?: number }).windowId;
-    if (typeof windowId === "number") ownership.setHarnessWindowId(windowId);
-  }
+  const win = await client.session().windowId(targetId);
+  if (win.success) ownership.setHarnessWindowId(win.data);
   return ok(targetId);
 };
 
-/**
- * Open a harness-owned tab beside `openerTargetId`, in the same window and —
- * when a profile is pinned — the same profile. The tab is registered as owned.
- */
 export const openHarnessTab = async (
   client: BrowserClient,
   openerTargetId: string,
@@ -215,7 +145,7 @@ export const openHarnessTab = async (
           openerId: openerTargetId,
         });
         if (!created.success) return created;
-        return ok((created.data as { targetId: string }).targetId);
+        return ok(created.data.targetId);
       })();
   if (!spawned.success) return spawned;
   client.ownership().add(spawned.data);

package/src/cdp/types.ts

@@ -1,3 +1,7 @@
+import type { Result } from "../util/result";
+import { isRecord } from "../util/guards";
+import type { CdpError } from "./errors";
+
 export type CdpEvent = {
   readonly method: string;
   readonly params: unknown;
@@ -44,18 +48,8 @@ export type DaemonStatus = {
   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;
+  if (!isRecord(v)) return false;
   const id = v["id"];
   if (id !== undefined && typeof id !== "number") return false;
   const method = v["method"];
@@ -64,10 +58,25 @@ export const isCdpRawMessage = (v: unknown): v is CdpRawMessage => {
   if (sessionId !== undefined && typeof sessionId !== "string") return false;
   const errVal = v["error"];
   if (errVal !== undefined) {
-    if (!isObject(errVal)) return false;
+    if (!isRecord(errVal)) return false;
     if (typeof errVal["message"] !== "string") return false;
     const code = errVal["code"];
     if (code !== undefined && typeof code !== "number") return false;
   }
   return true;
 };
+
+export 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>>;
+  events(): AsyncIterable<CdpEvent>;
+  state(): "open" | "closed" | "connecting";
+  onClose(cb: () => void): () => void;
+};

package/src/client.ts

@@ -1,10 +1,12 @@
+import { Type } from "typebox";
+import { Compile } from "typebox/compile";
+import { parseJson } from "./schemas/parse";
 import { type Result, err, ok } from "./util/result";
 import { safeJs } from "./util/js-template";
 import { type Mutex, createMutex } from "./util/mutex";
 import { discoverEndpoint } from "./cdp/discovery";
 import { type CdpError, cdpError } from "./cdp/errors";
-import type { CdpTransport } from "./cdp/transport";
-import { createCdpTransport } from "./cdp/transport";
+import type { CdpTransport } from "./cdp/types";
 import { type CdpSession, createCdpSession } from "./cdp/session";
 import { type OwnershipRegistry, createOwnershipRegistry } from "./cdp/ownership";
 import { ensureHarnessWindow, openHarnessTab } from "./cdp/target-factory";
@@ -14,14 +16,13 @@ import type { DaemonStatus, DialogInfo, PageInfo, TabInfo } from "./cdp/types";
 
 export type BrowserClientOptions = {
   readonly namespace: string;
-  readonly transport?: CdpTransport;
+  readonly transport: CdpTransport;
   readonly remote?: { readonly cdpUrl: string; readonly browserId: string };
   readonly initialOwnership?: {
     readonly ownedTargetIds?: ReadonlyArray<string>;
     readonly harnessWindowTargetId?: string;
     readonly harnessWindowId?: number;
   };
-  /** Profile to pin this session to, loaded from the durable pin store. */
   readonly profilePin?: ProfilePin | null;
   readonly onOwnershipChange?: (snapshot: {
     readonly ownedTargetIds: ReadonlyArray<string>;
@@ -36,11 +37,7 @@ export type BrowserClient = {
   status(): DaemonStatus;
   start(): Promise<Result<void, CdpError>>;
   stop(): Promise<void>;
-  /** Detach from the current page target (removes the "Chrome is being controlled" banner)
-   *  while keeping the transport connection alive. Call on session shutdown. */
   detach(): Promise<void>;
-  /** Close every tab this session owns and clear the window binding. Best-effort —
-   *  used on session shutdown so no stale harness tabs survive. */
   closeOwnedTabs(): Promise<void>;
   evaluateJs(expression: string, sessionId?: string): Promise<Result<unknown, CdpError>>;
   pageInfo(): Promise<Result<PageInfo | { readonly dialog: DialogInfo }, CdpError>>;
@@ -54,57 +51,51 @@ export type BrowserClient = {
   current(): { readonly sessionId: string; readonly targetId: string } | null;
   session(): CdpSession;
   transport(): CdpTransport;
-  /** User-data-dir of the connected browser, when discovery could determine it.
-   *  Undefined for BU_CDP_WS / bare-port connections, where profile selection
-   *  is unavailable. */
   userDataDir(): string | undefined;
-  /** The profile this session is pinned to, or null when unpinned. */
   profilePin(): ProfilePin | null;
   setProfilePin(pin: ProfilePin | null): void;
-  /** browserContextId of the pinned profile, once a window has identified it.
-   *  Session-scoped: Chrome re-mints context ids on every browser run. */
   profileContextId(): string | undefined;
   setProfileContextId(contextId: string | undefined): void;
-  /** Open and adopt a window inside the pinned profile. Returns its seed tab. */
   seedPinnedProfileWindow(): Promise<Result<string, CdpError>>;
-  /** Returns the shared async mutex that serialized browser tools must acquire
-   *  before performing mutations. Observation tools should not use this. */
   mutationMutex(): Mutex;
 };
 
 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})`));
-    }
+const PageInfoPayload = Type.Object({
+  url: Type.String(),
+  title: Type.String(),
+  w: Type.Number(),
+  h: Type.Number(),
+  sx: Type.Number(),
+  sy: Type.Number(),
+  pw: Type.Number(),
+  ph: Type.Number(),
+});
+
+const pageInfoValidator = Compile(PageInfoPayload);
+
+const parsePageInfoPayload = (raw: string): Result<PageInfo, CdpError> => {
+  const parsed = parseJson(raw, pageInfoValidator);
+  if (!parsed.success) {
+    return err(cdpError("invalid_response", `page info payload is invalid: ${parsed.error}`));
   }
+  const o = parsed.data;
   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,
+    url: o.url,
+    title: o.title,
+    width: o.w,
+    height: o.h,
+    scrollX: o.sx,
+    scrollY: o.sy,
+    pageWidth: o.pw,
+    pageHeight: o.ph,
   });
 };
 
 export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient => {
-  const transport = opts.transport ?? createCdpTransport();
+  const transport = opts.transport;
   const ownershipInit: { ownedTargetIds?: ReadonlyArray<string>; harnessWindowTargetId?: string; harnessWindowId?: number } = {};
   if (opts.initialOwnership?.ownedTargetIds !== undefined) {
     ownershipInit.ownedTargetIds = opts.initialOwnership.ownedTargetIds;
@@ -126,9 +117,6 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
       });
     });
   }
-  // The seed provider routes attachFirstPage's fallback through the target
-  // factory, so a pinned profile is honoured on every path that can create the
-  // harness window.
   const session = createCdpSession(transport, ownership, async () => {
     const window = await ensureHarnessWindow(api);
     return window.success ? ok(window.data.targetId) : window;
@@ -141,12 +129,7 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
   let profilePin: ProfilePin | null = opts.profilePin ?? null;
   let profileContextId: string | undefined;
 
-  /**
-   * With a profile pinned, the harness window must exist BEFORE anything
-   * attaches: session.attachFirstPage() would otherwise fall back to a bare
-   * Target.createTarget, which lands in the focus-derived default profile.
-   * Seeding first means attachFirstPage always finds an owned tab to attach to.
-   */
+  // With a pin set the window must exist BEFORE anything attaches, or attachFirstPage's bare Target.createTarget lands in the focus-derived default profile.
   const seedIfPinned = async (): Promise<Result<void, CdpError>> => {
     if (!profilePin) return ok(undefined);
     const window = await ensureHarnessWindow(api);
@@ -156,12 +139,9 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
 
   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 discoverEndpoint();
       if (!discovered.success) return discovered;
@@ -209,14 +189,10 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
       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") {
-      // Re-seed first when pinned: if the user closed every harness tab,
-      // attachFirstPage would mint a window in the focus-derived profile.
       const seeded = await seedIfPinned();
       if (!seeded.success) return seeded;
       const reattached = await session.attachFirstPage();
@@ -231,12 +207,7 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
   };
 
   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)()`. Only wrap when the trimmed
-    // source *starts with* a return statement — a bare expression, or one that
-    // merely mentions `return` inside a string literal or comment, is passed
-    // through untouched (previously any substring `"return "` triggered a wrap,
-    // silently turning such expressions into `undefined`).
+    // Wrap only when the trimmed source *starts with* `return` — matching the substring anywhere silently turned expressions mentioning it into `undefined`.
     const trimmed = expression.trim();
     const isReturnStatement = /^return[\s(]/.test(trimmed);
     const wrapped = isReturnStatement ? `(function(){${expression}})()` : expression;
@@ -244,11 +215,10 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
       ? 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"));
+    if (r.data.exceptionDetails !== undefined) {
+      return err(cdpError("remote_error", `JS evaluation failed: ${JSON.stringify(r.data.exceptionDetails)}`, "Runtime.evaluate"));
     }
-    return ok(data.result?.value);
+    return ok(r.data.result.value);
   };
 
   const readPageInfo = async (): Promise<Result<PageInfo, CdpError>> => {
@@ -260,13 +230,7 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
     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);
+    const info = parsePageInfoPayload(raw.data);
     if (!info.success) return info;
     if (currentTid) pageCaches.set(currentTid, { info: info.data, at: Date.now() });
     return ok(info.data);
@@ -281,8 +245,7 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
   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
+    const tabs = r.data.targetInfos
       .filter((t) => t.type === "page")
       .filter((t) => includeInternal || !t.url.startsWith("chrome://"))
       .map((t): TabInfo => ({
@@ -291,14 +254,12 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
         url: t.url,
         owned: ownership.has(t.targetId),
       }));
-    // Reconcile any persisted owned ids that no longer exist as live page targets.
     const live = new Set(tabs.map((t) => t.targetId));
     const owned = ownership.list();
     const survivors = owned.filter((id) => live.has(id));
     if (survivors.length !== owned.length) ownership.replaceAll(survivors);
     const hw = ownership.harnessWindow();
     if (hw && !live.has(hw)) ownership.setHarnessWindow(undefined);
-    // Prune per-tab page caches for tabs that no longer exist
     for (const tid of pageCaches.keys()) {
       if (!live.has(tid)) pageCaches.delete(tid);
     }
@@ -308,10 +269,6 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
   const switchTab = async (targetId: string): Promise<Result<void, CdpError>> => {
     const r = await session.switchTo(targetId);
     if (!r.success) return r;
-    // pageCache per-tab: no longer cleared — each tab retains its cache
-    // 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`,
     });
@@ -319,17 +276,11 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
   };
 
   const newTab = async (url?: string): Promise<Result<string, CdpError>> => {
-    // Reconcile ownership against live targets before deciding where to open.
     const tabsResult = await listTabs(true);
     if (!tabsResult.success) return tabsResult;
 
-    // ensureHarnessWindow reuses the seed tab, falls back to any surviving
-    // owned tab, and only then creates a window — which, when a profile is
-    // pinned, means launching one inside that profile.
     const window = await ensureHarnessWindow(api);
     if (!window.success) return window;
-    // A freshly created window IS the new tab; opening another would leave a
-    // stray blank tab behind.
     let tabId: string;
     if (window.data.freshlyCreated) {
       tabId = window.data.targetId;
@@ -356,9 +307,6 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
   };
 
   const closeOwnedTabs = async (): Promise<void> => {
-    // Snapshot first — remove() mutates the list, and targetDestroyed events
-    // may also prune concurrently. Failures are swallowed: a tab the user
-    // already closed, or a dead transport, must not block shutdown.
     for (const id of ownership.list()) {
       await session.callBrowser("Target.closeTarget", { targetId: id }).catch(() => {});
       ownership.remove(id);
@@ -377,10 +325,6 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
   const detach = async (): Promise<void> => {
     const cur = session.current();
     if (!cur) return;
-    // Target.detachFromTarget removes the "Chrome is being controlled" banner
-    // and releases the page session. The transport (WebSocket/Unix socket)
-    // stays alive for reuse by the next session.
-    // Reference: https://chromedevtools.github.io/devtools-protocol/tot/Target/#method-detachFromTarget
     await transport.request("Target.detachFromTarget", { sessionId: cur.sessionId }, { sessionId: null });
   };