cdp-toolkit 1.7.0 → 1.8.0

package/src/shared-tools.ts

@@ -36,10 +36,14 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type {
-  BrowserCookie, BrowserDriver, DriverUid, ElementLocator, NavigateResult, PageDriver, PageInfo, SnapshotNode,
+  BrowserCookie, BrowserDriver, Capability, DragDestination, DriverUid, ElementLocator, NavigateResult, PageDriver, PageInfo, SnapshotNode,
 } from "./driver.ts";
 import type { TargetSelector } from "./types.ts";
-import { assertLeaseOk, claimLease, defaultLabel, leaseTtlMs, releaseLeaseFor, requireLease, type LeaseBackend, type LeaseToken } from "./leases.ts";
+import {
+  assertLeaseOk, claimLease, defaultLabel, leaseTtlMs, listLeases, releaseLeaseFor, requireLease,
+  type LeaseBackend, type LeaseStaleReason, type LeaseToken,
+} from "./leases.ts";
+import { installBeacon, probeRendererActivity, rendererProbeSupported } from "./activity.ts";
 import { newTrackedPage, originIndex, type PageOrigin } from "./origins.ts";
 import { reapStaleAgentTabs, type ReapedTab } from "./reap.ts";
 
@@ -166,6 +170,31 @@ export interface ListedPage extends PageInfo {
    *  genuinely unknown, but this field is what keeps an unreadable record from
    *  being reported as a clean "nothing was ever recorded". */
   originUnreadable?: string;
+  /**
+   * Present only for a tab under an active, READABLE lease of THIS backend.
+   * idleMs and expiresAt are computed fresh on every call (now-lastUsedAt and
+   * lastUsedAt+ttlMs), never read off disk — same rule as list_leases' own
+   * LeaseRow, and unconditional on `probe`: a lease can exist whether or not a
+   * caller ever passes probe:true, and this costs nothing beyond a lease-dir
+   * read this call already pays for under strict mode.
+   */
+  lease?: { label: string; pid: number; idleMs: number; expiresAt: number; stale: LeaseStaleReason | false };
+  /**
+   * Present only when { probe: true } was passed AND this backend can answer
+   * it (see rendererProbeSupported in src/activity.ts) AND this entry is a
+   * page-type target — a worker or iframe has no `window` to carry the beacon
+   * global, so probing one would be a guaranteed false negative rather than a
+   * genuine liveness answer. true when a bounded Runtime.evaluate answered
+   * within budget; false on a timeout, a thrown page-side exception, or a
+   * target the driver could not reach at all — the wedged-tab case this field
+   * exists to surface, reported as data rather than failing the whole call.
+   */
+  responsive?: boolean;
+  /** Ms since a human last touched this tab, present only where probe:true
+   *  answered AND the same round trip found human-attributed beacon data.
+   *  Same rule as claim_page/list_leases: absence is "no answer", never "no
+   *  human". */
+  humanActiveMs?: number;
 }
 
 /**
@@ -190,23 +219,52 @@ async function reapSet(driver: BrowserDriver, pages: PageInfo[], all?: boolean):
 
 export async function listPages(
   driver: BrowserDriver,
-  args: { all?: boolean } = {},
+  args: { all?: boolean; probe?: boolean } = {},
 ): Promise<{ pages: ListedPage[]; count: number; reaped?: ReapedTab[] }> {
   // Reap FIRST, so a tab this call is about to close never appears in the
-  // listing it returns. Under strict mode only: see requireLease.
-  const reaped = requireLease() ? await reapStaleAgentTabs(driver, backendOf(driver)) : [];
+  // listing it returns, and so the lease read just below never reports a lease
+  // this same call is in the middle of deleting. Under strict mode only: see
+  // requireLease.
+  const backend = backendOf(driver);
+  const reaped = requireLease() ? await reapStaleAgentTabs(driver, backend) : [];
   const reapedIds = new Set(reaped.map((r) => r.targetId));
   const pages = (await driver.listPages({ all: args.all })).filter((p) => !reapedIds.has(p.id));
   // Never let provenance break the listing: originIndex does not throw, and a
   // missing or unreadable ledger yields an empty map, so every page falls back
   // to origin "unknown" exactly as a pre-ledger consumer always saw.
-  const ledger = await originIndex(backendOf(driver), await reapSet(driver, pages, args.all));
-  const annotated: ListedPage[] = pages.map((p) => {
-    const rec = ledger.get(p.id);
-    if (!rec) return { ...p, origin: "unknown" };
-    if (rec.unreadable !== undefined) return { ...p, origin: "unknown", originUnreadable: rec.unreadable };
-    return { ...p, origin: "agent", label: rec.label, createdAt: rec.createdAt };
-  });
+  const ledger = await originIndex(backend, await reapSet(driver, pages, args.all));
+  const now = Date.now();
+  // Observability (1.8.0): every READABLE lease of this backend, keyed by
+  // target. Read unconditionally, not gated on `probe`, because a lease can
+  // exist whether or not a caller ever asks for a renderer ping.
+  const leaseByTarget = new Map(
+    (await listLeases({ now, liveIds: pages.map((p) => p.id), liveBackend: backend }))
+      .filter((l) => l.backend === backend && l.unreadable === undefined)
+      .map((l) => [l.targetId, l] as const),
+  );
+  const doProbe = args.probe === true && rendererProbeSupported(driver);
+  const annotated: ListedPage[] = await Promise.all(
+    pages.map(async (p) => {
+      const rec = ledger.get(p.id);
+      const base: ListedPage =
+        !rec ? { ...p, origin: "unknown" }
+        : rec.unreadable !== undefined ? { ...p, origin: "unknown", originUnreadable: rec.unreadable }
+        : { ...p, origin: "agent", label: rec.label, createdAt: rec.createdAt };
+      const leaseRow = leaseByTarget.get(p.id);
+      if (leaseRow) {
+        base.lease = { label: leaseRow.label, pid: leaseRow.pid, idleMs: now - leaseRow.lastUsedAt, expiresAt: leaseRow.lastUsedAt + leaseRow.ttlMs, stale: leaseRow.stale };
+      }
+      // Page-type only: see ListedPage.responsive. Concurrent across pages
+      // (this whole map runs inside Promise.all), so one wedged tab's 500ms
+      // budget never serializes onto the next tab's.
+      if (doProbe && (p.type === undefined || p.type === "page")) {
+        const probe = await probeRendererActivity(driver, backend, p.id, now);
+        base.responsive = probe.responsive;
+        if (probe.humanActiveMs !== undefined) base.humanActiveMs = probe.humanActiveMs;
+      }
+      return base;
+    }),
+  );
   // `reaped` is present only when it has something to say, so the common-case
   // shape is byte-identical to 1.4.0. Silently closing a tab is not acceptable:
   // if a read closed something, the read says so.
@@ -238,6 +296,12 @@ export async function newPage(
     // silently WEAKEN every existing claim:true call site to pid-only.
     auto: !explicit,
   });
+  // Install the activity beacon on the same terms claim_page does: at claim
+  // time, after the claim, best effort (installBeacon never throws). A tab
+  // beaconed now is a tab that can ANSWER later — when this agent has released
+  // it and a person has picked it up, which is the case the beacon exists for.
+  // Nothing here is read back: a tab created a moment ago has no human history.
+  await installBeacon(driver, p.id);
   return { targetId: p.id, url: p.url, lease: token, label: record.label, expiresAt: record.lastUsedAt + record.ttlMs };
 }
 
@@ -286,23 +350,65 @@ export interface LegacyNavigateResult {
   url: string;
   frameId: string;
   reloaded?: boolean;
+  /** Present only on a history traversal, mirroring how `reloaded` is present only on a reload. */
+  traversed?: "back" | "forward";
   waitedFor: "load" | "domcontentloaded" | "frameStoppedLoading" | "navigate-only";
 }
 
+/** What a navigate_page call is actually asking for. Exactly one of the three. */
+export type NavigateMode =
+  | { mode: "url"; url: string }
+  | { mode: "reload" }
+  | { mode: "history"; history: "back" | "forward" };
+
+/**
+ * The three-way exclusivity check for navigate_page's url / reload / history, split out and
+ * exported so every refusal is pinned by a unit test without a browser (the same reason
+ * resolveScrollAnchor and resolveDragDestination live at this layer).
+ *
+ * EXCLUSIVE, NOT PRECEDENCE-ORDERED. `{url, history:"back"}` is a caller who does not know what
+ * they want; silently honoring one of them would navigate somewhere the caller did not ask for and
+ * report success. Refusing names both, so the mistake is visible in the error rather than in the
+ * page that comes back.
+ */
+export function resolveNavigateMode(args: { url?: string; reload?: boolean; history?: unknown }): NavigateMode {
+  const reload = args.reload === true;
+  const hasUrl = typeof args.url === "string" && args.url.length > 0;
+  const hasHistory = args.history !== undefined && args.history !== null;
+  const given = [hasUrl ? "url" : "", reload ? "reload" : "", hasHistory ? "history" : ""].filter(Boolean);
+  if (given.length > 1) {
+    throw new SharedToolError(`navigate_page: 'url', 'reload' and 'history' are mutually exclusive (got ${given.join(" + ")})`);
+  }
+  if (hasHistory) {
+    if (args.history !== "back" && args.history !== "forward") {
+      throw new SharedToolError(`navigate_page: 'history' must be 'back' or 'forward' (got ${JSON.stringify(args.history)})`);
+    }
+    return { mode: "history", history: args.history };
+  }
+  if (reload) return { mode: "reload" };
+  if (!hasUrl) {
+    throw new SharedToolError(
+      "navigate_page: 'url' is required (or pass reload:true to reload the current page, or history:'back'|'forward' to go back/forward in this tab's session history)",
+    );
+  }
+  return { mode: "url", url: args.url as string };
+}
+
 export async function navigatePage(
   driver: BrowserDriver,
-  args: { target?: TargetSelector; url?: string; reload?: boolean; ignoreCache?: boolean; waitUntil?: "load" | "domcontentloaded"; timeoutMs?: number },
+  args: {
+    target?: TargetSelector; url?: string; reload?: boolean; ignoreCache?: boolean;
+    history?: "back" | "forward"; waitUntil?: "load" | "domcontentloaded"; timeoutMs?: number;
+  },
 ): Promise<LegacyNavigateResult> {
-  const reload = args.reload === true;
-  if (!reload && (!args.url || typeof args.url !== "string")) {
-    throw new SharedToolError("navigate_page: 'url' is required (or pass reload:true to reload the current page)");
-  }
+  const mode = resolveNavigateMode(args);
   return withPage(driver, args.target, async (page) => {
-    const r = await page.navigate(args);
+    const r = await page.navigate(mode.mode === "history" ? { ...args, history: mode.history } : args);
     return {
       url: r.url,
       frameId: r.contextId,
       ...(r.reloaded ? { reloaded: r.reloaded } : {}),
+      ...(r.traversed ? { traversed: r.traversed } : {}),
       waitedFor: toLegacyWaitedFor(r.waitedFor),
     };
   });
@@ -620,14 +726,55 @@ export async function takeSnapshot(
 
 export async function click(
   driver: BrowserDriver,
-  args: { target?: TargetSelector; uid?: DriverUid; selector?: string; button?: "left" | "right" | "middle"; clickCount?: number },
+  args: { target?: TargetSelector; uid?: DriverUid; selector?: string; button?: "left" | "right" | "middle"; clickCount?: number; modifiers?: string[] },
 ): Promise<{ clicked: true; x: number; y: number }> {
   return withPage(driver, args.target, async (page) => {
-    const { x, y } = await page.click(locatorOf(args), { button: args.button ?? "left", clickCount: args.clickCount ?? 1 });
+    const { x, y } = await page.click(locatorOf(args), { button: args.button ?? "left", clickCount: args.clickCount ?? 1, modifiers: args.modifiers });
     return { clicked: true, x, y };
   });
 }
 
+/**
+ * scroll's anchor rule: exactly one of `{uid}`, `{selector}`, or `{x,y}` — or none of the three,
+ * which means the viewport center. `x`/`y` must arrive together; one without the other is refused
+ * rather than silently treated as "half an anchor". Exported for the unit tests, which pin the
+ * rule without a browser.
+ */
+export function resolveScrollAnchor(args: { uid?: DriverUid; selector?: string; x?: number; y?: number }): ElementLocator | { x: number; y: number } | undefined {
+  const hasUid = args.uid !== undefined && args.uid !== null && args.uid !== ("" as unknown);
+  const hasSelector = typeof args.selector === "string" && args.selector.length > 0;
+  const hasX = args.x !== undefined;
+  const hasY = args.y !== undefined;
+  if (hasX !== hasY) throw new SharedToolError("scroll: 'x' and 'y' must be provided together");
+  const hasXY = hasX && hasY;
+  const anchorCount = [hasUid, hasSelector, hasXY].filter(Boolean).length;
+  if (anchorCount > 1) throw new SharedToolError("scroll: provide at most one of { uid }, { selector }, or { x, y } (omit all three to scroll at the viewport center)");
+  if (hasUid || hasSelector) return locatorOf({ uid: args.uid, selector: args.selector });
+  if (hasXY) return { x: args.x as number, y: args.y as number };
+  return undefined;
+}
+
+/** scroll's delta rule: at least one of deltaX/deltaY is required (a no-op scroll is refused
+ *  rather than silently dispatched). Exported for the unit tests. */
+export function resolveScrollDelta(args: { deltaX?: number; deltaY?: number }): { deltaX: number; deltaY: number } {
+  const deltaX = args.deltaX ?? 0;
+  const deltaY = args.deltaY ?? 0;
+  if (deltaX === 0 && deltaY === 0) throw new SharedToolError("scroll requires at least one of { deltaX } or { deltaY }");
+  return { deltaX, deltaY };
+}
+
+export async function scroll(
+  driver: BrowserDriver,
+  args: { target?: TargetSelector; uid?: DriverUid; selector?: string; x?: number; y?: number; deltaX?: number; deltaY?: number },
+): Promise<{ x: number; y: number; deltaX: number; deltaY: number; target: { id: string; url: string; title: string } }> {
+  const anchor = resolveScrollAnchor(args);
+  const { deltaX, deltaY } = resolveScrollDelta(args);
+  return withPage(driver, args.target, async (page) => {
+    const { x, y } = await page.scroll(anchor, { deltaX, deltaY });
+    return { x, y, deltaX, deltaY, target: target3(page.info) };
+  });
+}
+
 export async function hover(driver: BrowserDriver, args: { target?: TargetSelector; uid?: DriverUid; selector?: string }): Promise<{ hovered: true; x: number; y: number }> {
   return withPage(driver, args.target, async (page) => {
     const { x, y } = await page.hover(locatorOf(args));
@@ -635,14 +782,106 @@ export async function hover(driver: BrowserDriver, args: { target?: TargetSelect
   });
 }
 
+/** drag's `to`: exactly one of { uid } | { selector } | { x, y }, x and y together. Exported for
+ *  the unit tests, which pin the rule without a browser. */
+export function resolveDragTo(to: { uid?: DriverUid; selector?: string; x?: number; y?: number }): DragDestination {
+  const hasUid = to.uid !== undefined && to.uid !== null && to.uid !== ("" as unknown);
+  const hasSelector = typeof to.selector === "string" && to.selector.length > 0;
+  const hasX = to.x !== undefined;
+  const hasY = to.y !== undefined;
+  if (hasX !== hasY) throw new SharedToolError("drag: 'to.x' and 'to.y' must be provided together");
+  const hasXY = hasX && hasY;
+  const count = [hasUid, hasSelector, hasXY].filter(Boolean).length;
+  if (count !== 1) throw new SharedToolError("drag: 'to' takes exactly one of { uid }, { selector }, or { x, y }");
+  if (hasXY) {
+    if (!Number.isFinite(to.x) || !Number.isFinite(to.y)) throw new SharedToolError("drag: 'to.x' and 'to.y' must be finite numbers");
+    return { x: to.x as number, y: to.y as number };
+  }
+  return locatorOf({ uid: to.uid, selector: to.selector });
+}
+
+/**
+ * drag's destination rule: EXACTLY one of `to` (where the drag ends) or `by` (how far it moves
+ * from the source point). Both is a contradiction and neither leaves nowhere to drag to, so both
+ * are refused rather than resolved by precedence — a caller who passed both meant one of them and
+ * silently picking is how the wrong widget gets dragged. `by` needs at least one of dx/dy; the
+ * other defaults to 0, so `by:{dx:40}` is a pure horizontal slider nudge. Exported for the tests.
+ */
+export function resolveDragDestination(args: {
+  to?: { uid?: DriverUid; selector?: string; x?: number; y?: number };
+  by?: { dx?: number; dy?: number };
+}): DragDestination {
+  const hasTo = args.to !== undefined && args.to !== null;
+  const hasBy = args.by !== undefined && args.by !== null;
+  if (hasTo === hasBy) throw new SharedToolError("drag requires exactly one of { to } or { by }");
+  if (hasBy) {
+    const by = args.by as { dx?: number; dy?: number };
+    const hasDx = by.dx !== undefined;
+    const hasDy = by.dy !== undefined;
+    if (!hasDx && !hasDy) throw new SharedToolError("drag: 'by' requires at least one of { dx } or { dy }");
+    const dx = by.dx ?? 0;
+    const dy = by.dy ?? 0;
+    if (!Number.isFinite(dx) || !Number.isFinite(dy)) throw new SharedToolError("drag: 'by.dx' and 'by.dy' must be finite numbers");
+    return { dx, dy };
+  }
+  return resolveDragTo(args.to as { uid?: DriverUid; selector?: string; x?: number; y?: number });
+}
+
+/** Upper bound on drag's interpolated moves. 500 already exceeds what any per-frame-sampling DnD
+ *  library needs (a 60fps drag lasting 8s), and each step is a round-tripped CDP command, so an
+ *  accidental `steps: 100000` would otherwise wedge the call for minutes. Refused, not clamped. */
+const MAX_DRAG_STEPS = 500;
+
+/** drag's `steps`: an integer in [1, MAX_DRAG_STEPS], default 2 (the pre-1.8.0 midpoint +
+ *  destination sequence). Exported for the unit tests. */
+export function resolveDragSteps(steps?: number): number {
+  if (steps === undefined) return 2;
+  if (typeof steps !== "number" || !Number.isInteger(steps) || steps < 1 || steps > MAX_DRAG_STEPS) {
+    throw new SharedToolError(`drag: 'steps' must be an integer between 1 and ${MAX_DRAG_STEPS} (default 2)`);
+  }
+  return steps;
+}
+
+/**
+ * drag's `mode`, plus the ONE backend gate in this file. mode:"html5" needs Capability
+ * "input.html5Drag", which only the Chrome driver declares (Chrome's Input.setInterceptDrags /
+ * dragIntercepted / dispatchDragEvent have no WebDriver BiDi equivalent). Per ADR-001 this is a
+ * PARAM-level gap, not a whole-tool one: `drag` stays in tools/list on Firefox because mouse mode
+ * works there, and asking for html5 on Firefox is a clear validation error — never a silent
+ * downgrade to mouse mode, which would report success for a drop that never happened.
+ * Exported for the unit tests.
+ */
+export function resolveDragMode(mode: string | undefined, capabilities: ReadonlySet<Capability>): "mouse" | "html5" {
+  if (mode === undefined || mode === "mouse") return "mouse";
+  if (mode !== "html5") throw new SharedToolError(`drag: unknown mode '${mode}' (use 'mouse' or 'html5')`);
+  if (!capabilities.has("input.html5Drag")) {
+    throw new SharedToolError(
+      "drag: mode:'html5' is not supported by this backend (WebDriver BiDi has no drag-interception primitive). " +
+        "Omit 'mode' for the synthetic-mouse drag, or use --browser chrome for real HTML5 drag events.",
+    );
+  }
+  return "html5";
+}
+
 export async function drag(
   driver: BrowserDriver,
-  args: { target?: TargetSelector; from: { uid?: DriverUid; selector?: string }; to: { uid?: DriverUid; selector?: string } },
-): Promise<{ dragged: true; from: { x: number; y: number }; to: { x: number; y: number } }> {
-  if (!args.from || !args.to) throw new SharedToolError("drag requires { from } and { to }");
+  args: {
+    target?: TargetSelector;
+    from: { uid?: DriverUid; selector?: string };
+    to?: { uid?: DriverUid; selector?: string; x?: number; y?: number };
+    by?: { dx?: number; dy?: number };
+    mode?: "mouse" | "html5";
+    steps?: number;
+  },
+): Promise<{ dragged: true; mode: "mouse" | "html5"; steps: number; from: { x: number; y: number }; to: { x: number; y: number } }> {
+  if (!args.from) throw new SharedToolError("drag requires { from }");
+  const destination = resolveDragDestination(args);
+  const steps = resolveDragSteps(args.steps);
+  // Capability check BEFORE withPage: an unsupported mode must not claim a lease or open a socket.
+  const mode = resolveDragMode(args.mode, driver.capabilities);
   return withPage(driver, args.target, async (page) => {
-    const { from, to } = await page.drag(locatorOf(args.from), locatorOf(args.to));
-    return { dragged: true, from, to };
+    const { from, to } = await page.drag(locatorOf(args.from), destination, { mode, steps });
+    return { dragged: true, mode, steps, from, to };
   });
 }
 
@@ -775,8 +1014,9 @@ export async function handleDialog(
 
 /* ------------------------------------- registry ------------------------------------- */
 
-/** The 23 tools this file unifies, importable by both src/index.ts (Chrome) and
- *  src/firefox-tools.ts (Firefox). Each function is (driver, args) => Promise<result>. */
+/** The 24 tools this file unifies (23 pre-1.8.0, plus `scroll`, Track P1), importable by both
+ *  src/index.ts (Chrome) and src/firefox-tools.ts (Firefox). Each function is
+ *  (driver, args) => Promise<result>. */
 export const SHARED_TOOLS = {
   list_pages: listPages,
   new_page: newPage,
@@ -792,6 +1032,7 @@ export const SHARED_TOOLS = {
   click,
   hover,
   drag,
+  scroll,
   fill,
   fill_form: fillForm,
   type_text: typeText,

package/src/tools/browser-session.ts

@@ -0,0 +1,246 @@
+/**
+ * browser-session.ts: ONE standing connection to the CDP **browser** endpoint, held open across
+ * tool calls, owning the browser-client-scoped state behind `wait_for_download` and
+ * `grant_permissions` (1.8.0 Track P3).
+ *
+ * WHY A STANDING CONNECTION IS NOT OPTIONAL HERE
+ * ==============================================
+ * The 1.8.0 spec described wait_for_download as "the server subscribes to
+ * Browser.downloadWillBegin/downloadProgress and keeps a ring buffer", which silently assumes a
+ * connection that outlives a tool call. This toolkit's CDP lifetime is per-call (ADR-001,
+ * driver.ts: "per-call": acquiring opens a transport and release() closes it), so that assumption
+ * had to be checked rather than inherited — the same spec had already shipped one false
+ * protocol assertion that Track S1 caught the same way.
+ *
+ * MEASURED, against an isolated headless Chrome 151 on macOS (three controls, one variable — the
+ * arming client's liveness — with the click, the page, and the download path held identical):
+ *
+ *   A. armer connection OPEN across the click .............. BOTH downloads landed in downloadPath;
+ *      Browser.downloadWillBegin + downloadProgress{state:"completed"} arrived on the armer.
+ *   B. armer connection CLOSED before the click ............ ZERO files. No events anywhere.
+ *   C. armed from the PAGE endpoint, then closed .......... ZERO files.
+ *
+ * So `Browser.setDownloadBehavior{behavior:"allowAndName", downloadPath, eventsEnabled:true}` does
+ * NOT persist browser-side after the arming client disconnects: it is per-client state that Chrome
+ * reverts on disconnect, and headless Chrome's default is to deny downloads, so the file does not
+ * merely go somewhere else — it never happens at all.
+ *
+ * The same experiment run for permissions gives the same verdict: `Browser.grantPermissions` on
+ * either endpoint, followed by that connection closing, leaves
+ * `navigator.permissions.query({name:"geolocation"}).state` at "prompt", never "granted". Both
+ * features therefore need a connection someone keeps open. That is this module.
+ *
+ * WHAT A DIRECTORY WATCHER WOULD AND WOULD NOT BUY. Watching downloadPath for a new file (and its
+ * .crdownload disappearing) was the obvious per-call fallback, and it does not work on its own:
+ * with nothing armed, the download is denied and the directory stays empty forever, so the watcher
+ * would poll a directory that can never fill. Once something IS armed, the standing connection
+ * already receives `Browser.downloadProgress{state:"completed", filePath}` — which carries the
+ * finished path directly, so there is nothing left for a watcher to discover. It is not implemented
+ * because it would be strictly redundant, not because it was overlooked.
+ *
+ * LIFETIME AND ITS HONEST LIMIT. The connection is opened LAZILY, on the first call to one of the
+ * two tools, so a session that never downloads and never grants permissions opens nothing and pays
+ * nothing. It then lives until the process exits. Under the MCP server (a long-lived process) that
+ * spans many tool calls, which is what makes "arm, click in a later call, wait in a later call
+ * still" work. Under the CLI — one process per command — it dies at process exit, so both tools are
+ * MCP-server capabilities, exactly like network_mock.ts's persistent fake backends and recorder.ts's
+ * background mode, and for exactly the same reason.
+ *
+ * If the connection dies (browser exited, socket dropped), the arm and every grant made through it
+ * are gone with it; the session is marked dead and the next call opens a fresh one and RE-ARMS the
+ * download behavior it remembers. Permission grants cannot be replayed that way — this module never
+ * pretends a grant survived a reconnect, because a caller told "granted" for a permission the
+ * browser has since forgotten would act on it.
+ */
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { openBrowser, type CdpConnection } from "../client.ts";
+
+/** Artifact root, captured at import exactly like every other module here (screencast, heap, ...). */
+const ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+
+/** Where armed downloads are written, before wait_for_download renames each guid to its filename. */
+export const DOWNLOADS_DIR = join(ARTIFACT_DIR, "downloads");
+
+/** How many finished downloads the ring buffer keeps. Same intent as recorder.ts's buffers: enough
+ *  that a caller who triggered several downloads before waiting gets them all, bounded so a
+ *  long-lived server cannot grow this without limit. */
+export const DOWNLOAD_BUFFER_LIMIT = 50;
+
+/** One download, as the standing connection observed it. */
+export interface DownloadRecord {
+  guid: string;
+  /** Source URL, from Browser.downloadWillBegin. */
+  url?: string;
+  /** The page's own name for the file (the `download` attribute / Content-Disposition). UNTRUSTED:
+   *  it is page-controlled, so downloads.ts sanitizes it before it ever reaches a filesystem path. */
+  suggestedFilename?: string;
+  /** Bytes received, from the terminal Browser.downloadProgress. */
+  bytes?: number;
+  /** Absolute path Chrome wrote, straight off the completed event — never reconstructed by us. */
+  filePath?: string;
+  state: "inProgress" | "completed" | "canceled";
+  /** True once a wait_for_download call has returned this record, so two waits never answer with
+   *  the same download. */
+  consumed: boolean;
+}
+
+interface BrowserSession {
+  conn: CdpConnection;
+  /** The path passed to setDownloadBehavior on this connection; undefined until armed. */
+  armedPath?: string;
+  downloads: DownloadRecord[];
+  /** Resolvers waiting for the next completed download, in FIFO order. */
+  waiters: Array<(r: DownloadRecord) => void>;
+  dead: boolean;
+}
+
+let session: BrowserSession | undefined;
+
+/** True for the errors that mean "this socket is gone", not "the command was rejected". */
+function isDisconnect(e: unknown): boolean {
+  const m = e instanceof Error ? e.message : String(e);
+  return /connection (not open|closed)|closed by caller|websocket|ECONNREFUSED|socket/i.test(m);
+}
+
+function record(s: BrowserSession, guid: string): DownloadRecord {
+  let r = s.downloads.find((d) => d.guid === guid);
+  if (!r) {
+    r = { guid, state: "inProgress", consumed: false };
+    s.downloads.push(r);
+    // Drop the OLDEST already-consumed record first, and only fall back to dropping an unconsumed
+    // one when the buffer is full of them: evicting a download nobody has collected yet is how a
+    // caller silently loses a file they are about to ask for.
+    while (s.downloads.length > DOWNLOAD_BUFFER_LIMIT) {
+      const i = s.downloads.findIndex((d) => d.consumed);
+      s.downloads.splice(i >= 0 ? i : 0, 1);
+    }
+  }
+  return r;
+}
+
+/** Wire the download event handlers onto a freshly opened connection. */
+function subscribe(s: BrowserSession): void {
+  s.conn.on("Browser.downloadWillBegin", (p) => {
+    const r = record(s, String(p.guid));
+    if (typeof p.url === "string") r.url = p.url;
+    if (typeof p.suggestedFilename === "string") r.suggestedFilename = p.suggestedFilename;
+  });
+  s.conn.on("Browser.downloadProgress", (p) => {
+    const r = record(s, String(p.guid));
+    if (typeof p.receivedBytes === "number") r.bytes = p.receivedBytes;
+    if (typeof p.filePath === "string") r.filePath = p.filePath;
+    const state = String(p.state);
+    if (state === "completed" || state === "canceled") {
+      r.state = state;
+      // Hand a completed download straight to the longest-waiting caller. Marking it consumed HERE
+      // (not in the waiter) closes the race where a second waiter, scheduled between this callback
+      // and the first waiter resuming, scans the buffer and claims the same record.
+      if (state === "completed") {
+        const waiter = s.waiters.shift();
+        if (waiter) {
+          r.consumed = true;
+          waiter(r);
+        }
+      }
+    }
+  });
+}
+
+/**
+ * The standing connection, opened on first use and reused forever after. Re-arms the download
+ * behavior when a dead connection is replaced, so a browser restart does not silently leave the
+ * caller unarmed while every call still reports success.
+ */
+export async function getBrowserSession(): Promise<BrowserSession> {
+  if (session && !session.dead) return session;
+  const previousPath = session?.armedPath;
+  const conn = await openBrowser();
+  const s: BrowserSession = { conn, downloads: [], waiters: [], dead: false };
+  subscribe(s);
+  session = s;
+  if (previousPath) await armDownloadsAt(previousPath);
+  return s;
+}
+
+/** Send on the standing connection, marking the session dead if the socket turned out to be gone. */
+export async function browserSend<T = Record<string, unknown>>(method: string, params: Record<string, unknown> = {}): Promise<T> {
+  const s = await getBrowserSession();
+  try {
+    return await s.conn.send<T>(method, params);
+  } catch (e) {
+    if (isDisconnect(e)) {
+      s.dead = true;
+      // One retry on a fresh connection: a socket that died between calls is the expected case
+      // (the browser was restarted), not an error the caller can act on.
+      const fresh = await getBrowserSession();
+      return await fresh.conn.send<T>(method, params);
+    }
+    throw e;
+  }
+}
+
+/** Point Chrome's downloads at `path` on the standing connection, creating the directory first. */
+async function armDownloadsAt(path: string): Promise<void> {
+  await mkdir(path, { recursive: true });
+  const s = await getBrowserSession();
+  await s.conn.send("Browser.setDownloadBehavior", { behavior: "allowAndName", downloadPath: path, eventsEnabled: true });
+  s.armedPath = path;
+}
+
+/**
+ * Ensure downloads are captured to DOWNLOADS_DIR. Idempotent and cheap to repeat: re-issuing
+ * setDownloadBehavior with identical parameters is accepted by Chrome (verified), so every
+ * wait_for_download call can arm without tracking whether some earlier call already did.
+ */
+export async function armDownloads(): Promise<{ downloadPath: string }> {
+  const s = await getBrowserSession();
+  if (s.armedPath !== DOWNLOADS_DIR) await armDownloadsAt(DOWNLOADS_DIR);
+  return { downloadPath: DOWNLOADS_DIR };
+}
+
+/** Completed-but-uncollected downloads, oldest first. */
+export function pendingDownloads(): DownloadRecord[] {
+  return (session?.downloads ?? []).filter((d) => d.state === "completed" && !d.consumed);
+}
+
+/**
+ * The next completed download nobody has collected: one already buffered, else the next one to
+ * finish, else a timeout. Buffered-first is what makes "click in one tool call, wait in a later
+ * one" work — the standing connection recorded the completion while no tool call was running.
+ */
+export async function nextCompletedDownload(timeoutMs: number): Promise<DownloadRecord> {
+  const s = await getBrowserSession();
+  const buffered = s.downloads.find((d) => d.state === "completed" && !d.consumed);
+  if (buffered) {
+    buffered.consumed = true;
+    return buffered;
+  }
+  return new Promise<DownloadRecord>((resolve, reject) => {
+    const waiter = (r: DownloadRecord): void => {
+      clearTimeout(timer);
+      resolve(r);
+    };
+    const timer = setTimeout(() => {
+      const i = s.waiters.indexOf(waiter);
+      if (i >= 0) s.waiters.splice(i, 1);
+      reject(new Error(
+        `wait_for_download: no download completed within ${timeoutMs}ms. Downloads are only captured while this server holds the arming connection, so the triggering click must come AFTER a wait_for_download call (use arm:true to arm without waiting).`,
+      ));
+    }, timeoutMs);
+    s.waiters.push(waiter);
+  });
+}
+
+/** Close the standing connection. For process shutdown and tests; safe to call when none is open. */
+export async function disposeBrowserSession(): Promise<void> {
+  const s = session;
+  session = undefined;
+  if (!s) return;
+  s.dead = true;
+  try {
+    s.conn.close();
+  } catch {
+    /* already gone */
+  }
+}