cdp-toolkit 1.1.0 → 1.2.0

package/dist/cli.js

@@ -1,5 +1,257 @@
 #!/usr/bin/env node
 
+// src/leases.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, readdir, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+var DEFAULT_LEASE_TTL_MS = 900000;
+function leaseDir() {
+  return process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+}
+function leaseTtlMs() {
+  const raw = Number(process.env.CDP_LEASE_TTL_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_LEASE_TTL_MS;
+}
+function safeId(id) {
+  return id.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+function leaseFile(backend, targetId) {
+  return join(leaseDir(), `lease-${backend}-${safeId(targetId)}.json`);
+}
+function mintToken(backend, targetId, nonce) {
+  return `${backend}:${targetId}:${nonce}`;
+}
+function tokenParts(token) {
+  if (typeof token !== "string")
+    return;
+  const first = token.indexOf(":");
+  const last = token.lastIndexOf(":");
+  if (first <= 0 || last <= first)
+    return;
+  const backend = token.slice(0, first);
+  if (backend !== "chrome" && backend !== "firefox")
+    return;
+  const targetId = token.slice(first + 1, last);
+  const nonce = token.slice(last + 1);
+  if (!targetId.length || !/^[0-9a-f]{24}$/.test(nonce))
+    return;
+  return { backend, targetId, nonce };
+}
+
+class LeaseConflictError extends Error {
+  targetId;
+  holder;
+  constructor(message, targetId, holder) {
+    super(message);
+    this.targetId = targetId;
+    this.holder = holder;
+    this.name = "LeaseConflictError";
+  }
+}
+async function readLease(backend, targetId) {
+  let raw;
+  try {
+    raw = await readFile(leaseFile(backend, targetId), "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT")
+      return;
+    throw err;
+  }
+  try {
+    const rec = JSON.parse(raw);
+    if (typeof rec?.nonce === "string" && typeof rec?.pid === "number")
+      return rec;
+  } catch {}
+  return;
+}
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0)
+    return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+function staleReason(rec, opts) {
+  if (!isPidAlive(rec.pid))
+    return "dead-pid";
+  if (opts.now - rec.lastUsedAt > rec.ttlMs)
+    return "expired";
+  if (opts.liveIds && !opts.liveIds.includes(rec.targetId))
+    return "target-gone";
+  return false;
+}
+async function claimLease(backend, targetId, opts) {
+  const now = opts.now ?? Date.now();
+  await mkdir(leaseDir(), { recursive: true });
+  for (let attempt = 0;attempt < 3; attempt++) {
+    const record = {
+      backend,
+      targetId,
+      nonce: randomBytes(12).toString("hex"),
+      pid: process.pid,
+      label: opts.label,
+      createdAt: now,
+      lastUsedAt: now,
+      ttlMs: opts.ttlMs ?? leaseTtlMs()
+    };
+    try {
+      await writeFile(leaseFile(backend, targetId), JSON.stringify(record), { flag: "wx" });
+      return { token: mintToken(backend, targetId, record.nonce), record };
+    } catch (err) {
+      if (err.code !== "EEXIST")
+        throw err;
+    }
+    const existing = await readLease(backend, targetId);
+    if (!existing)
+      continue;
+    const stale = staleReason(existing, { now, liveIds: opts.liveIds });
+    if (!stale) {
+      throw new LeaseConflictError(`target '${targetId}' is already leased by '${existing.label}' (pid ${existing.pid}); call release_page with that lease's token, or list_leases to inspect it`, targetId, existing.label);
+    }
+    await unlink(leaseFile(backend, targetId)).catch(() => {
+      return;
+    });
+  }
+  throw new LeaseConflictError(`target '${targetId}' could not be claimed after 3 attempts: another process is claiming and releasing it concurrently`, targetId);
+}
+async function releaseLease(token) {
+  const parts = tokenParts(token);
+  if (!parts)
+    return { released: false };
+  const rec = await readLease(parts.backend, parts.targetId);
+  if (!rec || rec.nonce !== parts.nonce)
+    return { released: false };
+  await unlink(leaseFile(parts.backend, parts.targetId)).catch(() => {
+    return;
+  });
+  return { released: true };
+}
+async function releaseLeaseFor(backend, targetId) {
+  if (!await readLease(backend, targetId))
+    return { released: false };
+  await unlink(leaseFile(backend, targetId)).catch(() => {
+    return;
+  });
+  return { released: true };
+}
+var leaseScope = new AsyncLocalStorage;
+function withLeaseScope(lease, fn) {
+  return leaseScope.run(lease, fn);
+}
+function currentLease() {
+  return leaseScope.getStore();
+}
+function leaseFromArgs(args) {
+  if (!args || typeof args !== "object")
+    return;
+  const lease = args.lease;
+  return typeof lease === "string" && lease.length > 0 ? lease : undefined;
+}
+async function touchLease(rec, now = Date.now()) {
+  const current = await readLease(rec.backend, rec.targetId).catch(() => {
+    return;
+  });
+  if (!current || current.nonce !== rec.nonce)
+    return;
+  await writeFile(leaseFile(current.backend, current.targetId), JSON.stringify({ ...current, lastUsedAt: now }), "utf8").catch(() => {
+    return;
+  });
+}
+function describeTarget(targetId, ctx) {
+  const url = ctx.url ? ` (url ${ctx.url})` : ctx.title ? ` (title ${JSON.stringify(ctx.title)})` : "";
+  return `target '${targetId}'${url}`;
+}
+async function assertLeaseOk(backend, targetId, ctx = {}) {
+  const token = ctx.lease ?? currentLease();
+  const now = ctx.now ?? Date.now();
+  const rec = await readLease(backend, targetId);
+  const held = rec && !staleReason(rec, { now, liveIds: ctx.liveIds }) ? rec : undefined;
+  const where = describeTarget(targetId, ctx);
+  if (token === undefined) {
+    if (!held)
+      return;
+    throw new LeaseConflictError(`${where} is leased by '${held.label}' (pid ${held.pid}). Pass that lease's token as the 'lease' argument, or call release_page to free it. list_leases shows every active lease.`, targetId, held.label);
+  }
+  const parts = tokenParts(token);
+  if (!parts) {
+    throw new LeaseConflictError(`malformed lease token for ${where}. Pass back the token claim_page returned, never a constructed one.`, targetId);
+  }
+  if (parts.backend !== backend || parts.targetId !== targetId) {
+    if (!held)
+      return;
+    throw new LeaseConflictError(`the lease token you passed is for ${parts.backend} target '${parts.targetId}', not ${where}, which is leased by '${held.label}'. Resolve the tab you actually hold, or claim this one.`, targetId, held.label);
+  }
+  if (!held) {
+    throw new LeaseConflictError(`${where} is not leased any more: the token you passed belongs to a lease that was released or reclaimed. Call claim_page again to take the tab.`, targetId);
+  }
+  if (parts.nonce !== held.nonce) {
+    throw new LeaseConflictError(`${where} was reclaimed and is now leased by '${held.label}' (pid ${held.pid}). Your token was invalidated by that reclamation. Call claim_page again if you still need this tab.`, targetId, held.label);
+  }
+  await touchLease(held, now);
+}
+var LEASE_FILE_RE = /^lease-(chrome|firefox)-(.+)\.json$/;
+async function listLeases(opts = {}) {
+  const now = opts.now ?? Date.now();
+  let names = [];
+  try {
+    names = await readdir(leaseDir());
+  } catch (err) {
+    if (err.code === "ENOENT")
+      return [];
+    throw err;
+  }
+  const out = [];
+  for (const name of names) {
+    const parts = LEASE_FILE_RE.exec(name);
+    if (!parts)
+      continue;
+    const fromName = {
+      backend: parts[1],
+      targetId: parts[2],
+      label: "",
+      pid: 0,
+      createdAt: 0,
+      lastUsedAt: 0,
+      ttlMs: 0,
+      pidAlive: false,
+      stale: false
+    };
+    let rec;
+    try {
+      rec = JSON.parse(await readFile(join(leaseDir(), name), "utf8"));
+    } catch (err) {
+      const code = err.code;
+      if (code === "ENOENT")
+        continue;
+      out.push({ ...fromName, unreadable: code ?? "unparseable" });
+      continue;
+    }
+    if (typeof rec?.nonce !== "string" || typeof rec?.pid !== "number") {
+      out.push({ ...fromName, unreadable: "unparseable" });
+      continue;
+    }
+    out.push({
+      backend: rec.backend,
+      targetId: rec.targetId,
+      label: rec.label,
+      pid: rec.pid,
+      createdAt: rec.createdAt,
+      lastUsedAt: rec.lastUsedAt,
+      ttlMs: rec.ttlMs,
+      pidAlive: isPidAlive(rec.pid),
+      stale: staleReason(rec, {
+        now,
+        liveIds: opts.liveBackend === undefined || opts.liveBackend === rec.backend ? opts.liveIds : undefined
+      })
+    });
+  }
+  return out;
+}
+
 // src/client.ts
 var BASE = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
 var DEFAULT_TIMEOUT_MS = Number(process.env.CDP_TIMEOUT_MS ?? 15000);
@@ -153,8 +405,13 @@ async function browserWsUrl() {
   const v = await httpJson("/json/version");
   return v.webSocketDebuggerUrl;
 }
-async function resolveTarget(selector) {
+async function resolveTarget(selector, opts = {}) {
   const targets = await listTargets();
+  const hit = pickTarget(targets, selector);
+  await assertLeaseOk("chrome", hit.id, { lease: opts.lease, url: hit.url, title: hit.title });
+  return hit;
+}
+function pickTarget(targets, selector) {
   const pages = targets.filter((t) => t.type === "page");
   if (!selector || selector === "active") {
     if (!pages.length)
@@ -190,7 +447,7 @@ async function openBrowser(opts = {}) {
   return new CdpConnection(await browserWsUrl(), opts).connect();
 }
 async function openPage(selector, opts = {}) {
-  const target = await resolveTarget(selector);
+  const target = await resolveTarget(selector, { lease: opts.lease });
   const conn = await new CdpConnection(target.webSocketDebuggerUrl, opts).connect();
   return { conn, target };
 }
@@ -1071,9 +1328,63 @@ function createCdpDriver() {
   return new CdpBrowserDriver;
 }
 
+// src/leases-tools.ts
+class LeaseToolError extends Error {
+}
+function backendOf(driver) {
+  return driver.scheme === "bidi" ? "firefox" : "chrome";
+}
+async function claimPage(driver, args = {}) {
+  const backend = backendOf(driver);
+  const label = typeof args.label === "string" && args.label.length ? args.label : `pid-${process.pid}`;
+  const pages = await driver.listPages();
+  let targetId = args.targetId;
+  let url = args.url ?? "about:blank";
+  if (targetId === undefined || targetId === "") {
+    const page = await driver.newPage(args.url);
+    targetId = page.id;
+    url = page.url;
+  } else {
+    const existing = pages.find((p) => p.id === targetId);
+    if (!existing)
+      throw new LeaseToolError(`claim_page: no page target with id '${targetId}'`);
+    url = existing.url;
+  }
+  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
+  });
+  return {
+    lease: token,
+    targetId,
+    url,
+    label: record.label,
+    ttlMs: record.ttlMs,
+    expiresAt: record.lastUsedAt + record.ttlMs
+  };
+}
+async function releasePage(_driver, args) {
+  if (typeof args.lease !== "string" || !args.lease.length) {
+    throw new LeaseToolError("release_page requires the 'lease' token returned by claim_page");
+  }
+  return releaseLease(args.lease);
+}
+async function listLeasesTool(driver, _args = {}) {
+  const liveIds = (await driver.listPages()).map((p) => p.id);
+  const leases = await listLeases({ liveIds, liveBackend: backendOf(driver) });
+  return { leases, count: leases.length };
+}
+var LEASE_TOOLS = {
+  claim_page: claimPage,
+  release_page: releasePage,
+  list_leases: listLeasesTool
+};
+
 // src/shared-tools.ts
-import { mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { mkdir as mkdir2, writeFile as writeFile2 } from "node:fs/promises";
+import { join as join2 } from "node:path";
 var ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 var STATE_DIR = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
 
@@ -1082,6 +1393,9 @@ class SharedToolError extends Error {
 function target3(p) {
   return { id: p.id, url: p.url, title: p.title };
 }
+function backendOf2(driver) {
+  return driver.scheme === "bidi" ? "firefox" : "chrome";
+}
 async function withPage2(driver, target, fn) {
   const page = await driver.page(target);
   try {
@@ -1092,6 +1406,11 @@ async function withPage2(driver, target, fn) {
 }
 async function resolvePage(driver, selector) {
   const pages = await driver.listPages();
+  const hit = await pickPage(driver, pages, selector);
+  await assertLeaseOk(backendOf2(driver), hit.id, { url: hit.url, title: hit.title });
+  return hit;
+}
+async function pickPage(driver, pages, selector) {
   if (selector === undefined || selector === "active") {
     if (!pages.length)
       throw new SharedToolError("no page targets open");
@@ -1139,18 +1458,27 @@ async function listPages(driver, args = {}) {
 }
 async function newPage(driver, args = {}) {
   const p = await driver.newPage(args.url);
-  return { targetId: p.id, url: p.url };
+  if (args.claim !== true)
+    return { targetId: p.id, url: p.url };
+  const { record, token } = await claimLease(backendOf2(driver), p.id, {
+    label: typeof args.label === "string" && args.label.length ? args.label : `pid-${process.pid}`,
+    ttlMs: typeof args.ttlMs === "number" && args.ttlMs > 0 ? args.ttlMs : leaseTtlMs()
+  });
+  return { targetId: p.id, url: p.url, lease: token, label: record.label, expiresAt: record.lastUsedAt + record.ttlMs };
 }
 async function closePage(driver, args) {
   if (args.target === undefined || args.target === "")
     throw new SharedToolError("close_page requires an explicit target; refusing to guess which page to close");
   const p = await resolvePage(driver, args.target);
   const res = await driver.closePage(p.id);
-  return { closed: p.id, success: res.success };
+  if (!res.success)
+    return { closed: p.id, success: false, leaseReleased: false };
+  const released = await releaseLeaseFor(backendOf2(driver), p.id);
+  return { closed: p.id, success: true, ...released.released ? { leaseReleased: true } : {} };
 }
 async function writeSelectedFile(id) {
-  await mkdir(STATE_DIR, { recursive: true });
-  await writeFile(join(STATE_DIR, "selected"), id, "utf8");
+  await mkdir2(STATE_DIR, { recursive: true });
+  await writeFile2(join2(STATE_DIR, "selected"), id, "utf8");
 }
 async function selectPage(driver, args) {
   if (args.target === undefined || args.target === "")
@@ -1305,10 +1633,10 @@ async function takeScreenshot(driver, args = {}) {
     const { data, format: outFormat } = await page.screenshot({ format, quality: args.quality, fullPage: args.fullPage, ...clip ? { clip } : {} });
     if (data.byteLength === 0)
       throw new SharedToolError("captureScreenshot returned empty data");
-    await mkdir(ARTIFACT_DIR, { recursive: true });
+    await mkdir2(ARTIFACT_DIR, { recursive: true });
     const ext = outFormat === "jpeg" ? "jpg" : "png";
-    const path = args.savePath ?? join(ARTIFACT_DIR, `screenshot-${page.info.id.slice(0, 8)}-${stamp()}.${ext}`);
-    await writeFile(path, Buffer.from(data));
+    const path = args.savePath ?? join2(ARTIFACT_DIR, `screenshot-${page.info.id.slice(0, 8)}-${stamp()}.${ext}`);
+    await writeFile2(path, Buffer.from(data));
     const result = {
       path,
       bytes: data.byteLength,
@@ -1371,10 +1699,10 @@ var SHARED_TOOLS = {
 };
 
 // src/tools/console.ts
-import { readFile } from "node:fs/promises";
+import { readFile as readFile2 } from "node:fs/promises";
 
 // src/tools/recorder.ts
-import { mkdir as mkdir2, appendFile, writeFile as writeFile2, copyFile } from "node:fs/promises";
+import { mkdir as mkdir3, appendFile, writeFile as writeFile3, copyFile } from "node:fs/promises";
 var ARTIFACT_DIR2 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 function recFile(targetId) {
   return `${ARTIFACT_DIR2}/rec-${targetId}.jsonl`;
@@ -1395,11 +1723,11 @@ var CONSOLE_EVENTS = ["Runtime.consoleAPICalled", "Runtime.exceptionThrown", "Lo
 async function startRecorder(target, opts = {}) {
   const network = opts.network ?? true;
   const consoleCap = opts.console ?? true;
-  await mkdir2(ARTIFACT_DIR2, { recursive: true });
+  await mkdir3(ARTIFACT_DIR2, { recursive: true });
   const { conn, target: resolved } = await openPage(target, { timeoutMs: opts.timeoutMs });
   const file = opts.file ?? recFile(resolved.id);
   if (opts.truncate) {
-    await writeFile2(file, "");
+    await writeFile3(file, "");
   }
   let chain = Promise.resolve();
   let dropped = 0;
@@ -1541,7 +1869,7 @@ function lineToEntry(line, index) {
 async function readConsoleEntries(file) {
   let raw;
   try {
-    raw = await readFile(file, "utf8");
+    raw = await readFile2(file, "utf8");
   } catch {
     return [];
   }
@@ -1597,7 +1925,7 @@ async function getConsoleMessage(args = {}) {
 }
 
 // src/tools/network.ts
-import { readFile as readFile2 } from "node:fs/promises";
+import { readFile as readFile3 } from "node:fs/promises";
 var DEFAULT_CAPTURE_MS2 = 2500;
 function asHeaders(v) {
   if (!v || typeof v !== "object")
@@ -1664,7 +1992,7 @@ function correlate(lines) {
 async function readNetworkRequests(file) {
   let raw;
   try {
-    raw = await readFile2(file, "utf8");
+    raw = await readFile3(file, "utf8");
   } catch {
     return [];
   }
@@ -1746,8 +2074,8 @@ async function getNetworkRequest(args = {}) {
 }
 
 // src/tools/performance.ts
-import { mkdir as mkdir3, readFile as readFile3, writeFile as writeFile3, stat, unlink } from "node:fs/promises";
-import { join as join2 } from "node:path";
+import { mkdir as mkdir4, readFile as readFile4, writeFile as writeFile4, stat, unlink as unlink2 } from "node:fs/promises";
+import { join as join3 } from "node:path";
 var ARTIFACT_DIR3 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 var STATE_DIR2 = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
 var DEFAULT_CATEGORIES = [
@@ -1765,7 +2093,7 @@ function shortId(id) {
   return id.slice(0, 8);
 }
 function stateFilePath() {
-  return join2(STATE_DIR2, "trace-state.json");
+  return join3(STATE_DIR2, "trace-state.json");
 }
 function bufferTraceData(conn, sink) {
   return conn.on("Tracing.dataCollected", (params) => {
@@ -1787,10 +2115,10 @@ async function endTrace(conn, sink, timeoutMs = 30000) {
   return sink;
 }
 async function writeTrace(events, targetId) {
-  await mkdir3(ARTIFACT_DIR3, { recursive: true });
-  const path = join2(ARTIFACT_DIR3, `trace-${shortId(targetId)}-${stamp2()}.json`);
+  await mkdir4(ARTIFACT_DIR3, { recursive: true });
+  const path = join3(ARTIFACT_DIR3, `trace-${shortId(targetId)}-${stamp2()}.json`);
   const body = JSON.stringify({ traceEvents: events, metadata: { source: "cdp-toolkit" } });
-  await writeFile3(path, body, "utf8");
+  await writeFile4(path, body, "utf8");
   const { size } = await stat(path);
   return { path, bytes: size };
 }
@@ -1810,7 +2138,7 @@ async function performanceStartTrace(args = {}) {
     throw err;
   }
   liveTraces.set(target.id, { conn, target, events, startedAt: Date.now() });
-  await mkdir3(STATE_DIR2, { recursive: true });
+  await mkdir4(STATE_DIR2, { recursive: true });
   const state = {
     targetId: target.id,
     url: target.url,
@@ -1818,7 +2146,7 @@ async function performanceStartTrace(args = {}) {
     pid: process.pid,
     categories
   };
-  await writeFile3(stateFilePath(), JSON.stringify(state), "utf8");
+  await writeFile4(stateFilePath(), JSON.stringify(state), "utf8");
   return {
     target: { id: target.id, url: target.url, title: target.title },
     categories,
@@ -1831,7 +2159,7 @@ async function performanceStopTrace(args = {}) {
   if (!entry) {
     let hint = "";
     try {
-      const raw = await readFile3(stateFilePath(), "utf8");
+      const raw = await readFile4(stateFilePath(), "utf8");
       const state = JSON.parse(raw);
       hint = state.pid === process.pid ? ` (state file lists target ${shortId(state.targetId)} but its live connection is gone)` : ` (trace was started by a DIFFERENT process pid=${state.pid}; live recordings cannot cross process boundaries)`;
     } catch {}
@@ -1843,7 +2171,7 @@ async function performanceStopTrace(args = {}) {
   } finally {
     conn.close();
     liveTraces.delete(target.id);
-    await unlink(stateFilePath()).catch(() => {});
+    await unlink2(stateFilePath()).catch(() => {});
   }
   const written = await writeTrace(events, target.id);
   const metrics = analyzeEvents(events);
@@ -1961,7 +2289,7 @@ async function performanceAnalyzeInsight(args = {}) {
   }
   let raw;
   try {
-    raw = await readFile3(args.tracePath, "utf8");
+    raw = await readFile4(args.tracePath, "utf8");
   } catch (err) {
     throw new CdpError(`cannot read trace file '${args.tracePath}': ${err.message}`);
   }
@@ -1978,8 +2306,8 @@ async function performanceAnalyzeInsight(args = {}) {
 }
 
 // src/tools/heap.ts
-import { mkdir as mkdir4, writeFile as writeFile4 } from "node:fs/promises";
-import { join as join3 } from "node:path";
+import { mkdir as mkdir5, writeFile as writeFile5 } from "node:fs/promises";
+import { join as join4 } from "node:path";
 var ARTIFACT_DIR4 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 function stamp3(targetId) {
   const short = targetId.slice(0, 8);
@@ -2004,9 +2332,9 @@ async function takeHeapsnapshot(args = {}) {
     if (snapshot.length === 0) {
       throw new Error("HeapProfiler.takeHeapSnapshot produced no chunks");
     }
-    await mkdir4(ARTIFACT_DIR4, { recursive: true });
-    const path = args.savePath ? args.savePath.startsWith("/") ? args.savePath : join3(ARTIFACT_DIR4, args.savePath) : join3(ARTIFACT_DIR4, `take_heapsnapshot-${stamp3(target.id)}.heapsnapshot`);
-    await writeFile4(path, snapshot, "utf8");
+    await mkdir5(ARTIFACT_DIR4, { recursive: true });
+    const path = args.savePath ? args.savePath.startsWith("/") ? args.savePath : join4(ARTIFACT_DIR4, args.savePath) : join4(ARTIFACT_DIR4, `take_heapsnapshot-${stamp3(target.id)}.heapsnapshot`);
+    await writeFile5(path, snapshot, "utf8");
     const bytes = Buffer.byteLength(snapshot, "utf8");
     return {
       path,
@@ -2019,7 +2347,7 @@ async function takeHeapsnapshot(args = {}) {
 
 // src/tools/lighthouse.ts
 import { spawn } from "node:child_process";
-import { mkdir as mkdir5, readFile as readFile4, stat as stat2 } from "node:fs/promises";
+import { mkdir as mkdir6, readFile as readFile5, stat as stat2 } from "node:fs/promises";
 var ARTIFACT_DIR5 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 function cdpPort() {
   const base = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
@@ -2080,7 +2408,7 @@ async function lighthouseAudit(args) {
   const url = args.url.trim();
   const timeoutMs = args.timeoutMs ?? 120000;
   const port = cdpPort();
-  await mkdir5(ARTIFACT_DIR5, { recursive: true });
+  await mkdir6(ARTIFACT_DIR5, { recursive: true });
   const outPath = args.savePath ?? `${ARTIFACT_DIR5}/lighthouse-${shortHost(url)}-${stamp4()}.json`;
   const formFactor = args.formFactor ?? "desktop";
   const lhArgs = [
@@ -2109,7 +2437,7 @@ async function lighthouseAudit(args) {
   }
   let raw;
   try {
-    raw = await readFile4(outPath, "utf8");
+    raw = await readFile5(outPath, "utf8");
   } catch {
     raw = undefined;
   }
@@ -2117,7 +2445,7 @@ async function lighthouseAudit(args) {
     if (res.signal === "SIGKILL") {
       throw new CdpError(`lighthouse_audit timed out after ${timeoutMs}ms (no report written). stderr: ${truncate(res.stderr)}`);
     }
-    const hint = /not found|could not determine executable|npm ERR|E404|ERR_MODULE/i.test(res.stderr) ? " The Lighthouse CLI could not be fetched/installed via npx — ensure network access and that 'lighthouse' is installable." : "";
+    const hint = /not found|could not determine executable|npm ERR|E404|ERR_MODULE/i.test(res.stderr) ? " The Lighthouse CLI could not be fetched/installed via npx; ensure network access and that 'lighthouse' is installable." : "";
     throw new CdpError(`lighthouse_audit produced no report (exit code ${res.code}).${hint} stderr: ${truncate(res.stderr)}`);
   }
   let report;
@@ -2191,7 +2519,10 @@ var TOOLS = {
   lighthouse_audit: lighthouseAudit,
   mock_request: mockRequest,
   list_mocks: listMocks,
-  clear_mocks: clearMocks
+  clear_mocks: clearMocks,
+  claim_page: onCdp(LEASE_TOOLS.claim_page),
+  release_page: onCdp(LEASE_TOOLS.release_page),
+  list_leases: onCdp(LEASE_TOOLS.list_leases)
 };
 var TOOL_NAMES = Object.keys(TOOLS);
 
@@ -2950,12 +3281,17 @@ async function safeTitle(conn, contextId) {
 async function pageInfoOf(conn, ctx) {
   return { id: ctx.context, url: ctx.url, title: await safeTitle(conn, ctx.context) };
 }
-async function resolveContext(conn, selector) {
+async function resolveContext(conn, selector, opts = {}) {
   const { contexts } = await conn.send("browsingContext.getTree", {}).catch((e) => {
     throw mapBidiError(e);
   });
   if (!contexts.length)
     throw driverError2("no-such-target", "no browsing contexts available");
+  const hit = await pickContext(conn, contexts, selector);
+  await assertLeaseOk("firefox", hit.context, { lease: opts.lease, url: hit.url });
+  return hit;
+}
+async function pickContext(conn, contexts, selector) {
   if (selector === undefined || selector === "active")
     return contexts[0];
   if (selector.startsWith("index:")) {
@@ -3476,7 +3812,7 @@ import { spawn as spawn2 } from "node:child_process";
 import { mkdtempSync, rmSync } from "node:fs";
 import { createConnection, createServer } from "node:net";
 import { tmpdir } from "node:os";
-import { join as join4 } from "node:path";
+import { join as join5 } from "node:path";
 function resolveBinary() {
   const candidates = [
     process.env.FIREFOX_BIN,
@@ -3550,7 +3886,7 @@ async function launchFirefox(opts = {}) {
   const binary = resolveBinary();
   const port = await pickPort(opts.port);
   const isThrowaway = opts.profilePath === undefined;
-  const profilePath = opts.profilePath ?? mkdtempSync(join4(tmpdir(), "cdp-toolkit-ff-profile-"));
+  const profilePath = opts.profilePath ?? mkdtempSync(join5(tmpdir(), "cdp-toolkit-ff-profile-"));
   const args = ["--profile", profilePath, "--remote-debugging-port", String(port), "--no-remote"];
   if (opts.headless)
     args.push("--headless");
@@ -3815,7 +4151,8 @@ var BIDI_ONLY_TOOLS = {
 // src/firefox-tools.ts
 var FIREFOX_TOOLS = {
   ...SHARED_TOOLS,
-  ...BIDI_ONLY_TOOLS
+  ...BIDI_ONLY_TOOLS,
+  ...LEASE_TOOLS
 };
 
 // src/cli.ts
@@ -3840,6 +4177,8 @@ zero behavior change for existing users). Firefox is LAUNCHED per invocation (it
 to), used for exactly one tool call, then disposed before the process exits.
 
 Target selector grammar: active | index:N | url:<substr> | title:<substr> | <targetId>
+Leases: pass --lease <token> to act on a tab another agent claimed with claim_page (MCP only).
+Run list_leases to see who holds what; release_page --lease <token> gives a lease back.
 Run with --list to print every tool name available under the selected backend.
 Run with --capabilities to see, per tool, whether it is available and (if not) which capability
 the selected backend is missing.`;
@@ -3943,28 +4282,38 @@ async function main() {
 `);
     return 1;
   }
-  if (browser === "chrome") {
-    const fn = TOOLS[parsed.tool];
-    const result = await fn(parsed.args);
-    process.stdout.write(`${JSON.stringify(result, null, 2)}
-`);
-    return 0;
-  }
-  const neutralFn = FIREFOX_TOOLS[parsed.tool];
-  if (!neutralFn) {
-    process.stderr.write(`${JSON.stringify({ error: `tool '${parsed.tool}' has no Firefox implementation wired` })}
+  if (parsed.tool === "claim_page") {
+    process.stderr.write(`${JSON.stringify({
+      error: "claim_page is not available from the CLI: a CLI invocation is one process per call, so the lease it claimed would be reclaimable immediately by the dead-pid rule. Claim from the cdp-toolkit MCP server, which is long lived, then pass the token to CLI calls with --lease <token>."
+    })}
 `);
     return 1;
   }
-  const session = await startFirefoxSession();
-  try {
-    const result = await neutralFn(session.driver, parsed.args);
-    process.stdout.write(`${JSON.stringify(result, null, 2)}
+  const tool = parsed.tool;
+  return withLeaseScope(leaseFromArgs(parsed.args), async () => {
+    if (browser === "chrome") {
+      const fn = TOOLS[tool];
+      const result = await fn(parsed.args);
+      process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);
-    return 0;
-  } finally {
-    await session.dispose();
-  }
+      return 0;
+    }
+    const neutralFn = FIREFOX_TOOLS[tool];
+    if (!neutralFn) {
+      process.stderr.write(`${JSON.stringify({ error: `tool '${tool}' has no Firefox implementation wired` })}
+`);
+      return 1;
+    }
+    const session = await startFirefoxSession();
+    try {
+      const result = await neutralFn(session.driver, parsed.args);
+      process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+      return 0;
+    } finally {
+      await session.dispose();
+    }
+  });
 }
 main().then((code) => process.exit(code)).catch((err) => {
   const message = err instanceof Error ? err.message : String(err);