cdp-toolkit 1.7.0 → 1.9.0

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 */
+  }
+}

package/src/tools/dispatch-mouse.ts

@@ -0,0 +1,108 @@
+/**
+ * dispatch-mouse.ts: `dispatch_mouse` over raw CDP, the toolkit's raw mouse-event primitive.
+ *
+ * WHY THIS IS CHROME-ONLY (capability "input.raw", declared in ../driver.ts /
+ * ../cdp/driver.ts), NOT a PageDriver method
+ * ============================================================================
+ * Every other interaction (click/hover/drag/scroll) is a Driver-neutral, multi-event SEQUENCE:
+ * "resolve an element, then press-and-release". dispatch_mouse is the opposite by design — ONE
+ * raw event per call, composed by the CALLER into whatever sequence a real mouse could produce
+ * (move/down/move/up reaches canvas drag-painting, marquee selection, custom widgets that
+ * click/drag's fixed sequences cannot). CDP's Input.dispatchMouseEvent is a natural fit: it is
+ * genuinely stateless, so "one event, one call" costs nothing extra.
+ *
+ * WebDriver BiDi's input.performActions is a worse fit for this SPECIFIC primitive: it models a
+ * virtual input DEVICE with session-lifetime state (a pointerDown from one call leaves the button
+ * "held" for a later call), not a raw event dispatch, and per the 1.8.0 spec (Track P1 §2) that
+ * mismatch — plus this driver not having been verified against real Firefox for the raw primitive
+ * this pass — earns the explicit "Chrome-only capability... unless bidi is trivial" fallback,
+ * exactly like start_screen_recording. tools/list omits dispatch_mouse under --browser firefox
+ * (ADR-001: absent, never present-and-throwing); nothing in this file runs under that backend.
+ *
+ * Lease gate: `withPage` (client.ts) resolves through `resolveTarget`, which calls
+ * `assertLeaseOk("chrome", ...)` — the same choke point click/hover/drag/scroll go through via
+ * resolvePage (shared-tools.ts). No tool here bypasses it.
+ */
+import { sendInput } from "../activity.ts";
+import { withPage } from "../client.ts";
+import type { TargetSelector } from "../types.ts";
+
+const CLICK_MODIFIER_BITS: Record<string, number> = { Alt: 1, Control: 2, Meta: 4, Shift: 8 };
+const BUTTONS = new Set(["left", "right", "middle"]);
+const CDP_EVENT_TYPE: Record<"move" | "down" | "up", string> = {
+  move: "mouseMoved",
+  down: "mousePressed",
+  up: "mouseReleased",
+};
+
+export interface DispatchMouseArgs {
+  target?: TargetSelector;
+  /** "move" (mouseMoved), "down" (mousePressed), or "up" (mouseReleased). */
+  action: "move" | "down" | "up";
+  /** Viewport-space coordinates. Required on every event: CDP has no notion of "current pointer
+   *  position" to default from. */
+  x: number;
+  y: number;
+  /** Mouse button: 'left' (default), 'right', or 'middle'. */
+  button?: "left" | "right" | "middle";
+  /** Click-run length for a down/up pair (2 = the second half of a double-click). Ignored for 'move'. */
+  clickCount?: number;
+  /** "Alt" | "Control" | "Meta" | "Shift", held for this one event. Same bit values as click's
+   *  modifiers (cdp/driver.ts's inputModifierBits): Alt=1, Control=2, Meta=4, Shift=8. */
+  modifiers?: string[];
+}
+
+export interface DispatchMouseResult {
+  dispatched: "move" | "down" | "up";
+  x: number;
+  y: number;
+}
+
+/** CDP modifier-bit math for the closed Alt/Control/Meta/Shift enum. Exported for the unit tests;
+ *  intentionally duplicated from (not imported from) cdp/driver.ts's identically-named constant,
+ *  so this chrome-only tool module has no dependency on the Driver-abstraction layer it sits
+ *  beside, matching heap.ts/screencast.ts's existing raw-CDP module boundary. */
+export function modifierBits(mods?: readonly string[]): number {
+  let bits = 0;
+  for (const m of mods ?? []) {
+    const bit = CLICK_MODIFIER_BITS[m];
+    if (bit === undefined) throw new Error(`dispatch_mouse: unknown modifier '${m}' (use Alt, Control, Meta, or Shift)`);
+    bits |= bit;
+  }
+  return bits;
+}
+
+/** Argument validation, split out and exported so the unit tests can pin every refusal without a
+ *  browser. Throws on the first violation; returns nothing (the caller re-reads `args`). */
+export function validateDispatchMouseArgs(args: DispatchMouseArgs): void {
+  if (args.action !== "move" && args.action !== "down" && args.action !== "up") {
+    throw new Error("dispatch_mouse requires { action } of 'move', 'down', or 'up'");
+  }
+  if (typeof args.x !== "number" || typeof args.y !== "number" || !Number.isFinite(args.x) || !Number.isFinite(args.y)) {
+    throw new Error("dispatch_mouse requires numeric { x } and { y } on every call");
+  }
+  const button = args.button ?? "left";
+  if (!BUTTONS.has(button)) throw new Error(`dispatch_mouse: unknown button '${button}' (use left, right, or middle)`);
+}
+
+/**
+ * Dispatch exactly one raw mouse event. Composability is the point: a caller reaches anything a
+ * physical mouse can by sequencing move/down/move/up calls itself (canvas drag-painting, marquee
+ * selection, a custom widget that click/drag's fixed sequences cannot drive).
+ */
+export async function dispatchMouse(args: DispatchMouseArgs): Promise<DispatchMouseResult> {
+  validateDispatchMouseArgs(args);
+  const button = args.button ?? "left";
+  const modifiers = modifierBits(args.modifiers);
+  return withPage(args.target, async (conn, target) => {
+    const params: Record<string, unknown> = { type: CDP_EVENT_TYPE[args.action], x: args.x, y: args.y, button, modifiers };
+    if (args.action !== "move") params.clickCount = args.clickCount ?? 1;
+    // Through activity.ts's sendInput, NOT conn.send: this event has to land in the dispatch log or
+    // the activity beacon reads the toolkit's own mouse as a human's and warns about contention with
+    // itself. sendInput is the shared writer CdpPageDriver.dispatchInput also delegates to — the one
+    // import this module takes from outside its own raw-CDP boundary, and the reason the file header's
+    // "not a PageDriver method" argument costs nothing in bookkeeping.
+    await sendInput(conn, "chrome", target.id, "Input.dispatchMouseEvent", params);
+    return { dispatched: args.action, x: args.x, y: args.y };
+  });
+}

package/src/tools/downloads.ts

@@ -0,0 +1,143 @@
+/**
+ * downloads.ts: `wait_for_download` — block until a file download finishes, then hand back a real
+ * path on disk with the page's own filename (1.8.0 Track P3).
+ *
+ * WHY THIS IS CHROME-ONLY (capability "browser.downloads"), NOT a PageDriver method
+ * ================================================================================
+ * A download is browser-scoped, not page-scoped: Browser.setDownloadBehavior, Browser.downloadWillBegin
+ * and Browser.downloadProgress all live on the CDP browser endpoint, and the download a caller
+ * cares about may be started by a click in one tab and finish while another is focused. There is no
+ * page handle to hang it off, so it stays out of the Driver interface entirely, exactly like
+ * dispatch-mouse.ts and screencast.ts. WebDriver BiDi has browsingContext.downloadWillBegin and
+ * downloadEnd events but NO command to redirect a download to a directory of our choosing, so
+ * Firefox cannot deliver the "here is the file" half of this tool at all: per ADR-001 it is absent
+ * from tools/list under --browser firefox rather than present and throwing.
+ *
+ * THE ORDERING RULE, and why it is a rule rather than a wart
+ * ---------------------------------------------------------
+ * Download capture must be ARMED BEFORE the click that starts the download. That is not a design
+ * preference; it is Chrome's behavior, measured (see browser-session.ts's header for the three
+ * controls): the download-behavior override is per-client state, reverted the moment the arming
+ * connection disconnects, and unarmed headless Chrome denies the download outright. So:
+ *
+ *     wait_for_download { arm: true }     <- arms, returns immediately, connection stays open
+ *     click { selector: "#export" }       <- the download starts and COMPLETES, captured meanwhile
+ *     wait_for_download {}                <- returns the file that finished during the click call
+ *
+ * The last step works because the standing connection buffered the completion while no tool call
+ * was running. A caller who does not want two round trips can also do click-then-wait in the other
+ * order (`wait_for_download` arms on every call), but only if something armed earlier in the same
+ * server process — the FIRST download of a process must be preceded by an arm.
+ *
+ * Lease gate: this tool resolves `target` through client.ts's resolveTarget, which calls
+ * assertLeaseOk — the same choke point every other Chrome tool passes through. It resolves a target
+ * even though the CDP work is browser-scoped precisely so that gate is not skipped, and so the
+ * result names the tab the caller believed it was working in.
+ */
+import { readdir, rename, stat } from "node:fs/promises";
+import { basename, extname, join } from "node:path";
+import { resolveTarget } from "../client.ts";
+import type { TargetSelector } from "../types.ts";
+import { DOWNLOADS_DIR, armDownloads, nextCompletedDownload, pendingDownloads } from "./browser-session.ts";
+
+export interface WaitForDownloadArgs {
+  target?: TargetSelector;
+  /** Arm download capture and return immediately, without waiting for a download. */
+  arm?: boolean;
+  /** How long to wait for a download to complete. Default 30000. */
+  timeoutMs?: number;
+}
+
+export interface WaitForDownloadResult {
+  path: string;
+  suggestedFilename: string;
+  bytes: number;
+  url?: string;
+  target: { id: string; url: string; title: string };
+}
+
+export interface ArmDownloadResult {
+  armed: true;
+  downloadPath: string;
+  /** Completed downloads already buffered and not yet collected, so an arm call is also a peek. */
+  pending: number;
+  target: { id: string; url: string; title: string };
+}
+
+/**
+ * A page-supplied filename reduced to something safe to join onto a directory.
+ *
+ * `suggestedFilename` comes from the page (an `<a download>` attribute or a Content-Disposition
+ * header), so it is ATTACKER-CONTROLLED in the ordinary case of driving an untrusted site. A name
+ * like "../../../../etc/cron.d/x" or "/etc/passwd" would otherwise be joined straight onto the
+ * downloads directory and escape it. Everything up to the last separator is discarded, then the
+ * traversal and hidden-file edge cases ("", ".", "..") fall back to a fixed name. Pure, and
+ * exported so every one of those cases is pinned by a unit test.
+ */
+export function safeFilename(suggested: string | undefined): string {
+  const raw = (suggested ?? "").replace(/[\u0000-\u001f]/g, "");
+  // basename() on the platform separator, plus an explicit backslash split, so a Windows-style
+  // path in a header cannot survive on a POSIX host where basename() would treat it as one name.
+  const name = basename(raw.split("\\").pop() ?? "").trim();
+  if (!name || name === "." || name === "..") return "download";
+  return name;
+}
+
+/**
+ * `name`, or the first "name-N.ext" that is not already taken. Suffixed before the extension so a
+ * collided "report.csv" stays a .csv file, which is the difference between the caller's next tool
+ * opening it and not.
+ */
+export function nextFreeName(name: string, taken: ReadonlySet<string>): string {
+  if (!taken.has(name)) return name;
+  const ext = extname(name);
+  const stem = ext ? name.slice(0, -ext.length) : name;
+  for (let i = 1; ; i++) {
+    const candidate = `${stem}-${i}${ext}`;
+    if (!taken.has(candidate)) return candidate;
+  }
+}
+
+/** Validation split out so the refusals are unit-testable without a browser. */
+export function validateWaitForDownloadArgs(args: WaitForDownloadArgs): void {
+  if (args.timeoutMs !== undefined) {
+    if (typeof args.timeoutMs !== "number" || !Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0) {
+      throw new Error(`wait_for_download: 'timeoutMs' must be a positive number (got ${JSON.stringify(args.timeoutMs)})`);
+    }
+  }
+  if (args.arm !== undefined && typeof args.arm !== "boolean") {
+    throw new Error(`wait_for_download: 'arm' must be a boolean (got ${JSON.stringify(args.arm)})`);
+  }
+}
+
+/**
+ * Wait for the next completed download and return it as a named file on disk.
+ *
+ * With `arm:true` this only arms capture and returns — no waiting, no file. See the file header for
+ * why arming has to happen before the triggering click.
+ */
+export async function waitForDownload(args: WaitForDownloadArgs = {}): Promise<WaitForDownloadResult | ArmDownloadResult> {
+  validateWaitForDownloadArgs(args);
+  // The lease gate, before any browser state is touched.
+  const t = await resolveTarget(args.target);
+  const target = { id: t.id, url: t.url, title: t.title };
+  const { downloadPath } = await armDownloads();
+  if (args.arm === true) return { armed: true, downloadPath, pending: pendingDownloads().length, target };
+
+  const rec = await nextCompletedDownload(args.timeoutMs ?? 30_000);
+  if (!rec.filePath) {
+    throw new Error(`wait_for_download: download ${rec.guid} completed without a file path (nothing to return)`);
+  }
+  const suggestedFilename = safeFilename(rec.suggestedFilename);
+  // Read the directory at rename time, not earlier: another download may have landed while this
+  // call was waiting, and the collision set has to reflect the directory as it is now.
+  const taken = new Set(await readdir(DOWNLOADS_DIR).catch(() => [] as string[]));
+  taken.delete(basename(rec.filePath)); // our own guid file is not a collision with itself
+  const finalName = nextFreeName(suggestedFilename, taken);
+  const path = join(DOWNLOADS_DIR, finalName);
+  await rename(rec.filePath, path);
+  // Size from the file itself, not from the event's receivedBytes: the file on disk is what the
+  // caller is about to read, and it is the only number that cannot disagree with it.
+  const bytes = (await stat(path)).size;
+  return { path, suggestedFilename, bytes, ...(rec.url ? { url: rec.url } : {}), target };
+}

package/src/tools/permissions.ts

@@ -0,0 +1,130 @@
+/**
+ * permissions.ts: `grant_permissions` — answer the browser's permission prompts up front, so a page
+ * that asks for geolocation / notifications / clipboard gets a decision instead of a modal an
+ * agent cannot click (1.8.0 Track P3).
+ *
+ * WHY THIS IS CHROME-ONLY (capability "browser.permissions"), NOT a PageDriver method
+ * ==================================================================================
+ * Browser.grantPermissions and Browser.resetPermissions are browser-endpoint commands keyed by
+ * ORIGIN, not by tab: a grant made "for" one tab applies to every tab on that origin, including
+ * ones opened later. There is no page-scoped concept to put on the Driver interface, so this stays
+ * a raw-CDP module like dispatch-mouse.ts. WebDriver BiDi's permission handling lives in an
+ * optional module this driver does not negotiate, so under Firefox the tool is absent from
+ * tools/list per ADR-001 rather than present and throwing.
+ *
+ * THE STANDING-CONNECTION REQUIREMENT (measured, not assumed)
+ * ----------------------------------------------------------
+ * A grant is bound to the CDP client that issued it and is REVERTED when that client disconnects.
+ * Measured on isolated headless Chrome 151: grant geolocation for an origin, close the granting
+ * connection, then query `navigator.permissions.query({name:"geolocation"}).state` over a fresh
+ * connection — the answer is "prompt", not "granted". Identical result granting from the page
+ * endpoint instead of the browser endpoint. A per-call implementation of this tool would therefore
+ * report `{granted:["geolocation"]}` and leave the browser in exactly the state it started in,
+ * which is the worst possible outcome: a caller acting on a grant that does not exist.
+ *
+ * So every command here goes through browser-session.ts's standing connection, and the grant lasts
+ * as long as that connection does — the life of the MCP server process. Under the stateless CLI
+ * (one process per command) the grant dies with the process, which makes this an MCP-server
+ * capability like network_mock.ts's fake backends. That limit is stated in the manifest description
+ * rather than papered over.
+ *
+ * Lease gate: `target` is resolved through client.ts's resolveTarget (which calls assertLeaseOk)
+ * before anything is granted — both to keep the gate on the path and because the resolved tab's URL
+ * is what `origin` defaults to.
+ */
+import { resolveTarget } from "../client.ts";
+import type { TargetSelector } from "../types.ts";
+import { browserSend } from "./browser-session.ts";
+
+export interface GrantPermissionsArgs {
+  target?: TargetSelector;
+  /** CDP PermissionType values, e.g. "geolocation", "notifications", "clipboardReadWrite". */
+  permissions?: string[];
+  /** Origin the grant applies to, e.g. "https://example.com". Defaults to the target tab's origin. */
+  origin?: string;
+  /** Reset every permission this session granted before granting (or, with no `permissions`, instead). */
+  reset?: boolean;
+}
+
+export interface GrantPermissionsResult {
+  granted?: string[];
+  origin?: string;
+  reset?: true;
+  target: { id: string; url: string; title: string };
+}
+
+/**
+ * The origin a permission grant should default to for a tab at `url`, or undefined when the tab has
+ * no grantable origin.
+ *
+ * `data:`, `blob:`, `about:blank` and friends all serialize to the opaque origin "null", which
+ * Browser.grantPermissions cannot key on. Returning undefined (rather than the string "null") is
+ * what lets the caller be told to pass `origin` explicitly, instead of getting a protocol error
+ * about a value they never supplied. Pure, and exported for the unit tests.
+ */
+export function originOf(url: string): string | undefined {
+  try {
+    const o = new URL(url).origin;
+    return o && o !== "null" ? o : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Validation split out so every refusal is pinned by a unit test without a browser. */
+export function validateGrantPermissionsArgs(args: GrantPermissionsArgs): void {
+  const reset = args.reset === true;
+  if (args.reset !== undefined && typeof args.reset !== "boolean") {
+    throw new Error(`grant_permissions: 'reset' must be a boolean (got ${JSON.stringify(args.reset)})`);
+  }
+  if (args.permissions === undefined) {
+    // reset-only is the one legal way to call this with nothing to grant.
+    if (!reset) throw new Error("grant_permissions: 'permissions' is required (or pass reset:true to clear previous grants)");
+    return;
+  }
+  if (!Array.isArray(args.permissions)) {
+    throw new Error(`grant_permissions: 'permissions' must be an array of CDP PermissionType strings (got ${JSON.stringify(args.permissions)})`);
+  }
+  // An empty array is refused rather than treated as "grant nothing": it is a caller who built the
+  // list dynamically and got zero entries, and answering {granted:[]} would report success for a
+  // call that changed nothing.
+  if (args.permissions.length === 0 && !reset) {
+    throw new Error("grant_permissions: 'permissions' must not be empty (pass reset:true if the intent is to clear grants)");
+  }
+  for (const p of args.permissions) {
+    if (typeof p !== "string" || p.length === 0) {
+      throw new Error(`grant_permissions: every entry of 'permissions' must be a non-empty string (got ${JSON.stringify(p)})`);
+    }
+  }
+}
+
+/**
+ * Grant browser permissions for an origin, and/or reset previously granted ones.
+ *
+ * `reset:true` with `permissions` resets FIRST and then grants, so the result is exactly the listed
+ * permissions rather than the listed ones unioned with whatever was granted earlier. Note that
+ * Browser.resetPermissions takes no origin — CDP resets this client's grants for every origin at
+ * once — so a reset is not scoped to `origin` even though a grant is.
+ */
+export async function grantPermissions(args: GrantPermissionsArgs = {}): Promise<GrantPermissionsResult> {
+  validateGrantPermissionsArgs(args);
+  const t = await resolveTarget(args.target);
+  const target = { id: t.id, url: t.url, title: t.title };
+  const reset = args.reset === true;
+  const permissions = args.permissions ?? [];
+
+  if (reset) await browserSend("Browser.resetPermissions", {});
+  if (permissions.length === 0) return { reset: true, target };
+
+  const origin = args.origin ?? originOf(t.url);
+  if (!origin) {
+    throw new Error(
+      `grant_permissions: cannot derive an origin from the target tab's url (${JSON.stringify(t.url)}); pass 'origin' explicitly, e.g. origin:"https://example.com"`,
+    );
+  }
+  // Chrome rejects an unknown PermissionType by name ("Unknown permission type: ..."), so a typo
+  // surfaces as a clear protocol error rather than a silently-ignored entry. No local allowlist is
+  // kept here: it would go stale against Chrome's own enum and start refusing valid permissions.
+  await browserSend("Browser.grantPermissions", { origin, permissions });
+  return { granted: [...permissions], origin, ...(reset ? { reset: true as const } : {}), target };
+}

package/src/types.ts

@@ -41,6 +41,26 @@ export interface CdpEvent<P = Record<string, unknown>> {
  *   - "index:N"              -> Nth page-type target (0-based)
  *   - "url:<substring>"      -> first page whose url contains substring
  *   - "title:<substring>"    -> first page whose title contains substring
+ *   - "label:<name>"         -> the page-type target whose label EXACTLY
+ *     matches `name`, checked against both the origin ledger (agent-created
+ *     tabs, see src/origins.ts) and live lease records (covers a taken-over
+ *     tab claimed with a label, which has no origin record — see
+ *     src/leases-tools.ts's claimPage). The resolved id must be present in
+ *     the listing this call is resolving against; a label whose tab is gone
+ *     falls through to the normal no-match error. A miss enumerates the
+ *     labels that DO exist; two live targets sharing a label is an ambiguity
+ *     error naming both ids, never a silent first-match. See pickPage in
+ *     src/shared-tools.ts.
+ *   - "worker:<substring>"    -> a service_worker/shared_worker target whose
+ *     URL contains the substring (an MV3 extension's background worker is
+ *     `chrome-extension://<id>/<script>`, so both the extension id and the
+ *     script name match). NOT UNIVERSAL, unlike every arm above it: resolved
+ *     only by Chrome's pickTarget (this file's resolveTarget), accepted only by
+ *     evaluate_script, refused with a capability error on Firefox and by the
+ *     page-only resolvers. It reads the UNFILTERED target listing, because a
+ *     worker is not a page target — and a worker that is idle-evicted is in no
+ *     listing at all, which is what evaluate_script's `wake` exists for. See
+ *     src/workers.ts and src/cdp/workers.ts.
  */
 export type TargetSelector = string | undefined;