cdp-toolkit 1.6.0 → 1.8.0

package/src/mcp.ts

@@ -19,11 +19,12 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 import { TOOLS, TOOL_NAMES, BASE } from "./index.ts";
 import { MANIFEST } from "./manifest.ts";
 import { resolveBrowserKind, stripBrowserFlag, getOrCreateFirefoxSession, disposeFirefoxSession } from "./backend.ts";
+import { disposeBrowserSession } from "./tools/browser-session.ts";
 import { toolAvailability } from "./capabilities.ts";
 import { FIREFOX_TOOLS } from "./firefox-tools.ts";
-import { leaseFromArgs, withLeaseScope } from "./leases.ts";
+import { leaseFromArgs, markLongLivedProcess, withLeaseScope } from "./leases.ts";
 
-const VERSION = "1.6.0";
+const VERSION = "1.8.0";
 
 // --browser is read once at startup (MCP has no per-call notion of backend): explicit flag,
 // else CDP_BROWSER env var, else "chrome" (zero behavior change for existing users/configs).
@@ -100,6 +101,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 });
 
 auditCoverage();
+// This process is the long-lived MCP server, which is what makes strict mode
+// (CDP_REQUIRE_LEASE) safe to honor here and unsafe in cli.ts. See requireLease.
+markLongLivedProcess();
 await server.connect(new StdioServerTransport());
 console.error(`[cdp-toolkit] MCP server v${VERSION} ready, browser=${BROWSER}, ${AVAILABILITY.available.length} tools, CDP_BASE=${BASE}`);
 
@@ -112,6 +116,10 @@ async function shutdown(): Promise<void> {
   if (shuttingDown) return;
   shuttingDown = true;
   await disposeFirefoxSession();
+  // The standing browser-endpoint connection behind wait_for_download / grant_permissions (1.8.0
+  // Track P3). Unlike Firefox it owns no OS process, so process.exit would collect it anyway; it is
+  // closed explicitly so shutdown does not depend on that, and is a no-op when neither tool ran.
+  await disposeBrowserSession();
   process.exit(0);
 }
 process.on("SIGINT", () => void shutdown());

package/src/reap.ts

@@ -0,0 +1,165 @@
+/**
+ * Closing tabs whose agent died, without a background sweeper.
+ *
+ * WHY REAP AT ALL. release_page closes a tab an agent gives back, but an agent
+ * that crashes, is killed, or simply stops calling never gives anything back.
+ * Its tab stays open forever with a lease file nobody will ever release. That
+ * is the failure this module exists for, and it is the common one: a timeout is
+ * a more likely end to an agent than a clean shutdown.
+ *
+ * WHY REAP-ON-READ AND NOT A SWEEPER. Same reasoning as origins.ts's ledger: a
+ * background sweeper is a second lifetime to reason about and a process that
+ * has to be running. list_pages and list_leases already hold the browser's
+ * target list and the lease directory at the moment they run, so doing it there
+ * costs one extra pass over data already in hand and needs nothing scheduled.
+ *
+ * WHY THE SELECTION IS A PURE FUNCTION. Every mistake in this module closes a
+ * tab someone wanted. A pure selector over plain data is testable across the
+ * whole matrix of {provenance} x {lease state} x {liveness} with no browser and
+ * no filesystem, which is the only way to be confident about a destructive
+ * operation. The impure wrapper below does nothing but call it and act.
+ *
+ * WHY REAPING SPLIT FROM RECLAIMABILITY (1.8.0). Before this version `expired`
+ * meant one thing everywhere: at ttlMs, both "another agent may take this
+ * lease" AND "this tab gets closed" fired at once. That is wrong for the
+ * second question and right for the first: a lease going reclaimable at ttlMs
+ * is cheap and reversible, but closing someone's tab is not, and an agent 20
+ * minutes into a build between browser calls looks identical to one that died.
+ * leases.ts's staleReason keeps deciding reclaimability at ttlMs, unchanged;
+ * this module alone additionally waits reapGraceMs past that before treating
+ * `expired` as grounds to close anything. See staleAgentTabs' condition 4.
+ */
+import type { BrowserDriver } from "./driver.ts";
+import { listLeases, releaseLeaseFor, type LeaseBackend, type LeaseSummary } from "./leases.ts";
+import { originIndex, type OriginSummary } from "./origins.ts";
+
+export interface ReapedTab {
+  targetId: string;
+  label: string;
+  /** Why it was reaped. Deliberately narrower than LeaseStaleReason: see below. */
+  reason: "dead-pid" | "expired";
+}
+
+export interface ReapInput {
+  backend: LeaseBackend;
+  /**
+   * Ids from the PAGE-ONLY listing, never from an `all:true` listing. A worker,
+   * iframe or background page can carry a lease (pickPage's bare-id branch
+   * resolves non-page targets), and "close the stale tab" is meaningless for
+   * one. This is a different set from the one shared-tools' reapSet feeds to the
+   * origin ledger, which deliberately uses the unfiltered listing so a live but
+   * filtered-out target does not lose its provenance record. Two reaps, two
+   * questions, two id sets: do not merge them.
+   */
+  livePageIds: readonly string[];
+  origins: ReadonlyMap<string, OriginSummary>;
+  leases: readonly LeaseSummary[];
+  /** Clock for the grace check below. Threaded in rather than read internally
+   *  (Date.now()) so this function stays pure and the whole matrix is testable
+   *  with no wall clock. */
+  now: number;
+  /** How much longer an `expired` lease survives before its tab is destroyed,
+   *  on top of the ttlMs that already made it reclaimable. See reapGraceMs(). */
+  reapGraceMs: number;
+}
+
+/**
+ * Select the tabs that may be closed. PURE: no I/O, no driver, no clock.
+ *
+ * All conditions must hold, and condition 4 (the grace check) is new in 1.8.0:
+ *
+ *  1. the lease row is for this backend and READABLE. An `unreadable` row is
+ *     never reaped for the same reason listLeases reports it as stale:false -
+ *     we cannot see who owns it, and a guess in the destructive direction is
+ *     the one guess that cannot be undone.
+ *  2. it is stale for `dead-pid` or `expired`. NOT `target-gone`, which means
+ *     the tab is already closed and there is nothing to do, and obviously not
+ *     `false`.
+ *  3. the target is actually still open, per livePageIds.
+ *  4. THE GRACE WINDOW. `stale === "expired"` alone is the RECLAIMABILITY
+ *     signal (see leases.ts's staleReason): it fires at ttlMs and is cheap and
+ *     reversible — another agent may simply take the lease. Closing the tab is
+ *     a different, destructive question, and it does not fire until an
+ *     ADDITIONAL reapGraceMs has elapsed past that same ttlMs, so an agent that
+ *     is 20 minutes into a build between browser calls gets a window to come
+ *     back before its tab is destroyed. `dead-pid` skips this check entirely:
+ *     a process that no longer exists is never coming back to reclaim
+ *     anything, so there is nothing to wait for, and that is why dead-pid stays
+ *     immediate while expired does not.
+ *  5. the toolkit OPENED it. An agent-created tab with NO lease is deliberately
+ *     never reaped: that is exactly what new_page produces for a user who never
+ *     touches leases, and closing those would be a data-loss bug rather than a
+ *     cleanup. Only a tab that was claimed and then abandoned qualifies.
+ */
+export function staleAgentTabs(input: ReapInput): ReapedTab[] {
+  const live = new Set(input.livePageIds);
+  const out: ReapedTab[] = [];
+  for (const row of input.leases) {
+    if (row.backend !== input.backend) continue;
+    if (row.unreadable !== undefined) continue;
+    if (row.stale !== "dead-pid" && row.stale !== "expired") continue;
+    if (row.stale === "expired" && input.now - row.lastUsedAt <= row.ttlMs + input.reapGraceMs) continue;
+    if (!live.has(row.targetId)) continue;
+    const origin = input.origins.get(row.targetId);
+    if (origin === undefined || origin.unreadable !== undefined) continue;
+    out.push({ targetId: row.targetId, label: row.label, reason: row.stale });
+  }
+  return out;
+}
+
+/**
+ * 45 minutes. Combined with the default 15-minute lease TTL (leases.ts), the
+ * total fuse from an agent's last touch to its tab being destroyed is 60
+ * minutes — generous, because the cost of guessing wrong here is a tab an
+ * agent was still using getting closed out from under it, not merely a lease
+ * another agent could have taken.
+ */
+export const DEFAULT_REAP_GRACE_MS = 2_700_000;
+
+/** Read per call, not at module load, so a test can redirect the value — same
+ *  rule as leaseTtlMs() in leases.ts. Unlike a TTL, zero is a legitimate
+ *  override (disables the grace period, reverting to at-TTL reaping), so the
+ *  validity check is `>= 0` rather than `> 0`. */
+export function reapGraceMs(): number {
+  const raw = Number(process.env.CDP_REAP_GRACE_MS);
+  return Number.isFinite(raw) && raw >= 0 ? raw : DEFAULT_REAP_GRACE_MS;
+}
+
+/**
+ * Select, close, and drop the leases. Returns ONLY the tabs actually closed.
+ *
+ * A close that fails is not reported, and that asymmetry is deliberate: the
+ * caller filters its listing by this array, so reporting a tab we failed to
+ * close would hide a tab that is still open. Failing quietly leaves the tab
+ * visible and the lease in place, and the next read tries again.
+ *
+ * The lease file is unlinked; the ORIGIN record is not. listOrigins already
+ * reaps records for targets the browser no longer has, so the record disappears
+ * on the next listing. One lifetime rule for origin records, not three.
+ */
+export async function reapStaleAgentTabs(driver: BrowserDriver, backend: LeaseBackend): Promise<ReapedTab[]> {
+  // ONE clock reading, shared with listLeases' own staleReason classification
+  // below: the "expired" verdict a lease reads at and the grace check applied
+  // to it here must agree on what "now" was, or the two could disagree at the
+  // margin.
+  const now = Date.now();
+  // The PAGE-ONLY listing: see ReapInput.livePageIds.
+  const livePageIds = (await driver.listPages()).map((p) => p.id);
+  const [origins, leases] = await Promise.all([
+    // undefined liveIds = reap nothing from the ledger here. Reaping origin
+    // records is list_pages' job and it uses a DIFFERENT id set (the unfiltered
+    // listing); doing it here too would delete records for targets that are
+    // live but filtered out of the page-only view.
+    originIndex(backend, undefined),
+    listLeases({ now, liveIds: livePageIds, liveBackend: backend }).catch(() => [] as LeaseSummary[]),
+  ]);
+  const candidates = staleAgentTabs({ backend, livePageIds, origins, leases, now, reapGraceMs: reapGraceMs() });
+  const closed: ReapedTab[] = [];
+  for (const c of candidates) {
+    const res = await driver.closePage(c.targetId).catch(() => ({ success: false }));
+    if (res.success !== true) continue;
+    await releaseLeaseFor(backend, c.targetId);
+    closed.push(c);
+  }
+  return closed;
+}

package/src/shared-tools.ts

@@ -36,11 +36,16 @@
 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, 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";
 
 const ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 const STATE_DIR = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
@@ -70,7 +75,9 @@ async function withPage<T>(driver: BrowserDriver, target: TargetSelector | undef
   }
 }
 
-async function resolvePage(driver: BrowserDriver, selector?: TargetSelector): Promise<PageInfo> {
+/** Exported for leases-tools.ts's release_page{target}, which needs exactly this
+ *  gate: resolving through here is what authorizes the release. */
+export async function resolvePage(driver: BrowserDriver, selector?: TargetSelector): Promise<PageInfo> {
   const pages = await driver.listPages();
   const hit = await pickPage(driver, pages, selector);
   // THE third choke point. close_page and select_page resolve here and nowhere
@@ -93,8 +100,17 @@ async function resolvePage(driver: BrowserDriver, selector?: TargetSelector): Pr
  * every branch resolves against page-type targets only EXCEPT a bare-id lookup, which (like
  * legacy resolveTarget's `targets.find`) searches the FULL unfiltered listing, so passing an
  * exact non-page targetId (a worker, an iframe) still resolves.
+ *
+ * THE GATE-FREE HALF of resolvePage, and exported for the one caller that needs
+ * resolution WITHOUT authorization: claim_page{target}. Everything else must go
+ * through resolvePage. Claiming cannot run assertLeaseOk, because under
+ * CDP_REQUIRE_LEASE the gate AUTO-ACQUIRES a lease on an unleased tab, so a
+ * claim routed through it would take the tab twice — once implicitly with an
+ * auto lease, then again explicitly, and the second claim would collide with
+ * the first. Refusing a tab another process holds is still enforced, one layer
+ * down, by claimLease's own conflict check.
  */
-async function pickPage(driver: BrowserDriver, pages: PageInfo[], selector?: TargetSelector): Promise<PageInfo> {
+export async function pickPage(driver: BrowserDriver, pages: PageInfo[], selector?: TargetSelector): Promise<PageInfo> {
   if (selector === undefined || selector === "active") {
     if (!pages.length) throw new SharedToolError("no page targets open");
     return pages[0]!;
@@ -154,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;
 }
 
 /**
@@ -176,19 +217,58 @@ async function reapSet(driver: BrowserDriver, pages: PageInfo[], all?: boolean):
   }
 }
 
-export async function listPages(driver: BrowserDriver, args: { all?: boolean } = {}): Promise<{ pages: ListedPage[]; count: number }> {
-  const pages = await driver.listPages({ all: args.all });
+export async function listPages(
+  driver: BrowserDriver,
+  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, 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 };
-  });
-  return { pages: annotated, count: annotated.length };
+  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.
+  return { pages: annotated, count: annotated.length, ...(reaped.length ? { reaped } : {}) };
 }
 
 export async function newPage(
@@ -199,13 +279,29 @@ export async function newPage(
   // Creates the tab AND writes its creation record. The record outlives any
   // lease taken below, which is the point: a released tab is still an agent's.
   const p = await newTrackedPage(driver, backendOf(driver), { url: args.url, label });
-  if (args.claim !== true) return { targetId: p.id, url: p.url };
+  // Under strict mode a tab nobody holds is a tab nobody may drive, so creating
+  // one without claiming it would hand back a target the very next call has to
+  // auto-acquire anyway. Doing it here means the tab is never briefly unowned
+  // AND the caller is handed a token it can release with, which matters because
+  // an auto-acquired lease never returns one.
+  const explicit = args.claim === true;
+  if (!explicit && !requireLease()) return { targetId: p.id, url: p.url };
   // Atomic in the sense that matters: the tab is claimed before this call
   // returns, so no other agent can see it unclaimed and take it first.
   const { record, token } = await claimLease(backendOf(driver), p.id, {
     label,
     ttlMs: typeof args.ttlMs === "number" && args.ttlMs > 0 ? args.ttlMs : leaseTtlMs(),
+    // An explicit claim:true stays explicit under strict mode: the caller asked
+    // for the strong tier and must keep getting it, or turning strict on would
+    // 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 };
 }
 
@@ -254,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),
     };
   });
@@ -588,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));
@@ -603,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 };
   });
 }
 
@@ -743,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,
@@ -760,6 +1032,7 @@ export const SHARED_TOOLS = {
   click,
   hover,
   drag,
+  scroll,
   fill,
   fill_form: fillForm,
   type_text: typeText,