cdp-toolkit 1.7.0 → 1.8.0

package/dist/mcp.js

@@ -486,6 +486,141 @@ async function withPage(selector, fn, opts = {}) {
   }
 }
 
+// src/activity.ts
+var BEACON_DATA_GLOBAL = "__cdpToolkitLastInput";
+var BEACON_INSTALLED_GLOBAL = "__cdpToolkitBeacon";
+var BEACON_EVENTS = ["pointerdown", "mousedown", "keydown", "wheel", "touchstart"];
+var BEACON_BODY = `
+  if (!window.${BEACON_INSTALLED_GLOBAL}) {
+    window.${BEACON_INSTALLED_GLOBAL} = true;
+    var mark = function () { window.${BEACON_DATA_GLOBAL} = Date.now(); };
+    var events = ${JSON.stringify([...BEACON_EVENTS])};
+    for (var i = 0; i < events.length; i++) {
+      window.addEventListener(events[i], mark, { capture: true, passive: true });
+    }
+  }`;
+var BEACON_SOURCE = `(function () {${BEACON_BODY}
+})();`;
+var BEACON_FUNCTION_DECLARATION = `function () {${BEACON_BODY}
+}`;
+var BEACON_READ_EXPRESSION = `(typeof window.${BEACON_DATA_GLOBAL} === "number" ? window.${BEACON_DATA_GLOBAL} : null)`;
+var DISPATCH_ATTRIBUTION_WINDOW_MS = 1500;
+function dispatchKey(backend, targetId) {
+  return `${backend}:${targetId}`;
+}
+var dispatchLog = new Map;
+var DISPATCH_LOG_LIMIT = 512;
+function recordDispatch(backend, targetId, now = Date.now()) {
+  const key = dispatchKey(backend, targetId);
+  dispatchLog.delete(key);
+  dispatchLog.set(key, now);
+  while (dispatchLog.size > DISPATCH_LOG_LIMIT) {
+    const oldest = dispatchLog.keys().next();
+    if (oldest.done)
+      break;
+    dispatchLog.delete(oldest.value);
+  }
+}
+var NON_SYNTHESIZING_INPUT_METHODS = new Set(["Input.setInterceptDrags", "Input.setIgnoreInputEvents"]);
+async function sendInput(conn, backend, targetId, method, params = {}) {
+  if (!NON_SYNTHESIZING_INPUT_METHODS.has(method))
+    recordDispatch(backend, targetId);
+  return conn.send(method, params);
+}
+function lastDispatchAt(backend, targetId) {
+  return dispatchLog.get(dispatchKey(backend, targetId));
+}
+function isHumanAttributed(beaconTs, dispatchAt, windowMs = DISPATCH_ATTRIBUTION_WINDOW_MS) {
+  if (typeof beaconTs !== "number" || !Number.isFinite(beaconTs))
+    return false;
+  return beaconTs > (dispatchAt ?? 0) + windowMs;
+}
+function humanActiveMs(beaconTs, dispatchAt, now = Date.now(), windowMs = DISPATCH_ATTRIBUTION_WINDOW_MS) {
+  if (!isHumanAttributed(beaconTs, dispatchAt, windowMs))
+    return null;
+  return Math.max(0, now - beaconTs);
+}
+var CONTENTION_WINDOW_MS = 30000;
+function contentionWarning(ms, opts) {
+  if (!opts.takeover)
+    return;
+  if (ms === null || ms >= CONTENTION_WINDOW_MS)
+    return;
+  return `a person appears to be using this tab right now: input not dispatched by this server landed ${ms}ms ago. ` + `The claim SUCCEEDED and you hold the lease — this is a warning, not a refusal. ` + `Driving the tab now will fight them for the keyboard and mouse. ` + `Consider claim_page with no target to work in your own tab instead, or ask before continuing.`;
+}
+function beaconSupported(driver) {
+  return typeof driver.installActivityBeacon === "function" && typeof driver.readActivityBeacon === "function";
+}
+async function installBeacon(driver, targetId) {
+  if (typeof driver.installActivityBeacon !== "function")
+    return false;
+  return driver.installActivityBeacon(targetId).catch(() => false);
+}
+async function readHumanActiveMs(driver, backend, targetId, now = Date.now()) {
+  if (typeof driver.readActivityBeacon !== "function")
+    return null;
+  const beaconTs = await driver.readActivityBeacon(targetId).catch(() => null);
+  return humanActiveMs(beaconTs, lastDispatchAt(backend, targetId), now);
+}
+var RENDERER_PROBE_TIMEOUT_MS = 500;
+var RENDERER_PROBE_EXPRESSION = `[1, ${BEACON_READ_EXPRESSION}]`;
+function rendererProbeSupported(driver) {
+  return typeof driver.probeRenderer === "function";
+}
+async function probeRendererActivity(driver, backend, targetId, now = Date.now()) {
+  if (typeof driver.probeRenderer !== "function")
+    return { responsive: false };
+  const { responsive, beaconTs } = await driver.probeRenderer(targetId, RENDERER_PROBE_TIMEOUT_MS).catch(() => ({ responsive: false, beaconTs: null }));
+  const ms = humanActiveMs(beaconTs, lastDispatchAt(backend, targetId), now);
+  return ms === null ? { responsive } : { responsive, humanActiveMs: ms };
+}
+
+class BeaconSessions {
+  close;
+  limit;
+  live = new Map;
+  constructor(close, limit = 32) {
+    this.close = close;
+    this.limit = limit;
+  }
+  get(key) {
+    return this.live.get(key);
+  }
+  set(key, value) {
+    const previous = this.live.get(key);
+    if (previous !== undefined) {
+      this.live.delete(key);
+      this.safeClose(previous);
+    }
+    this.live.set(key, value);
+    while (this.live.size > this.limit) {
+      const oldest = this.live.keys().next();
+      if (oldest.done)
+        break;
+      this.drop(oldest.value);
+    }
+  }
+  drop(key) {
+    const value = this.live.get(key);
+    if (value === undefined)
+      return;
+    this.live.delete(key);
+    this.safeClose(value);
+  }
+  clear() {
+    for (const key of [...this.live.keys()])
+      this.drop(key);
+  }
+  get size() {
+    return this.live.size;
+  }
+  safeClose(value) {
+    try {
+      this.close(value);
+    } catch {}
+  }
+}
+
 // src/tools/snapshot.ts
 var INTERACTIVE_ROLES = new Set([
   "button",
@@ -709,11 +844,22 @@ var REQUIRED_CAPABILITIES = {
   stop_screen_recording: ["capture.screencast"],
   mock_request: ["network.intercept"],
   list_mocks: ["network.intercept"],
-  clear_mocks: ["network.intercept"]
+  clear_mocks: ["network.intercept"],
+  dispatch_mouse: ["input.raw"],
+  wait_for_download: ["browser.downloads"],
+  grant_permissions: ["browser.permissions"]
 };
 function isDriverError(e) {
   return e instanceof Error && typeof e.code === "string";
 }
+function interpolatePoints(from, to, steps) {
+  const out = [];
+  for (let i = 1;i < steps; i++) {
+    out.push({ x: from.x + (to.x - from.x) * i / steps, y: from.y + (to.y - from.y) * i / steps });
+  }
+  out.push({ x: to.x, y: to.y });
+  return out;
+}
 
 // src/cdp/driver.ts
 function driverError(code, message, data) {
@@ -769,12 +915,21 @@ async function centerOf(conn, objectId) {
 async function focusElement(conn, objectId) {
   await conn.send("Runtime.callFunctionOn", { objectId, functionDeclaration: "function(){this.focus&&this.focus();}", returnByValue: true });
 }
-async function setValueOnObject(conn, objectId, value) {
+var ARM_SCROLL_SETTLE_WATCH = "(function(){window.__cdpScrollSettle=new Promise((resolve)=>{let t;const done=()=>{window.removeEventListener('scroll',on,true);resolve(true);};" + "const on=()=>{clearTimeout(t);t=setTimeout(done,60);};window.addEventListener('scroll',on,true);t=setTimeout(done,60);setTimeout(done,500);});})()";
+async function armScrollSettleWatch(conn) {
+  await conn.send("Runtime.evaluate", { expression: ARM_SCROLL_SETTLE_WATCH, returnByValue: true });
+}
+async function awaitScrollSettle(conn) {
+  await conn.send("Runtime.evaluate", { expression: "window.__cdpScrollSettle", awaitPromise: true, returnByValue: true }).catch(() => {
+    return;
+  });
+}
+async function setValueOnObject(conn, objectId, value, sendInput2) {
   await focusElement(conn, objectId);
   const fn = "function(){if('value'in this){this.value='';this.dispatchEvent(new Event('input',{bubbles:true}));}else if(this.isContentEditable){this.textContent='';}}";
   await conn.send("Runtime.callFunctionOn", { objectId, functionDeclaration: fn, returnByValue: true });
   if (value.length)
-    await conn.send("Input.insertText", { text: value });
+    await sendInput2("Input.insertText", { text: value });
 }
 var NAMED_KEYS = {
   enter: { key: "Enter", code: "Enter", keyCode: 13, text: "\r" },
@@ -799,6 +954,18 @@ var NAMED_KEYS = {
   pagedown: { key: "PageDown", code: "PageDown", keyCode: 34 }
 };
 var MODIFIER_BITS = { alt: 1, control: 2, ctrl: 2, meta: 4, cmd: 4, command: 4, shift: 8 };
+var CLICK_MODIFIER_BITS = { Alt: 1, Control: 2, Meta: 4, Shift: 8 };
+function inputModifierBits(mods) {
+  let bits = 0;
+  for (const m of mods ?? []) {
+    const bit = CLICK_MODIFIER_BITS[m];
+    if (bit === undefined)
+      throw driverError("page-error", `unknown modifier '${m}' (use Alt, Control, Meta, or Shift)`);
+    bits |= bit;
+  }
+  return bits;
+}
+var HTML5_DRAG_INTERCEPT_TIMEOUT_MS = 5000;
 function resolveKey(key) {
   const named = NAMED_KEYS[key.toLowerCase()];
   if (named)
@@ -963,7 +1130,11 @@ var CDP_CAPABILITIES = new Set([
   "input.insertTextAtomic",
   "locate.text",
   "locate.xpath",
-  "capture.screencast"
+  "capture.screencast",
+  "input.raw",
+  "input.html5Drag",
+  "browser.downloads",
+  "browser.permissions"
 ]);
 
 class CdpPageDriver {
@@ -983,6 +1154,9 @@ class CdpPageDriver {
     this.enabledDomains.add(name);
     await this.conn.send(`${name}.enable`);
   }
+  async dispatchInput(method, params = {}) {
+    return sendInput(this.conn, "chrome", this.info.id, method, params);
+  }
   async ensureDomainSoft(name) {
     if (this.enabledDomains.has(name))
       return;
@@ -991,11 +1165,22 @@ class CdpPageDriver {
       return;
     });
   }
+  async historyEntry(direction) {
+    const h = await this.conn.send("Page.getNavigationHistory");
+    const entries = h.entries ?? [];
+    const entry = entries[h.currentIndex + (direction === "back" ? -1 : 1)];
+    if (!entry) {
+      throw driverError("page-error", `navigate: no history entry to go ${direction} to (at entry ${h.currentIndex + 1} of ${entries.length})`);
+    }
+    return entry;
+  }
   async navigate(opts) {
     await this.ensureDomain("Page");
     const reload = opts.reload === true;
-    if (!reload && !opts.url)
+    const history = opts.history;
+    if (!reload && !history && !opts.url)
       throw driverError("page-error", "navigate: 'url' is required unless reload:true");
+    const entry = history ? await this.historyEntry(history) : undefined;
     const waitUntil = opts.waitUntil ?? "load";
     const milestoneMethod = waitUntil === "load" ? "Page.loadEventFired" : "Page.domContentEventFired";
     const milestone = this.conn.waitFor(milestoneMethod, undefined, opts.timeoutMs).then(() => waitUntil).catch(() => {
@@ -1013,6 +1198,10 @@ class CdpPageDriver {
       contextId = tree?.frameTree?.frame?.id ?? "";
       url = tree?.frameTree?.frame?.url ?? opts.url ?? "";
       reloaded = true;
+    } else if (entry) {
+      await this.conn.send("Page.navigateToHistoryEntry", { entryId: entry.id }, opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {});
+      contextId = "";
+      url = entry.url;
     } else {
       const nav = await this.conn.send("Page.navigate", { url: opts.url }, opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {});
       if (nav.errorText)
@@ -1021,7 +1210,20 @@ class CdpPageDriver {
       url = opts.url;
     }
     const settled = await Promise.race([milestone, stopped]);
-    return { url, contextId, ...reloaded ? { reloaded } : {}, waitedFor: settled ?? "timeout" };
+    if (entry) {
+      const tree = await this.conn.send("Page.getFrameTree").catch(() => {
+        return;
+      });
+      contextId = tree?.frameTree?.frame?.id ?? contextId;
+      url = tree?.frameTree?.frame?.url ?? url;
+    }
+    return {
+      url,
+      contextId,
+      ...reloaded ? { reloaded } : {},
+      ...history ? { traversed: history } : {},
+      waitedFor: settled ?? "timeout"
+    };
   }
   async waitForText(text, timeoutMs = 15000, pollMs = 250) {
     await this.ensureDomain("Runtime");
@@ -1101,36 +1303,96 @@ class CdpPageDriver {
   async hover(loc) {
     const { objectId } = await resolveElementLocator(this.conn, loc);
     const { x, y } = await centerOf(this.conn, objectId);
-    await this.conn.send("Input.dispatchMouseEvent", { type: "mouseMoved", x, y });
+    await this.dispatchInput("Input.dispatchMouseEvent", { type: "mouseMoved", x, y });
     return { x, y };
   }
   async click(loc, opts) {
     const button = opts?.button ?? "left";
     const clickCount = opts?.clickCount ?? 1;
+    const modifiers = inputModifierBits(opts?.modifiers);
     const { x, y } = await this.hover(loc);
-    await this.conn.send("Input.dispatchMouseEvent", { type: "mousePressed", x, y, button, clickCount });
-    await this.conn.send("Input.dispatchMouseEvent", { type: "mouseReleased", x, y, button, clickCount });
+    await this.dispatchInput("Input.dispatchMouseEvent", { type: "mousePressed", x, y, button, clickCount, modifiers });
+    await this.dispatchInput("Input.dispatchMouseEvent", { type: "mouseReleased", x, y, button, clickCount, modifiers });
+    return { x, y };
+  }
+  async scroll(anchor, opts) {
+    await this.ensureDomain("Runtime");
+    const { x, y } = await this.resolveScrollPoint(anchor);
+    await armScrollSettleWatch(this.conn);
+    await this.dispatchInput("Input.dispatchMouseEvent", { type: "mouseWheel", x, y, deltaX: opts.deltaX ?? 0, deltaY: opts.deltaY ?? 0 });
+    await awaitScrollSettle(this.conn);
     return { x, y };
   }
-  async drag(from, to) {
+  async resolveScrollPoint(anchor) {
+    if (anchor === undefined) {
+      await this.ensureDomain("Runtime");
+      const { result, exceptionDetails } = await this.conn.send("Runtime.evaluate", { expression: "({x: window.innerWidth / 2, y: window.innerHeight / 2})", returnByValue: true });
+      if (exceptionDetails || !result.value)
+        throw driverError("page-error", `could not measure viewport for scroll center: ${exceptionDetails?.text ?? "no value"}`);
+      return result.value;
+    }
+    if ("x" in anchor)
+      return anchor;
+    const { objectId } = await resolveElementLocator(this.conn, anchor);
+    return centerOf(this.conn, objectId);
+  }
+  async drag(from, to, opts) {
     const fromPt = await this.hover(from);
-    const { objectId: dstId } = await resolveElementLocator(this.conn, to);
-    const toPt = await centerOf(this.conn, dstId);
-    await this.conn.send("Input.dispatchMouseEvent", { type: "mousePressed", x: fromPt.x, y: fromPt.y, button: "left", clickCount: 1 });
-    await this.conn.send("Input.dispatchMouseEvent", { type: "mouseMoved", x: (fromPt.x + toPt.x) / 2, y: (fromPt.y + toPt.y) / 2, button: "left" });
-    await this.conn.send("Input.dispatchMouseEvent", { type: "mouseMoved", x: toPt.x, y: toPt.y, button: "left" });
-    await this.conn.send("Input.dispatchMouseEvent", { type: "mouseReleased", x: toPt.x, y: toPt.y, button: "left", clickCount: 1 });
+    const toPt = await this.resolveDragDestination(to, fromPt);
+    const steps = Math.max(1, Math.trunc(opts?.steps ?? 2));
+    if ((opts?.mode ?? "mouse") === "html5") {
+      await this.html5Drag(fromPt, toPt, steps);
+      return { from: fromPt, to: toPt };
+    }
+    await this.dispatchInput("Input.dispatchMouseEvent", { type: "mousePressed", x: fromPt.x, y: fromPt.y, button: "left", clickCount: 1 });
+    for (const pt of interpolatePoints(fromPt, toPt, steps)) {
+      await this.dispatchInput("Input.dispatchMouseEvent", { type: "mouseMoved", x: pt.x, y: pt.y, button: "left" });
+    }
+    await this.dispatchInput("Input.dispatchMouseEvent", { type: "mouseReleased", x: toPt.x, y: toPt.y, button: "left", clickCount: 1 });
     return { from: fromPt, to: toPt };
   }
+  async resolveDragDestination(to, fromPt) {
+    if ("dx" in to)
+      return { x: fromPt.x + to.dx, y: fromPt.y + to.dy };
+    if ("x" in to)
+      return to;
+    const { objectId } = await resolveElementLocator(this.conn, to);
+    return centerOf(this.conn, objectId);
+  }
+  async html5Drag(fromPt, toPt, steps) {
+    await this.dispatchInput("Input.setInterceptDrags", { enabled: true });
+    try {
+      const intercepted = this.conn.waitFor("Input.dragIntercepted", undefined, HTML5_DRAG_INTERCEPT_TIMEOUT_MS).catch(() => {
+        return;
+      });
+      await this.dispatchInput("Input.dispatchMouseEvent", { type: "mousePressed", x: fromPt.x, y: fromPt.y, button: "left", clickCount: 1 });
+      for (const pt of interpolatePoints(fromPt, toPt, steps)) {
+        await this.dispatchInput("Input.dispatchMouseEvent", { type: "mouseMoved", x: pt.x, y: pt.y, button: "left" });
+      }
+      const event = await intercepted;
+      if (!event?.data) {
+        throw driverError("page-error", `drag mode:"html5": the page never started a drag (no Input.dragIntercepted within ${HTML5_DRAG_INTERCEPT_TIMEOUT_MS}ms). ` + 'The source element is probably not draggable — HTML5 drag-and-drop needs draggable="true" (or a native draggable element) ' + 'plus a dragstart handler. Use the default mode:"mouse" for widgets built on raw pointer events.');
+      }
+      const data = event.data;
+      for (const type of ["dragEnter", "dragOver", "drop"]) {
+        await this.dispatchInput("Input.dispatchDragEvent", { type, x: toPt.x, y: toPt.y, data });
+      }
+      await this.dispatchInput("Input.dispatchMouseEvent", { type: "mouseReleased", x: toPt.x, y: toPt.y, button: "left", clickCount: 1 });
+    } finally {
+      await this.dispatchInput("Input.setInterceptDrags", { enabled: false }).catch(() => {
+        return;
+      });
+    }
+  }
   async setValue(loc, value) {
     const { objectId } = await resolveElementLocator(this.conn, loc);
-    await setValueOnObject(this.conn, objectId, value);
+    await setValueOnObject(this.conn, objectId, value, (method, params) => this.dispatchInput(method, params));
   }
   async typeText(loc, text) {
     const { objectId } = await resolveElementLocator(this.conn, loc);
     await focusElement(this.conn, objectId);
     if (text.length)
-      await this.conn.send("Input.insertText", { text });
+      await this.dispatchInput("Input.insertText", { text });
   }
   async pressKey(press) {
     const spec = resolveKey(press.key);
@@ -1145,8 +1407,8 @@ class CdpPageDriver {
     const down = { type: "keyDown", key: spec.key, code: spec.code, windowsVirtualKeyCode: spec.keyCode, nativeVirtualKeyCode: spec.keyCode, modifiers: modBits };
     if (spec.text && !suppressText)
       down.text = spec.text;
-    await this.conn.send("Input.dispatchKeyEvent", down);
-    await this.conn.send("Input.dispatchKeyEvent", { type: "keyUp", key: spec.key, code: spec.code, windowsVirtualKeyCode: spec.keyCode, nativeVirtualKeyCode: spec.keyCode, modifiers: modBits });
+    await this.dispatchInput("Input.dispatchKeyEvent", down);
+    await this.dispatchInput("Input.dispatchKeyEvent", { type: "keyUp", key: spec.key, code: spec.code, windowsVirtualKeyCode: spec.keyCode, nativeVirtualKeyCode: spec.keyCode, modifiers: modBits });
   }
   async setFiles(loc, files) {
     const { objectId } = await resolveElementLocator(this.conn, loc);
@@ -1362,6 +1624,36 @@ class CdpPageDriver {
     this.conn.close();
   }
 }
+var beaconSessions = new BeaconSessions((conn) => conn.close());
+async function targetWsUrl(targetId) {
+  const hit = (await listTargets()).find((t) => t.id === targetId);
+  return hit?.webSocketDebuggerUrl;
+}
+async function readBeaconOver(conn) {
+  try {
+    const res = await conn.send("Runtime.evaluate", {
+      expression: BEACON_READ_EXPRESSION,
+      returnByValue: true
+    });
+    const value = res.result?.value;
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+  } catch {
+    return;
+  }
+}
+async function probeOver(conn, timeoutMs) {
+  try {
+    const res = await conn.send("Runtime.evaluate", { expression: RENDERER_PROBE_EXPRESSION, returnByValue: true }, { timeoutMs });
+    const value = res.result?.value;
+    if (Array.isArray(value) && value[0] === 1) {
+      const ts = value[1];
+      return { responsive: true, beaconTs: typeof ts === "number" && Number.isFinite(ts) ? ts : null };
+    }
+    return { responsive: false, beaconTs: null };
+  } catch {
+    return { responsive: false, beaconTs: null };
+  }
+}
 async function withBrowserConn(fn) {
   const conn = await openBrowser();
   try {
@@ -1400,6 +1692,8 @@ class CdpBrowserDriver {
   async closePage(id) {
     return withBrowserConn(async (conn) => {
       const res = await conn.send("Target.closeTarget", { targetId: id });
+      if (res.success !== false)
+        beaconSessions.drop(id);
       return { success: res.success ?? true };
     });
   }
@@ -1412,7 +1706,83 @@ class CdpBrowserDriver {
     const { conn, target } = await openPage(selector).catch(noSuchTarget);
     return new CdpPageDriver(conn, target, this);
   }
-  async dispose() {}
+  async installActivityBeacon(targetId) {
+    const held = beaconSessions.get(targetId);
+    if (held) {
+      const rearmed = await held.send("Runtime.evaluate", { expression: BEACON_SOURCE, returnByValue: true }).then(() => true).catch(() => false);
+      if (rearmed)
+        return true;
+      beaconSessions.drop(targetId);
+    }
+    const wsUrl = await targetWsUrl(targetId).catch(() => {
+      return;
+    });
+    if (!wsUrl)
+      return false;
+    const conn = await new CdpConnection(wsUrl).connect().catch(() => {
+      return;
+    });
+    if (!conn)
+      return false;
+    try {
+      await conn.send("Page.enable");
+      await conn.send("Page.addScriptToEvaluateOnNewDocument", { source: BEACON_SOURCE });
+      await conn.send("Runtime.evaluate", { expression: BEACON_SOURCE, returnByValue: true });
+    } catch {
+      conn.close();
+      return false;
+    }
+    beaconSessions.set(targetId, conn);
+    return true;
+  }
+  async readActivityBeacon(targetId) {
+    const held = beaconSessions.get(targetId);
+    if (held) {
+      const value = await readBeaconOver(held);
+      if (value !== undefined)
+        return value;
+      beaconSessions.drop(targetId);
+    }
+    const wsUrl = await targetWsUrl(targetId).catch(() => {
+      return;
+    });
+    if (!wsUrl)
+      return null;
+    const conn = await new CdpConnection(wsUrl).connect().catch(() => {
+      return;
+    });
+    if (!conn)
+      return null;
+    try {
+      return await readBeaconOver(conn) ?? null;
+    } finally {
+      conn.close();
+    }
+  }
+  async probeRenderer(targetId, timeoutMs = RENDERER_PROBE_TIMEOUT_MS) {
+    const held = beaconSessions.get(targetId);
+    if (held)
+      return probeOver(held, timeoutMs);
+    const wsUrl = await targetWsUrl(targetId).catch(() => {
+      return;
+    });
+    if (!wsUrl)
+      return { responsive: false, beaconTs: null };
+    const conn = new CdpConnection(wsUrl, { timeoutMs });
+    try {
+      await conn.connect();
+    } catch {
+      return { responsive: false, beaconTs: null };
+    }
+    try {
+      return await probeOver(conn, timeoutMs);
+    } finally {
+      conn.close();
+    }
+  }
+  async dispose() {
+    beaconSessions.clear();
+  }
 }
 function createCdpDriver() {
   return new CdpBrowserDriver;
@@ -1534,6 +1904,8 @@ function staleAgentTabs(input) {
       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);
@@ -1543,13 +1915,19 @@ function staleAgentTabs(input) {
   }
   return out;
 }
+var DEFAULT_REAP_GRACE_MS = 2700000;
+function reapGraceMs() {
+  const raw = Number(process.env.CDP_REAP_GRACE_MS);
+  return Number.isFinite(raw) && raw >= 0 ? raw : DEFAULT_REAP_GRACE_MS;
+}
 async function reapStaleAgentTabs(driver, backend) {
+  const now = Date.now();
   const livePageIds = (await driver.listPages()).map((p) => p.id);
   const [origins, leases] = await Promise.all([
     originIndex(backend, undefined),
-    listLeases({ liveIds: livePageIds, liveBackend: backend }).catch(() => [])
+    listLeases({ now, liveIds: livePageIds, liveBackend: backend }).catch(() => [])
   ]);
-  const candidates = staleAgentTabs({ backend, livePageIds, origins, leases });
+  const candidates = staleAgentTabs({ backend, livePageIds, origins, leases, now, reapGraceMs: reapGraceMs() });
   const closed = [];
   for (const c of candidates) {
     const res = await driver.closePage(c.targetId).catch(() => ({ success: false }));
@@ -1641,18 +2019,29 @@ async function reapSet(driver, pages, all) {
   }
 }
 async function listPages(driver, args = {}) {
-  const reaped = requireLease() ? await reapStaleAgentTabs(driver, backendOf(driver)) : [];
+  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));
-  const ledger = await originIndex(backendOf(driver), await reapSet(driver, pages, args.all));
-  const annotated = pages.map((p) => {
+  const ledger = await originIndex(backend, await reapSet(driver, pages, args.all));
+  const now = Date.now();
+  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]));
+  const doProbe = args.probe === true && rendererProbeSupported(driver);
+  const annotated = await Promise.all(pages.map(async (p) => {
     const rec = ledger.get(p.id);
-    if (!rec)
-      return { ...p, origin: "unknown" };
-    if (rec.unreadable !== undefined)
-      return { ...p, origin: "unknown", originUnreadable: rec.unreadable };
-    return { ...p, origin: "agent", label: rec.label, createdAt: rec.createdAt };
-  });
+    const base = !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 };
+    }
+    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;
+  }));
   return { pages: annotated, count: annotated.length, ...reaped.length ? { reaped } : {} };
 }
 async function newPage(driver, args = {}) {
@@ -1666,6 +2055,7 @@ async function newPage(driver, args = {}) {
     ttlMs: typeof args.ttlMs === "number" && args.ttlMs > 0 ? args.ttlMs : leaseTtlMs(),
     auto: !explicit
   });
+  await installBeacon(driver, p.id);
   return { targetId: p.id, url: p.url, lease: token, label: record.label, expiresAt: record.lastUsedAt + record.ttlMs };
 }
 async function closePage(driver, args) {
@@ -1697,17 +2087,36 @@ function toLegacyWaitedFor(w) {
     return "navigate-only";
   return w;
 }
-async function navigatePage(driver, args) {
+function resolveNavigateMode(args) {
   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 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 };
+}
+async function navigatePage(driver, args) {
+  const mode = resolveNavigateMode(args);
   return withPage2(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)
     };
   });
@@ -1853,22 +2262,113 @@ async function takeSnapshot(driver, args = {}) {
 }
 async function click(driver, args) {
   return withPage2(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 };
   });
 }
+function resolveScrollAnchor(args) {
+  const hasUid = args.uid !== undefined && args.uid !== null && args.uid !== "";
+  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, y: args.y };
+  return;
+}
+function resolveScrollDelta(args) {
+  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 };
+}
+async function scroll(driver, args) {
+  const anchor = resolveScrollAnchor(args);
+  const { deltaX, deltaY } = resolveScrollDelta(args);
+  return withPage2(driver, args.target, async (page) => {
+    const { x, y } = await page.scroll(anchor, { deltaX, deltaY });
+    return { x, y, deltaX, deltaY, target: target3(page.info) };
+  });
+}
 async function hover(driver, args) {
   return withPage2(driver, args.target, async (page) => {
     const { x, y } = await page.hover(locatorOf(args));
     return { hovered: true, x, y };
   });
 }
+function resolveDragTo(to) {
+  const hasUid = to.uid !== undefined && to.uid !== null && to.uid !== "";
+  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, y: to.y };
+  }
+  return locatorOf({ uid: to.uid, selector: to.selector });
+}
+function resolveDragDestination(args) {
+  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;
+    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);
+}
+var MAX_DRAG_STEPS = 500;
+function resolveDragSteps(steps) {
+  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;
+}
+function resolveDragMode(mode, capabilities) {
+  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";
+}
 async function drag(driver, args) {
-  if (!args.from || !args.to)
-    throw new SharedToolError("drag requires { from } and { to }");
+  if (!args.from)
+    throw new SharedToolError("drag requires { from }");
+  const destination = resolveDragDestination(args);
+  const steps = resolveDragSteps(args.steps);
+  const mode = resolveDragMode(args.mode, driver.capabilities);
   return withPage2(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 };
   });
 }
 async function fill(driver, args) {
@@ -1989,6 +2489,7 @@ var SHARED_TOOLS = {
   click,
   hover,
   drag,
+  scroll,
   fill,
   fill_form: fillForm,
   type_text: typeText,
@@ -2038,12 +2539,15 @@ async function claimPage(driver, args = {}) {
     url = page.url;
     opened = true;
   }
+  const humanMs = opened ? null : await readHumanActiveMs(driver, backend, targetId);
   const liveIds = [...pages.map((p) => p.id), targetId];
   const { record, token } = await claimLease(backend, targetId, {
     label,
     ttlMs: typeof args.ttlMs === "number" && args.ttlMs > 0 ? args.ttlMs : leaseTtlMs(),
     liveIds
   });
+  await installBeacon(driver, targetId);
+  const contention = contentionWarning(humanMs, { takeover: !opened });
   return {
     lease: token,
     targetId,
@@ -2051,7 +2555,9 @@ async function claimPage(driver, args = {}) {
     label: record.label,
     ttlMs: record.ttlMs,
     expiresAt: record.lastUsedAt + record.ttlMs,
-    opened
+    opened,
+    ...beaconSupported(driver) ? { humanActiveMs: humanMs } : {},
+    ...contention !== undefined ? { contention } : {}
   };
 }
 async function releasePage(driver, args = {}) {
@@ -2086,9 +2592,22 @@ async function listLeasesTool(driver, _args = {}) {
   const backend = backendOf2(driver);
   const reaped = requireLease() ? await reapStaleAgentTabs(driver, backend) : [];
   const reapedIds = new Set(reaped.map((r) => r.targetId));
-  const liveIds = (await driver.listPages()).map((p) => p.id);
+  const livePages = await driver.listPages();
+  const liveIds = livePages.map((p) => p.id);
   const all = await listLeases({ liveIds, liveBackend: backend });
-  const leases = all.filter((l) => !(l.backend === backend && reapedIds.has(l.targetId)));
+  const kept = all.filter((l) => !(l.backend === backend && reapedIds.has(l.targetId)));
+  const liveSet = new Set(liveIds);
+  const now = Date.now();
+  const leases = [];
+  for (const row of kept) {
+    const computed = row.unreadable !== undefined ? row : { ...row, idleMs: now - row.lastUsedAt, expiresAt: row.lastUsedAt + row.ttlMs };
+    if (row.backend !== backend || row.unreadable !== undefined || !liveSet.has(row.targetId)) {
+      leases.push(computed);
+      continue;
+    }
+    const humanMs = await readHumanActiveMs(driver, backend, row.targetId, now).catch(() => null);
+    leases.push(humanMs === null ? computed : { ...computed, humanActiveMs: humanMs });
+  }
   return { leases, count: leases.length, ...reaped.length ? { reaped } : {} };
 }
 var LEASE_TOOLS = {
@@ -3244,6 +3763,273 @@ function truncate(s, max = 600) {
   return t.length > max ? `${t.slice(0, max)}…` : t;
 }
 
+// src/tools/dispatch-mouse.ts
+var CLICK_MODIFIER_BITS2 = { Alt: 1, Control: 2, Meta: 4, Shift: 8 };
+var BUTTONS = new Set(["left", "right", "middle"]);
+var CDP_EVENT_TYPE = {
+  move: "mouseMoved",
+  down: "mousePressed",
+  up: "mouseReleased"
+};
+function modifierBits(mods) {
+  let bits = 0;
+  for (const m of mods ?? []) {
+    const bit = CLICK_MODIFIER_BITS2[m];
+    if (bit === undefined)
+      throw new Error(`dispatch_mouse: unknown modifier '${m}' (use Alt, Control, Meta, or Shift)`);
+    bits |= bit;
+  }
+  return bits;
+}
+function validateDispatchMouseArgs(args) {
+  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)`);
+}
+async function dispatchMouse(args) {
+  validateDispatchMouseArgs(args);
+  const button = args.button ?? "left";
+  const modifiers = modifierBits(args.modifiers);
+  return withPage(args.target, async (conn, target) => {
+    const params = { type: CDP_EVENT_TYPE[args.action], x: args.x, y: args.y, button, modifiers };
+    if (args.action !== "move")
+      params.clickCount = args.clickCount ?? 1;
+    await sendInput(conn, "chrome", target.id, "Input.dispatchMouseEvent", params);
+    return { dispatched: args.action, x: args.x, y: args.y };
+  });
+}
+
+// src/tools/downloads.ts
+import { readdir as readdir3, rename, stat as stat4 } from "node:fs/promises";
+import { basename, extname, join as join8 } from "node:path";
+
+// src/tools/browser-session.ts
+import { mkdir as mkdir9 } from "node:fs/promises";
+import { join as join7 } from "node:path";
+var ARTIFACT_DIR7 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+var DOWNLOADS_DIR = join7(ARTIFACT_DIR7, "downloads");
+var DOWNLOAD_BUFFER_LIMIT = 50;
+var session;
+function isDisconnect(e) {
+  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, guid) {
+  let r = s.downloads.find((d) => d.guid === guid);
+  if (!r) {
+    r = { guid, state: "inProgress", consumed: false };
+    s.downloads.push(r);
+    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;
+}
+function subscribe(s) {
+  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;
+      if (state === "completed") {
+        const waiter = s.waiters.shift();
+        if (waiter) {
+          r.consumed = true;
+          waiter(r);
+        }
+      }
+    }
+  });
+}
+async function getBrowserSession() {
+  if (session && !session.dead)
+    return session;
+  const previousPath = session?.armedPath;
+  const conn = await openBrowser();
+  const s = { conn, downloads: [], waiters: [], dead: false };
+  subscribe(s);
+  session = s;
+  if (previousPath)
+    await armDownloadsAt(previousPath);
+  return s;
+}
+async function browserSend(method, params = {}) {
+  const s = await getBrowserSession();
+  try {
+    return await s.conn.send(method, params);
+  } catch (e) {
+    if (isDisconnect(e)) {
+      s.dead = true;
+      const fresh = await getBrowserSession();
+      return await fresh.conn.send(method, params);
+    }
+    throw e;
+  }
+}
+async function armDownloadsAt(path) {
+  await mkdir9(path, { recursive: true });
+  const s = await getBrowserSession();
+  await s.conn.send("Browser.setDownloadBehavior", { behavior: "allowAndName", downloadPath: path, eventsEnabled: true });
+  s.armedPath = path;
+}
+async function armDownloads() {
+  const s = await getBrowserSession();
+  if (s.armedPath !== DOWNLOADS_DIR)
+    await armDownloadsAt(DOWNLOADS_DIR);
+  return { downloadPath: DOWNLOADS_DIR };
+}
+function pendingDownloads() {
+  return (session?.downloads ?? []).filter((d) => d.state === "completed" && !d.consumed);
+}
+async function nextCompletedDownload(timeoutMs) {
+  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((resolve, reject) => {
+    const waiter = (r) => {
+      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);
+  });
+}
+async function disposeBrowserSession() {
+  const s = session;
+  session = undefined;
+  if (!s)
+    return;
+  s.dead = true;
+  try {
+    s.conn.close();
+  } catch {}
+}
+
+// src/tools/downloads.ts
+function safeFilename(suggested) {
+  const raw = (suggested ?? "").replace(/[\u0000-\u001f]/g, "");
+  const name = basename(raw.split("\\").pop() ?? "").trim();
+  if (!name || name === "." || name === "..")
+    return "download";
+  return name;
+}
+function nextFreeName(name, taken) {
+  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;
+  }
+}
+function validateWaitForDownloadArgs(args) {
+  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)})`);
+  }
+}
+async function waitForDownload(args = {}) {
+  validateWaitForDownloadArgs(args);
+  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 ?? 30000);
+  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);
+  const taken = new Set(await readdir3(DOWNLOADS_DIR).catch(() => []));
+  taken.delete(basename(rec.filePath));
+  const finalName = nextFreeName(suggestedFilename, taken);
+  const path = join8(DOWNLOADS_DIR, finalName);
+  await rename(rec.filePath, path);
+  const bytes = (await stat4(path)).size;
+  return { path, suggestedFilename, bytes, ...rec.url ? { url: rec.url } : {}, target };
+}
+
+// src/tools/permissions.ts
+function originOf(url) {
+  try {
+    const o = new URL(url).origin;
+    return o && o !== "null" ? o : undefined;
+  } catch {
+    return;
+  }
+}
+function validateGrantPermissionsArgs(args) {
+  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) {
+    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)})`);
+  }
+  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)})`);
+    }
+  }
+}
+async function grantPermissions(args = {}) {
+  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"`);
+  }
+  await browserSend("Browser.grantPermissions", { origin, permissions });
+  return { granted: [...permissions], origin, ...reset ? { reset: true } : {}, target };
+}
+
 // src/index.ts
 var cdpDriver = createCdpDriver();
 function onCdp(fn) {
@@ -3264,6 +4050,7 @@ var TOOLS = {
   click: onCdp(SHARED_TOOLS.click),
   hover: onCdp(SHARED_TOOLS.hover),
   drag: onCdp(SHARED_TOOLS.drag),
+  scroll: onCdp(SHARED_TOOLS.scroll),
   fill: onCdp(SHARED_TOOLS.fill),
   fill_form: onCdp(SHARED_TOOLS.fill_form),
   type_text: onCdp(SHARED_TOOLS.type_text),
@@ -3288,6 +4075,9 @@ var TOOLS = {
   mock_request: mockRequest,
   list_mocks: listMocks,
   clear_mocks: clearMocks,
+  dispatch_mouse: dispatchMouse,
+  wait_for_download: waitForDownload,
+  grant_permissions: grantPermissions,
   claim_page: onCdp(LEASE_TOOLS.claim_page),
   release_page: onCdp(LEASE_TOOLS.release_page),
   list_leases: onCdp(LEASE_TOOLS.list_leases)
@@ -3303,7 +4093,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 var MANIFEST = [
   {
     name: "list_pages",
-    description: "Enumerate browser page targets via the CDP browser endpoint (GET /json/list). By default returns only page-type tabs; set 'all' to also include workers and background pages. Each entry carries the targetId used as a target selector elsewhere, plus an 'origin' field recording where the tab came from: 'agent' means this toolkit created it (the entry then also carries the creating 'label' and 'createdAt'), and this stays true after the creating agent releases its lease or dies, which is what makes a stray agent tab findable later. 'unknown' means there is no creation record. It never says 'human': the toolkit cannot prove a person opened a tab, so 'unknown' is the honest word for a tab it did not create, one opened before the toolkit ran, or one whose record could not be written. A tab whose record exists but could not be read reports origin 'unknown' plus 'originUnreadable', so a broken record is never mistaken for no record. Under CDP_REQUIRE_LEASE this call also reaps: a tab this toolkit created whose lease is stale because the owning process died or the TTL elapsed is closed, and the closed tabs are reported in an additive 'reaped' array ({targetId,label,reason}) that is present only when something was actually closed. A tab with no lease is never reaped, so tabs opened by a caller that never uses leases are untouched.",
+    description: "Enumerate browser page targets via the CDP browser endpoint (GET /json/list). By default returns only page-type tabs; set 'all' to also include workers and background pages. Each entry carries the targetId used as a target selector elsewhere, plus an 'origin' field recording where the tab came from: 'agent' means this toolkit created it (the entry then also carries the creating 'label' and 'createdAt'), and this stays true after the creating agent releases its lease or dies, which is what makes a stray agent tab findable later. 'unknown' means there is no creation record. It never says 'human': the toolkit cannot prove a person opened a tab, so 'unknown' is the honest word for a tab it did not create, one opened before the toolkit ran, or one whose record could not be written. A tab whose record exists but could not be read reports origin 'unknown' plus 'originUnreadable', so a broken record is never mistaken for no record. Under CDP_REQUIRE_LEASE this call also reaps abandoned agent tabs, but reap-CLOSE and lease-RECLAIMABLE (list_leases' 'stale') now fire at different times: a lease reads reclaimable the moment its TTL elapses, cheap and reversible since another agent may simply take it, while this call only CLOSES the tab, destructively, after an ADDITIONAL grace period past that TTL (CDP_REAP_GRACE_MS, default 2700000ms/45 minutes, so 60 minutes total after last use) — a tab an agent is mid-build between calls on is not destroyed out from under it. A dead-pid lease is reaped immediately regardless of grace: that process is never coming back. Closed tabs are reported in an additive 'reaped' array ({targetId,label,reason}) present only when something was actually closed; a tab with no lease is never reaped. Every entry under an active, readable lease of this backend also carries 'lease': {label, pid, idleMs, expiresAt, stale} — idleMs and expiresAt are computed fresh on every call (now-lastUsedAt and lastUsedAt+ttlMs), never read off disk, and this is unconditional on 'probe'. Set 'probe' to true to also ping each page-type target's renderer: one bounded (500ms) check per target, never more, so a single wedged tab cannot stall the listing beyond its own budget. This adds 'responsive' (true iff the ping answered in time; false on a timeout, a page-side exception, or an unreachable target — never an error for the whole call) and, where that same round trip found human-attributed input, 'humanActiveMs' (see claim_page and list_leases for what that field means and cannot prove). 'responsive' and 'humanActiveMs' are both ABSENT — never false/null — when 'probe' is not set, and 'responsive' is likewise absent on a backend that cannot answer this ping at all.",
     inputSchema: {
       type: "object",
       properties: {
@@ -3314,6 +4104,10 @@ var MANIFEST = [
         all: {
           type: "boolean",
           description: "Include non-page targets (service/shared workers, background pages) when true; otherwise only page-type tabs are listed."
+        },
+        probe: {
+          type: "boolean",
+          description: "Ping each page-type target's renderer before returning: one bounded (500ms) Runtime.evaluate per target, never more. Adds 'responsive' to every page-type entry and, where the same round trip finds human-attributed input, 'humanActiveMs'. A wedged or unreachable tab reports responsive:false rather than failing the call. Defaults to false, which is byte-identical to the pre-1.8.0 shape."
         }
       },
       required: [],
@@ -3395,7 +4189,7 @@ var MANIFEST = [
   },
   {
     name: "navigate_page",
-    description: "Navigate a target page to a URL (Page.navigate) OR reload it (reload:true) over raw CDP, then wait for the load milestone with a bounded timeout so a wedged renderer can't hang. Returns {url,frameId,waitedFor} (plus reloaded:true on a reload); waitUntil supports 'load'|'domcontentloaded' only (no 'networkidle'), and there is no auto-snapshot of the new page. Pass reload:true with ignoreCache:true for a hard reload that refetches every subresource (e.g. to pick up a freshly-deployed, non-content-hashed bundle the HTTP cache would serve stale).",
+    description: "Navigate a target page to a URL (Page.navigate), reload it (reload:true), OR go back/forward in its session history (history:'back'|'forward'), then wait for the load milestone with a bounded timeout so a wedged renderer can't hang. Exactly one of url / reload / history per call. Returns {url,frameId,waitedFor} (plus reloaded:true on a reload, traversed:'back'|'forward' on a history move); waitUntil supports 'load'|'domcontentloaded' only (no 'networkidle'), and there is no auto-snapshot of the new page. Pass reload:true with ignoreCache:true for a hard reload that refetches every subresource (e.g. to pick up a freshly-deployed, non-content-hashed bundle the HTTP cache would serve stale).",
     inputSchema: {
       type: "object",
       properties: {
@@ -3415,6 +4209,14 @@ var MANIFEST = [
           type: "boolean",
           description: "Reload the current page (Page.reload) instead of navigating to url. Default false."
         },
+        history: {
+          type: "string",
+          enum: [
+            "back",
+            "forward"
+          ],
+          description: "Traverse this tab's session history instead of loading a url: 'back' and 'forward' are the browser's Back and Forward buttons. Mutually exclusive with 'url' and 'reload' — passing two of the three is refused by name rather than resolved by precedence. Works on BOTH backends (Chrome: Page.getNavigationHistory + Page.navigateToHistoryEntry; Firefox: browsingContext.traverseHistory) and waits for the same load milestone as an ordinary navigation. Going back from the first entry, or forward from the last, is an ERROR naming the direction — never a silent success that navigated nowhere. The result carries traversed:'back'|'forward' alongside the resulting url."
+        },
         ignoreCache: {
           type: "boolean",
           description: "On reload, bypass the HTTP cache (hard reload) so subresources are refetched. Ignored unless reload:true. Default false."
@@ -3652,7 +4454,7 @@ var MANIFEST = [
   },
   {
     name: "click",
-    description: "Click an element via a synthetic mouse press/release at the element's scrolled-into-view bounding-rect center. Target the element with exactly one of 'uid' (a CDP backendDOMNodeId from take_snapshot) or 'selector' (a CSS selector).",
+    description: "Click an element via a synthetic mouse press/release at the element's scrolled-into-view bounding-rect center. Target the element with exactly one of 'uid' (a CDP backendDOMNodeId from take_snapshot) or 'selector' (a CSS selector). clickCount:3 triple-clicks (selects a paragraph/line in most editors). 'modifiers' holds Alt/Control/Meta/Shift for the press and release, like a real modifier-click; on the Firefox backend a non-empty 'modifiers' throws (not yet supported over BiDi), so a modifier click there needs --browser chrome.",
     inputSchema: {
       type: "object",
       properties: {
@@ -3683,7 +4485,20 @@ var MANIFEST = [
         },
         clickCount: {
           type: "number",
-          description: "Number of clicks: 1 = single (default), 2 = double-click."
+          description: "Number of clicks: 1 = single (default), 2 = double-click, 3 = triple-click."
+        },
+        modifiers: {
+          type: "array",
+          items: {
+            type: "string",
+            enum: [
+              "Alt",
+              "Control",
+              "Meta",
+              "Shift"
+            ]
+          },
+          description: "Modifier keys held for the click's press and release, e.g. ['Shift'] for a shift-click. Not supported on the Firefox backend: passing a non-empty array there throws."
         }
       },
       required: [],
@@ -3719,7 +4534,7 @@ var MANIFEST = [
   },
   {
     name: "drag",
-    description: "Drag from a source element to a destination element via synthetic mouse press/move/release (approximates HTML5 drag-and-drop; not guaranteed for every custom DnD library). 'from' and 'to' each take exactly one of uid (a CDP backendDOMNodeId from take_snapshot) or selector.",
+    description: `Drag from a source element to a destination. 'from' takes exactly one of uid (a CDP backendDOMNodeId from take_snapshot) or selector. The destination is exactly one of 'to' (an element via uid/selector, or an absolute viewport point via x+y) or 'by' ({dx,dy} offset from the source point — sliders, map panning, resize handles). mode:'mouse' (default) dispatches synthetic mouse press/move/release: right for widgets built on raw pointer events, and Chrome does turn it into a real drag, but WHICH drag events reach the page depends on where the interpolated pointer path happens to land — measured on Chrome 151, the default steps:2 delivers ZERO dragover events, so an HTML5 drop zone written the standard way (preventDefault inside dragover) refuses the drop entirely. mode:'html5' performs the drag deterministically instead: Chrome's drag interception hands back the DragData the page's own dragstart built, and the toolkit replays it as dragEnter/dragOver/drop exactly at the destination, so a draggable="true" / dataTransfer drop zone works regardless of the pointer path. mode:'html5' is CHROME-ONLY: it requires capability 'input.html5Drag' and is rejected with a clear error under the Firefox backend, where the tool itself remains available for mouse-mode drags. 'steps' (default 2) sets how many interpolated mouse-move events are dispatched between source and destination; raise it for DnD libraries with a movement threshold or per-frame sampling.`,
     inputSchema: {
       type: "object",
       properties: {
@@ -3748,7 +4563,7 @@ var MANIFEST = [
         },
         to: {
           type: "object",
-          description: "Destination element to drag to. Provide exactly one of uid or selector.",
+          description: "Where the drag ends: exactly one of uid, selector, or x+y. Mutually exclusive with 'by'; exactly one of to/by is required.",
           properties: {
             uid: {
               type: "number",
@@ -3757,18 +4572,222 @@ var MANIFEST = [
             selector: {
               type: "string",
               description: "CSS selector for the destination element (resolved via document.querySelector)."
+            },
+            x: {
+              type: "number",
+              description: "Absolute viewport x-coordinate to drop at. Must be given together with 'y'. Use this when there is no droppable element to name (a canvas, a slider track)."
+            },
+            y: {
+              type: "number",
+              description: "Absolute viewport y-coordinate to drop at. Must be given together with 'x'."
+            }
+          },
+          additionalProperties: false
+        },
+        by: {
+          type: "object",
+          description: "Drag by an offset from the source element's center instead of to a destination: at least one of dx/dy, the other defaults to 0. Mutually exclusive with 'to'; exactly one of to/by is required. Use for sliders (by:{dx:40}), map panning, and resize handles.",
+          properties: {
+            dx: {
+              type: "number",
+              description: "Horizontal offset in CSS pixels; positive drags RIGHT."
+            },
+            dy: {
+              type: "number",
+              description: "Vertical offset in CSS pixels; positive drags DOWN."
             }
           },
           additionalProperties: false
+        },
+        mode: {
+          type: "string",
+          enum: [
+            "mouse",
+            "html5"
+          ],
+          description: "'mouse' (default): synthetic mouse press/move/release, right for widgets built on raw pointer events. Chrome does turn this into a real HTML5 drag too, but WHICH drag events reach the page depends on the interpolated pointer path: at the default steps:2, an HTML5 drop zone written the standard way (preventDefault inside dragover) sees zero dragover events and refuses the drop. 'html5': real HTML5 drag-and-drop (dragstart/dragEnter/dragOver/drop with the page's own dataTransfer), deterministic regardless of pointer path. 'html5' is CHROME-ONLY and is rejected with a clear error under the Firefox backend."
+        },
+        steps: {
+          type: "number",
+          description: "Number of interpolated mouse-move events dispatched between the source and destination points, evenly spaced, the last landing exactly on the destination. Integer 1-500, default 2 (midpoint then destination). Raise it for DnD libraries with a movement threshold or per-frame sampling."
+        }
+      },
+      required: [
+        "from"
+      ],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "scroll",
+    description: "Dispatch a wheel/scroll event at an anchor point: provide at most one of 'uid', 'selector', or 'x'+'y'; omit all three to scroll at the viewport center. An element anchor ('uid' or 'selector') is scrolled into view first, the same as click/hover. At least one of 'deltaX'/'deltaY' is required; positive 'deltaY' scrolls DOWN and positive 'deltaX' scrolls RIGHT (wheel-event convention). Chrome dispatches Input.dispatchMouseEvent{type:'mouseWheel'}; Firefox dispatches WebDriver BiDi's 'wheel' input source. Returns the resolved anchor point ({x,y}) plus the delta actually dispatched.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+        },
+        uid: {
+          type: "number",
+          description: "CDP backendDOMNodeId of the element to scroll into view and anchor at, obtained from take_snapshot. Provide at most one of uid, selector, or x+y; omit all three to scroll at the viewport center."
+        },
+        selector: {
+          type: "string",
+          description: "CSS selector for the element to scroll into view and anchor at (resolved via document.querySelector). Provide at most one of uid, selector, or x+y; omit all three to scroll at the viewport center."
+        },
+        x: {
+          type: "number",
+          description: "Absolute viewport x-coordinate to anchor the scroll at. Must be given together with 'y'. Provide at most one of uid, selector, or x+y."
+        },
+        y: {
+          type: "number",
+          description: "Absolute viewport y-coordinate to anchor the scroll at. Must be given together with 'x'. Provide at most one of uid, selector, or x+y."
+        },
+        deltaX: {
+          type: "number",
+          description: "Horizontal scroll delta; positive scrolls RIGHT. At least one of deltaX/deltaY is required."
+        },
+        deltaY: {
+          type: "number",
+          description: "Vertical scroll delta; positive scrolls DOWN. At least one of deltaX/deltaY is required."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "dispatch_mouse",
+    description: "Dispatch exactly one raw mouse event ('move', 'down', or 'up') at absolute viewport coordinates: the toolkit's lowest-level input primitive. Compose move/down/move/up calls yourself to reach anything a physical mouse can do that click/drag's fixed sequences cannot — canvas drag-painting, marquee/rubber-band selection, a custom widget with its own hit-testing. Chrome-only (capability 'input.raw'): absent from tools/list under the Firefox backend, never present-and-throwing.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+        },
+        action: {
+          type: "string",
+          enum: [
+            "move",
+            "down",
+            "up"
+          ],
+          description: "Which raw event to dispatch: 'move' (mouseMoved), 'down' (mousePressed), or 'up' (mouseReleased)."
+        },
+        x: {
+          type: "number",
+          description: "Viewport x-coordinate. Required on every call: CDP has no notion of a 'current pointer position' to default from."
+        },
+        y: {
+          type: "number",
+          description: "Viewport y-coordinate. Required on every call."
+        },
+        button: {
+          type: "string",
+          enum: [
+            "left",
+            "right",
+            "middle"
+          ],
+          description: "Mouse button: 'left' (default), 'right', or 'middle'."
+        },
+        clickCount: {
+          type: "number",
+          description: "Click-run length for a 'down' or 'up' event (2 = the second half of a double-click, 3 = triple-click). Ignored for 'move'; defaults to 1."
+        },
+        modifiers: {
+          type: "array",
+          items: {
+            type: "string",
+            enum: [
+              "Alt",
+              "Control",
+              "Meta",
+              "Shift"
+            ]
+          },
+          description: "Modifier keys held for this one event, e.g. ['Shift']."
         }
       },
       required: [
-        "from",
-        "to"
+        "action",
+        "x",
+        "y"
       ],
       additionalProperties: false
     }
   },
+  {
+    name: "wait_for_download",
+    description: "Wait for a file download to finish and return it as a real file on disk: {path,suggestedFilename,bytes,url,target}. The file is written under the artifact dir's downloads/ folder and renamed from Chrome's internal guid to the page's own filename, collision-suffixed (report.csv, report-1.csv, ...). ORDERING RULE, and it is not optional: download capture must be ARMED BEFORE the click that starts the download — call wait_for_download{arm:true} first (it arms and returns immediately, reporting {armed:true,downloadPath,pending}), then click, then call wait_for_download to collect the finished file. This is Chrome's behavior, not a preference: the download-behavior override is per-connection state that Chrome REVERTS the moment the arming client disconnects, and an unarmed headless Chrome denies the download outright, so a download triggered before anything armed is lost with no file anywhere. SIDE EFFECT, browser-global: arming redirects EVERY download in this browser (all tabs, all origins) into the toolkit's downloads directory for as long as this server runs, and downloads no longer land in the user's normal Downloads folder. Because the arm lives on a connection this server process holds open, this is an MCP-server capability: under the one-shot CLI the connection dies with the process and nothing is captured. Chrome-only (capability 'browser.downloads'): absent from tools/list under the Firefox backend, never present-and-throwing, because WebDriver BiDi has no command to redirect a download to a chosen directory.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'. A download is browser-scoped, so this names the tab for the lease check and for the echoed target, not which download is returned."
+        },
+        arm: {
+          type: "boolean",
+          description: "Arm download capture and return immediately instead of waiting: {armed:true,downloadPath,pending}. Call this BEFORE the click that triggers the download. 'pending' counts downloads that already completed and have not been collected yet, so an arm call doubles as a peek."
+        },
+        timeoutMs: {
+          type: "number",
+          description: "How long to wait for a download to complete, in milliseconds. Default 30000. Ignored with arm:true. A download that already completed and was not yet collected is returned immediately, so this only bounds the wait for a download still in flight."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "grant_permissions",
+    description: "Grant browser permissions for an origin up front, so a page asking for geolocation / notifications / clipboard gets an answer instead of showing a prompt no agent can click. 'permissions' takes CDP PermissionType values ('geolocation', 'notifications', 'clipboardReadWrite', 'camera', 'microphone', 'midi', ...); an unknown name is refused by Chrome with the bad value in the message. Returns {granted,origin,target}, or {reset:true,target} for a reset-only call. Grants are keyed by ORIGIN, not by tab: every tab on that origin is affected, including ones opened later. reset:true clears this server's previous grants first (or instead, when no permissions are given) — note CDP's reset is not origin-scoped, so it clears them for every origin at once. The grant lives on a connection this server process holds open and Chrome DISCARDS IT when that connection closes, so this is an MCP-server capability: under the one-shot CLI the grant dies with the process. Chrome-only (capability 'browser.permissions'): absent from tools/list under the Firefox backend, never present-and-throwing.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'. Used for the lease check and, when 'origin' is omitted, as the source of the origin to grant for."
+        },
+        permissions: {
+          type: "array",
+          items: {
+            type: "string"
+          },
+          description: "CDP PermissionType values to grant, e.g. ['geolocation'] or ['clipboardReadWrite','clipboardSanitizedWrite']. Required unless reset:true. An empty array is refused rather than treated as a successful no-op."
+        },
+        origin: {
+          type: "string",
+          description: "Origin the grant applies to, e.g. 'https://example.com'. Defaults to the target tab's own origin. Required explicitly when that tab has no grantable origin (data:, blob:, about:blank all serialize to the opaque origin 'null'), which is refused with a message naming the tab's url."
+        },
+        reset: {
+          type: "boolean",
+          description: "Clear this server's previous permission grants (Browser.resetPermissions). With 'permissions' it resets FIRST and then grants, so the result is exactly the listed permissions; on its own it is a reset-only call answering {reset:true}. Not scoped to 'origin': CDP resets every origin at once."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
   {
     name: "fill",
     description: "Fill an element by focusing it, clearing existing content, then inserting 'value' via Input.insertText (atomic paste-like commit, not per-character keystrokes). Target with exactly one of 'uid' (a CDP backendDOMNodeId from take_snapshot) or 'selector' (a CSS selector).",
@@ -4647,7 +5666,7 @@ var MANIFEST = [
   },
   {
     name: "claim_page",
-    description: "Take exclusive ownership of a browser tab and return an opaque lease token. Two modes. FRESH TAB: with no target and no targetId, opens a new tab (optionally at url) and claims it, so 'give me my own tab' is one call. TAKEOVER: with target, claims a tab that is already open — this is how you work in a tab the human already has open when they ask you to, instead of opening your own — resolving any target selector against the live page list and never creating anything. The answer's 'opened' flag says which happened (true only when this call created the tab), and that same creation record is what release_page consults, so a tab you took over is left open when you release it. Any later tool call against a leased tab must carry the matching token in its 'lease' argument or it is refused, naming the holder. The lease is reclaimable once its owning process dies, its ttlMs elapses without use, or its tab is closed. Refused from the CLI: a CLI invocation is one process per call, so its lease would be reclaimable immediately.",
+    description: "Take exclusive ownership of a browser tab and return an opaque lease token. Two modes. FRESH TAB: with no target and no targetId, opens a new tab (optionally at url) and claims it, so 'give me my own tab' is one call. TAKEOVER: with target, claims a tab that is already open — this is how you work in a tab the human already has open when they ask you to, instead of opening your own — resolving any target selector against the live page list and never creating anything. The answer's 'opened' flag says which happened (true only when this call created the tab), and that same creation record is what release_page consults, so a tab you took over is left open when you release it. Any later tool call against a leased tab must carry the matching token in its 'lease' argument or it is refused, naming the holder. The lease is reclaimable once its owning process dies, its ttlMs elapses without use, or its tab is closed. Refused from the CLI: a CLI invocation is one process per call, so its lease would be reclaimable immediately. IS SOMEBODY ELSE IN THIS TAB: the answer also carries 'humanActiveMs', milliseconds since input that this server did not dispatch — i.e. since a person last clicked, typed, or scrolled here. null means NO DATA (the tab carries no activity beacon, which is normal the first time anyone claims a person's tab, or every input on it was this server's own); it never means 'no human'. The field is absent entirely on a backend that cannot answer. On a takeover of a tab a human used within the last 30 seconds the answer additionally carries 'contention', a warning string. THE CLAIM IS NEVER REFUSED FOR THIS: taking over a person's tab is what takeover mode is for, so by the time you read the warning you already hold the lease and the tab is yours to drive. It tells you that driving it now means fighting a live person for the keyboard and mouse, so you can open your own tab instead or ask first. Known limits: input inside a cross-origin iframe is invisible to it, and a second MCP server's clicks read as human to this one.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4701,7 +5720,7 @@ var MANIFEST = [
   },
   {
     name: "list_leases",
-    description: "Enumerate every active lease for diagnosis: backend, target id, agent label, pid, createdAt, lastUsedAt, ttlMs, whether the owning process is still alive, and whether the lease is reclaimable and why. Requires no token. Never returns the lease nonce, so this cannot be used to forge a token. A row for a lease file that could not be read or parsed instead carries `unreadable` (the errno, or \"unparseable\"), with label, pid, and the timestamp fields as zero placeholders and stale always false, since stale is what marks a lease free to take and an unreadable one must never read that way. Under CDP_REQUIRE_LEASE this call reaps abandoned agent tabs exactly as list_pages does, reporting them in an additive 'reaped' array and omitting their rows from the listing.",
+    description: "Enumerate every active lease for diagnosis: backend, target id, agent label, pid, createdAt, lastUsedAt, ttlMs, whether the owning process is still alive, and whether the lease is reclaimable and why. Requires no token. Never returns the lease nonce, so this cannot be used to forge a token. A row for a lease file that could not be read or parsed instead carries `unreadable` (the errno, or \"unparseable\"), with label, pid, and the timestamp fields as zero placeholders and stale always false, since stale is what marks a lease free to take and an unreadable one must never read that way. Under CDP_REQUIRE_LEASE this call reaps abandoned agent tabs exactly as list_pages does (see that tool's description for the grace period between a lease reading reclaimable and its tab actually being closed), reporting them in an additive 'reaped' array and omitting their rows from the listing. A row also carries 'humanActiveMs' — milliseconds since input this server did not dispatch, i.e. since a person last used that tab — WHERE THE TAB CAN ANSWER. The field is ABSENT rather than null when it cannot: no activity beacon on that tab, every input on it accounted for by this server, a row belonging to the other backend, a tab no longer open, or a page that would not evaluate. Absence therefore means 'no answer', never 'nobody is there'. Note that lastUsedAt measures TOOLKIT calls only, so a tab a person has been typing in for ten minutes looks perfectly idle by that field and is exactly the case humanActiveMs exists to expose. Two further fields are computed fresh on every call, never read off disk: 'idleMs' (now minus lastUsedAt) and 'expiresAt' (lastUsedAt plus ttlMs — the same value claim_page already returns under that name). Both are omitted on an 'unreadable' row, whose lastUsedAt and ttlMs are the zeroed placeholders described above.",
     inputSchema: {
       type: "object",
       properties: {},
@@ -5465,6 +6484,8 @@ var KEY_VALUES = {
 };
 var MODIFIER_VALUES = { shift: "", control: "", ctrl: "", alt: "", meta: "", cmd: "", command: "" };
 var BUTTON_CODES = { left: 0, middle: 1, right: 2 };
+var ARM_SCROLL_SETTLE_WATCH_SOURCE = "function(){window.__cdpScrollSettle=new Promise((resolve)=>{let t;const done=()=>{window.removeEventListener('scroll',on,true);resolve(true);};" + "const on=()=>{clearTimeout(t);t=setTimeout(done,60);};window.addEventListener('scroll',on,true);t=setTimeout(done,60);setTimeout(done,500);});}";
+var AWAIT_SCROLL_SETTLE_SOURCE = "function(){return window.__cdpScrollSettle;}";
 var BIDI_CAPABILITIES = new Set([
   "emulate.deviceMetrics",
   "screenshot.fullPage",
@@ -5486,6 +6507,7 @@ async function getConnection(port, timeoutMs) {
   connections.set(port, conn);
   return conn;
 }
+var bidiBeaconScripts = new Map;
 async function safeTitle(conn, contextId) {
   try {
     const res = await conn.send("script.evaluate", { expression: "document.title", target: { context: contextId }, awaitPromise: false });
@@ -5549,9 +6571,31 @@ class BidiPageDriver {
     this.info = info;
     this.browser = browser;
   }
+  async urlAndReadyState() {
+    const raw = await this.conn.send("script.evaluate", {
+      expression: "location.href + '\\u0000' + document.readyState",
+      target: { context: this.contextId },
+      awaitPromise: false
+    }).then((r) => r.type === "success" ? String(deserializeRemote(r.result) ?? "") : "").catch(() => "");
+    const [url = "", ready = ""] = raw.split("\x00");
+    return [url, ready];
+  }
+  async settleAfterTraversal(beforeUrl, waitUntil, timeoutMs) {
+    const ready = waitUntil === "domcontentloaded" ? ["interactive", "complete"] : ["complete"];
+    const deadline = Date.now() + timeoutMs;
+    for (;; ) {
+      const [url, state] = await this.urlAndReadyState();
+      if (url && url !== beforeUrl && ready.includes(state))
+        return { waitedFor: waitUntil, url };
+      if (Date.now() >= deadline)
+        return { waitedFor: "timeout", url: url || beforeUrl };
+      await new Promise((r) => setTimeout(r, 50));
+    }
+  }
   async navigate(opts) {
     const reload = opts.reload === true;
-    if (!reload && !opts.url)
+    const history = opts.history;
+    if (!reload && !history && !opts.url)
       throw driverError2("page-error", "navigate: 'url' is required unless reload:true");
     const waitUntil = opts.waitUntil ?? "load";
     const wait = waitUntil === "domcontentloaded" ? "interactive" : "complete";
@@ -5561,6 +6605,17 @@ class BidiPageDriver {
         const r2 = await this.conn.send("browsingContext.reload", { context: this.contextId, ignoreCache: opts.ignoreCache === true, wait }, sendOpts);
         return { url: r2.url, contextId: this.contextId, reloaded: true, waitedFor: waitUntil };
       }
+      if (history) {
+        const [beforeUrl] = await this.urlAndReadyState();
+        await this.conn.send("browsingContext.traverseHistory", { context: this.contextId, delta: history === "back" ? -1 : 1 }, sendOpts).catch((e) => {
+          const msg = e instanceof Error ? e.message : String(e);
+          if (/no such history entry|history/i.test(msg))
+            throw driverError2("page-error", `navigate: no history entry to go ${history} to (${msg})`);
+          throw e;
+        });
+        const settled = await this.settleAfterTraversal(beforeUrl, waitUntil, opts.timeoutMs ?? 15000);
+        return { url: settled.url, contextId: this.contextId, traversed: history, waitedFor: settled.waitedFor };
+      }
       const r = await this.conn.send("browsingContext.navigate", { context: this.contextId, url: opts.url, wait }, sendOpts);
       return { url: r.url, contextId: this.contextId, waitedFor: waitUntil };
     } catch (e) {
@@ -5643,6 +6698,7 @@ class BidiPageDriver {
       throw driverError2("stale-uid", `uid does not resolve: ${uid}`);
   }
   async performActions(actions) {
+    recordDispatch("firefox", this.contextId);
     try {
       await this.conn.send("input.performActions", { context: this.contextId, actions });
     } catch (e) {
@@ -5663,6 +6719,9 @@ class BidiPageDriver {
     return { x, y };
   }
   async click(loc, opts) {
+    if (opts?.modifiers && opts.modifiers.length > 0) {
+      throw driverError2("unsupported", "click: 'modifiers' is not supported by the Firefox/BiDi driver; omit 'modifiers' or use --browser chrome for a modifier click.");
+    }
     const ref = await resolveElementLocator2(this.conn, this.contextId, loc);
     const { x, y } = await this.centerOf(ref);
     const button = BUTTON_CODES[opts?.button ?? "left"];
@@ -5672,19 +6731,53 @@ class BidiPageDriver {
     await this.performActions([{ type: "pointer", id: "cdp-mouse", actions }]);
     return { x, y };
   }
-  async drag(from, to) {
+  async scroll(anchor, opts) {
+    const { x, y } = await this.resolveScrollPoint(anchor);
+    const deltaX = Math.round(opts.deltaX ?? 0);
+    const deltaY = Math.round(opts.deltaY ?? 0);
+    await this.callFunctionValue(ARM_SCROLL_SETTLE_WATCH_SOURCE, []);
+    const actions = [{ type: "scroll", x: Math.round(x), y: Math.round(y), deltaX, deltaY }];
+    await this.performActions([{ type: "wheel", id: "cdp-wheel", actions }]);
+    await this.callFunctionValue(AWAIT_SCROLL_SETTLE_SOURCE, []).catch(() => {
+      return;
+    });
+    return { x, y };
+  }
+  async resolveScrollPoint(anchor) {
+    if (anchor === undefined) {
+      const v = await this.callFunctionValue("function(){return {x: window.innerWidth / 2, y: window.innerHeight / 2};}", []);
+      if (!v || typeof v !== "object")
+        throw driverError2("page-error", "could not measure viewport for scroll center");
+      return v;
+    }
+    if ("x" in anchor)
+      return anchor;
+    return this.centerOf(await resolveElementLocator2(this.conn, this.contextId, anchor));
+  }
+  async drag(from, to, opts) {
+    if (opts?.mode === "html5") {
+      throw driverError2("unsupported", "drag: mode:'html5' is not supported by the Firefox/BiDi driver (WebDriver BiDi has no drag-interception primitive); " + "omit 'mode' for the synthetic-mouse drag, or use --browser chrome for real HTML5 drag events.");
+    }
     const fromPt = await this.centerOf(await resolveElementLocator2(this.conn, this.contextId, from));
-    const toPt = await this.centerOf(await resolveElementLocator2(this.conn, this.contextId, to));
+    const toPt = await this.resolveDragDestination(to, fromPt);
+    const steps = Math.max(1, Math.trunc(opts?.steps ?? 2));
     const actions = [
       { type: "pointerMove", x: fromPt.x, y: fromPt.y, duration: 0 },
-      { type: "pointerDown", button: 0 },
-      { type: "pointerMove", x: (fromPt.x + toPt.x) / 2, y: (fromPt.y + toPt.y) / 2, duration: 50 },
-      { type: "pointerMove", x: toPt.x, y: toPt.y, duration: 50 },
-      { type: "pointerUp", button: 0 }
+      { type: "pointerDown", button: 0 }
     ];
+    for (const pt of interpolatePoints(fromPt, toPt, steps))
+      actions.push({ type: "pointerMove", x: pt.x, y: pt.y, duration: 50 });
+    actions.push({ type: "pointerUp", button: 0 });
     await this.performActions([{ type: "pointer", id: "cdp-mouse", actions }]);
     return { from: fromPt, to: toPt };
   }
+  async resolveDragDestination(to, fromPt) {
+    if ("dx" in to)
+      return { x: fromPt.x + to.dx, y: fromPt.y + to.dy };
+    if ("x" in to)
+      return to;
+    return this.centerOf(await resolveElementLocator2(this.conn, this.contextId, to));
+  }
   async sendKeys(text) {
     if (!text.length)
       return;
@@ -6054,7 +7147,60 @@ class BidiBrowserDriver {
     const info = await pageInfoOf(conn, ctx);
     return new BidiPageDriver(conn, ctx.context, info, this);
   }
+  async installActivityBeacon(contextId) {
+    const conn = await getConnection(this.port, this.timeoutMs).catch(() => {
+      return;
+    });
+    if (!conn)
+      return false;
+    try {
+      const key = `${this.port}:${contextId}`;
+      if (!bidiBeaconScripts.has(key)) {
+        const registered = await conn.send("script.addPreloadScript", {
+          functionDeclaration: BEACON_FUNCTION_DECLARATION,
+          contexts: [contextId]
+        });
+        bidiBeaconScripts.set(key, registered.script);
+      }
+      await conn.send("script.evaluate", {
+        expression: BEACON_SOURCE,
+        target: { context: contextId },
+        awaitPromise: false
+      });
+      return true;
+    } catch {
+      return false;
+    } finally {
+      conn.release();
+    }
+  }
+  async readActivityBeacon(contextId) {
+    const conn = await getConnection(this.port, this.timeoutMs).catch(() => {
+      return;
+    });
+    if (!conn)
+      return null;
+    try {
+      const res = await conn.send("script.evaluate", {
+        expression: BEACON_READ_EXPRESSION,
+        target: { context: contextId },
+        awaitPromise: false
+      });
+      if (res.type !== "success")
+        return null;
+      const value = deserializeRemote(res.result);
+      return typeof value === "number" && Number.isFinite(value) ? value : null;
+    } catch {
+      return null;
+    } finally {
+      conn.release();
+    }
+  }
   async dispose() {
+    for (const key of [...bidiBeaconScripts.keys()]) {
+      if (key.startsWith(`${this.port}:`))
+        bidiBeaconScripts.delete(key);
+    }
     const conn = connections.get(this.port);
     if (!conn)
       return;
@@ -6071,7 +7217,7 @@ import { spawn as spawn3 } from "node:child_process";
 import { mkdtempSync, rmSync } from "node:fs";
 import { createConnection, createServer } from "node:net";
 import { tmpdir } from "node:os";
-import { join as join7 } from "node:path";
+import { join as join9 } from "node:path";
 function resolveBinary() {
   const candidates = [
     process.env.FIREFOX_BIN,
@@ -6145,7 +7291,7 @@ async function launchFirefox(opts = {}) {
   const binary = resolveBinary();
   const port = await pickPort(opts.port);
   const isThrowaway = opts.profilePath === undefined;
-  const profilePath = opts.profilePath ?? mkdtempSync(join7(tmpdir(), "cdp-toolkit-ff-profile-"));
+  const profilePath = opts.profilePath ?? mkdtempSync(join9(tmpdir(), "cdp-toolkit-ff-profile-"));
   const args = ["--profile", profilePath, "--remote-debugging-port", String(port), "--no-remote"];
   if (opts.headless)
     args.push("--headless");
@@ -6415,7 +7561,7 @@ var FIREFOX_TOOLS = {
 };
 
 // src/mcp.ts
-var VERSION = "1.7.0";
+var VERSION = "1.8.0";
 var BROWSER = resolveBrowserKind(stripBrowserFlag(process.argv.slice(2)));
 var AVAILABILITY = toolAvailability(BROWSER);
 var AVAILABLE_NAMES = new Set(AVAILABILITY.available);
@@ -6462,8 +7608,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (!neutralFn)
       return { content: [{ type: "text", text: `unknown tool: ${name}` }], isError: true };
     try {
-      const session = await getOrCreateFirefoxSession();
-      const result = await neutralFn(session.driver, args);
+      const session2 = await getOrCreateFirefoxSession();
+      const result = await neutralFn(session2.driver, args);
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
@@ -6481,6 +7627,7 @@ async function shutdown() {
     return;
   shuttingDown = true;
   await disposeFirefoxSession();
+  await disposeBrowserSession();
   process.exit(0);
 }
 process.on("SIGINT", () => void shutdown());