cdp-toolkit 1.7.0 → 1.8.0

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 };
+}