cdp-toolkit 1.6.0 → 1.7.0

package/dist/cli.js

@@ -13,6 +13,16 @@ function leaseTtlMs() {
   const raw = Number(process.env.CDP_LEASE_TTL_MS);
   return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_LEASE_TTL_MS;
 }
+var longLived = false;
+function markLongLivedProcess(value = true) {
+  longLived = value;
+}
+function requireLease() {
+  if (!longLived)
+    return false;
+  const raw = (process.env.CDP_REQUIRE_LEASE ?? "").trim().toLowerCase();
+  return raw === "1" || raw === "true" || raw === "yes" || raw === "on";
+}
 function defaultLabel() {
   return `pid-${process.pid}`;
 }
@@ -99,7 +109,8 @@ async function claimLease(backend, targetId, opts) {
       label: opts.label,
       createdAt: now,
       lastUsedAt: now,
-      ttlMs: opts.ttlMs ?? leaseTtlMs()
+      ttlMs: opts.ttlMs ?? leaseTtlMs(),
+      auto: opts.auto === true
     };
     try {
       await writeFile(leaseFile(backend, targetId), JSON.stringify(record), { flag: "wx" });
@@ -175,8 +186,16 @@ async function assertLeaseOk(backend, targetId, ctx = {}) {
   const held = rec && !staleReason(rec, { now, liveIds: ctx.liveIds }) ? rec : undefined;
   const where = describeTarget(targetId, ctx);
   if (token === undefined) {
-    if (!held)
+    if (!held) {
+      if (requireLease()) {
+        await claimLease(backend, targetId, { label: defaultLabel(), ttlMs: leaseTtlMs(), auto: true, now });
+      }
       return;
+    }
+    if (held.auto === true && held.pid === process.pid) {
+      await touchLease(held, now);
+      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);
@@ -184,8 +203,12 @@ async function assertLeaseOk(backend, targetId, ctx = {}) {
     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)
+    if (!held) {
+      if (requireLease()) {
+        await claimLease(backend, targetId, { label: defaultLabel(), ttlMs: leaseTtlMs(), auto: true, now });
+      }
       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) {
@@ -1429,6 +1452,20 @@ async function recordOrigin(backend, targetId, opts = {}) {
     await writeFile2(file, JSON.stringify(record), { flag: "wx" });
   } catch {}
 }
+async function readOrigin(backend, targetId) {
+  let raw;
+  try {
+    raw = await readFile2(originFile(backend, targetId), "utf8");
+  } catch {
+    return;
+  }
+  try {
+    const rec = JSON.parse(raw);
+    if (typeof rec?.targetId === "string" && typeof rec?.label === "string" && typeof rec?.createdAt === "number")
+      return rec;
+  } catch {}
+  return;
+}
 async function listOrigins(opts = {}) {
   let names = [];
   try {
@@ -1486,59 +1523,43 @@ async function newTrackedPage(driver, backend, opts = {}) {
   return page;
 }
 
-// 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 : defaultLabel();
-  const pages = await driver.listPages();
-  let targetId = args.targetId;
-  let url = args.url ?? "about:blank";
-  if (targetId === undefined || targetId === "") {
-    const page = await newTrackedPage(driver, backend, { url: args.url, label });
-    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;
+// src/reap.ts
+function staleAgentTabs(input) {
+  const live = new Set(input.livePageIds);
+  const out = [];
+  for (const row of input.leases) {
+    if (row.backend !== input.backend)
+      continue;
+    if (row.unreadable !== undefined)
+      continue;
+    if (row.stale !== "dead-pid" && row.stale !== "expired")
+      continue;
+    if (!live.has(row.targetId))
+      continue;
+    const origin = input.origins.get(row.targetId);
+    if (origin === undefined || origin.unreadable !== undefined)
+      continue;
+    out.push({ targetId: row.targetId, label: row.label, reason: row.stale });
   }
-  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
-  };
+  return out;
 }
-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");
+async function reapStaleAgentTabs(driver, backend) {
+  const livePageIds = (await driver.listPages()).map((p) => p.id);
+  const [origins, leases] = await Promise.all([
+    originIndex(backend, undefined),
+    listLeases({ liveIds: livePageIds, liveBackend: backend }).catch(() => [])
+  ]);
+  const candidates = staleAgentTabs({ backend, livePageIds, origins, leases });
+  const closed = [];
+  for (const c of candidates) {
+    const res = await driver.closePage(c.targetId).catch(() => ({ success: false }));
+    if (res.success !== true)
+      continue;
+    await releaseLeaseFor(backend, c.targetId);
+    closed.push(c);
   }
-  return releaseLease(args.lease);
+  return closed;
 }
-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 as mkdir3, writeFile as writeFile3 } from "node:fs/promises";
@@ -1551,7 +1572,7 @@ class SharedToolError extends Error {
 function target3(p) {
   return { id: p.id, url: p.url, title: p.title };
 }
-function backendOf2(driver) {
+function backendOf(driver) {
   return driver.scheme === "bidi" ? "firefox" : "chrome";
 }
 async function withPage2(driver, target, fn) {
@@ -1565,7 +1586,7 @@ 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 });
+  await assertLeaseOk(backendOf(driver), hit.id, { url: hit.url, title: hit.title });
   return hit;
 }
 async function pickPage(driver, pages, selector) {
@@ -1620,8 +1641,10 @@ async function reapSet(driver, pages, all) {
   }
 }
 async function listPages(driver, args = {}) {
-  const pages = await driver.listPages({ all: args.all });
-  const ledger = await originIndex(backendOf2(driver), await reapSet(driver, pages, args.all));
+  const reaped = requireLease() ? await reapStaleAgentTabs(driver, backendOf(driver)) : [];
+  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 rec = ledger.get(p.id);
     if (!rec)
@@ -1630,16 +1653,18 @@ async function listPages(driver, args = {}) {
       return { ...p, origin: "unknown", originUnreadable: rec.unreadable };
     return { ...p, origin: "agent", label: rec.label, createdAt: rec.createdAt };
   });
-  return { pages: annotated, count: annotated.length };
+  return { pages: annotated, count: annotated.length, ...reaped.length ? { reaped } : {} };
 }
 async function newPage(driver, args = {}) {
   const label = typeof args.label === "string" && args.label.length ? args.label : defaultLabel();
-  const p = await newTrackedPage(driver, backendOf2(driver), { url: args.url, label });
-  if (args.claim !== true)
+  const p = await newTrackedPage(driver, backendOf(driver), { url: args.url, label });
+  const explicit = args.claim === true;
+  if (!explicit && !requireLease())
     return { targetId: p.id, url: p.url };
-  const { record, token } = await claimLease(backendOf2(driver), p.id, {
+  const { record, token } = await claimLease(backendOf(driver), p.id, {
     label,
-    ttlMs: typeof args.ttlMs === "number" && args.ttlMs > 0 ? args.ttlMs : leaseTtlMs()
+    ttlMs: typeof args.ttlMs === "number" && args.ttlMs > 0 ? args.ttlMs : leaseTtlMs(),
+    auto: !explicit
   });
   return { targetId: p.id, url: p.url, lease: token, label: record.label, expiresAt: record.lastUsedAt + record.ttlMs };
 }
@@ -1650,7 +1675,7 @@ async function closePage(driver, args) {
   const res = await driver.closePage(p.id);
   if (!res.success)
     return { closed: p.id, success: false, leaseReleased: false };
-  const released = await releaseLeaseFor(backendOf2(driver), p.id);
+  const released = await releaseLeaseFor(backendOf(driver), p.id);
   return { closed: p.id, success: true, ...released.released ? { leaseReleased: true } : {} };
 }
 async function writeSelectedFile(id) {
@@ -1975,6 +2000,103 @@ var SHARED_TOOLS = {
   handle_dialog: handleDialog
 };
 
+// src/leases-tools.ts
+class LeaseToolError extends Error {
+}
+function backendOf2(driver) {
+  return driver.scheme === "bidi" ? "firefox" : "chrome";
+}
+async function claimPage(driver, args = {}) {
+  const hasTarget = typeof args.target === "string" && args.target.length > 0;
+  const hasTargetId = typeof args.targetId === "string" && args.targetId.length > 0;
+  if (hasTarget && hasTargetId) {
+    throw new LeaseToolError("claim_page takes at most one of 'target' (any selector: active | index:N | url:<substr> | title:<substr> | <targetId>) or 'targetId' (an exact target id, kept for back-compat). Pass 'target' alone to claim an open tab, or neither to open a fresh one.");
+  }
+  const backend = backendOf2(driver);
+  const label = typeof args.label === "string" && args.label.length ? args.label : defaultLabel();
+  const pages = await driver.listPages();
+  let targetId;
+  let url;
+  let opened;
+  if (hasTarget) {
+    const hit = await pickPage(driver, pages, args.target).catch((err) => {
+      throw new LeaseToolError(`claim_page: no open tab matches target '${args.target}' (${err.message}). No tab was opened: claim_page never creates one when 'target' is given.`);
+    });
+    targetId = hit.id;
+    url = hit.url;
+    opened = false;
+  } else if (hasTargetId) {
+    const existing = pages.find((p) => p.id === args.targetId);
+    if (!existing)
+      throw new LeaseToolError(`claim_page: no page target with id '${args.targetId}'`);
+    targetId = existing.id;
+    url = existing.url;
+    opened = false;
+  } else {
+    const page = await newTrackedPage(driver, backend, { url: args.url, label });
+    targetId = page.id;
+    url = page.url;
+    opened = true;
+  }
+  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,
+    opened
+  };
+}
+async function releasePage(driver, args = {}) {
+  const hasLease = typeof args.lease === "string" && args.lease.length > 0;
+  const hasTarget = typeof args.target === "string" && args.target.length > 0;
+  if (hasLease === hasTarget) {
+    throw new LeaseToolError("release_page takes exactly one of 'lease' (the token claim_page returned) or 'target' (a selector for a tab this process holds)");
+  }
+  const backend = backendOf2(driver);
+  let targetId;
+  let released;
+  if (hasLease) {
+    const parts = tokenParts(args.lease);
+    if (!parts)
+      return { released: false, closed: false };
+    targetId = parts.targetId;
+    released = (await releaseLease(args.lease)).released;
+  } else {
+    const page = await resolvePage(driver, args.target);
+    targetId = page.id;
+    released = (await releaseLeaseFor(backend, targetId)).released;
+  }
+  if (!released)
+    return { released: false, closed: false, ...hasTarget ? { targetId } : {} };
+  const shouldClose = args.close === false ? false : args.close === true ? true : await readOrigin(backend, targetId) !== undefined;
+  if (!shouldClose)
+    return { released: true, closed: false, targetId };
+  const res = await driver.closePage(targetId).catch(() => ({ success: false }));
+  return { released: true, closed: res.success === true, targetId };
+}
+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 all = await listLeases({ liveIds, liveBackend: backend });
+  const leases = all.filter((l) => !(l.backend === backend && reapedIds.has(l.targetId)));
+  return { leases, count: leases.length, ...reaped.length ? { reaped } : {} };
+}
+var LEASE_TOOLS = {
+  claim_page: claimPage,
+  release_page: releasePage,
+  list_leases: listLeasesTool
+};
+
 // src/tools/console.ts
 import { readFile as readFile3 } from "node:fs/promises";
 

package/dist/index.js

@@ -11,6 +11,16 @@ function leaseTtlMs() {
   const raw = Number(process.env.CDP_LEASE_TTL_MS);
   return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_LEASE_TTL_MS;
 }
+var longLived = false;
+function markLongLivedProcess(value = true) {
+  longLived = value;
+}
+function requireLease() {
+  if (!longLived)
+    return false;
+  const raw = (process.env.CDP_REQUIRE_LEASE ?? "").trim().toLowerCase();
+  return raw === "1" || raw === "true" || raw === "yes" || raw === "on";
+}
 function defaultLabel() {
   return `pid-${process.pid}`;
 }
@@ -97,7 +107,8 @@ async function claimLease(backend, targetId, opts) {
       label: opts.label,
       createdAt: now,
       lastUsedAt: now,
-      ttlMs: opts.ttlMs ?? leaseTtlMs()
+      ttlMs: opts.ttlMs ?? leaseTtlMs(),
+      auto: opts.auto === true
     };
     try {
       await writeFile(leaseFile(backend, targetId), JSON.stringify(record), { flag: "wx" });
@@ -173,8 +184,16 @@ async function assertLeaseOk(backend, targetId, ctx = {}) {
   const held = rec && !staleReason(rec, { now, liveIds: ctx.liveIds }) ? rec : undefined;
   const where = describeTarget(targetId, ctx);
   if (token === undefined) {
-    if (!held)
+    if (!held) {
+      if (requireLease()) {
+        await claimLease(backend, targetId, { label: defaultLabel(), ttlMs: leaseTtlMs(), auto: true, now });
+      }
       return;
+    }
+    if (held.auto === true && held.pid === process.pid) {
+      await touchLease(held, now);
+      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);
@@ -182,8 +201,12 @@ async function assertLeaseOk(backend, targetId, ctx = {}) {
     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)
+    if (!held) {
+      if (requireLease()) {
+        await claimLease(backend, targetId, { label: defaultLabel(), ttlMs: leaseTtlMs(), auto: true, now });
+      }
       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) {
@@ -1427,6 +1450,20 @@ async function recordOrigin(backend, targetId, opts = {}) {
     await writeFile2(file, JSON.stringify(record), { flag: "wx" });
   } catch {}
 }
+async function readOrigin(backend, targetId) {
+  let raw;
+  try {
+    raw = await readFile2(originFile(backend, targetId), "utf8");
+  } catch {
+    return;
+  }
+  try {
+    const rec = JSON.parse(raw);
+    if (typeof rec?.targetId === "string" && typeof rec?.label === "string" && typeof rec?.createdAt === "number")
+      return rec;
+  } catch {}
+  return;
+}
 async function listOrigins(opts = {}) {
   let names = [];
   try {
@@ -1484,59 +1521,43 @@ async function newTrackedPage(driver, backend, opts = {}) {
   return page;
 }
 
-// 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 : defaultLabel();
-  const pages = await driver.listPages();
-  let targetId = args.targetId;
-  let url = args.url ?? "about:blank";
-  if (targetId === undefined || targetId === "") {
-    const page = await newTrackedPage(driver, backend, { url: args.url, label });
-    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;
+// src/reap.ts
+function staleAgentTabs(input) {
+  const live = new Set(input.livePageIds);
+  const out = [];
+  for (const row of input.leases) {
+    if (row.backend !== input.backend)
+      continue;
+    if (row.unreadable !== undefined)
+      continue;
+    if (row.stale !== "dead-pid" && row.stale !== "expired")
+      continue;
+    if (!live.has(row.targetId))
+      continue;
+    const origin = input.origins.get(row.targetId);
+    if (origin === undefined || origin.unreadable !== undefined)
+      continue;
+    out.push({ targetId: row.targetId, label: row.label, reason: row.stale });
   }
-  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
-  };
+  return out;
 }
-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");
+async function reapStaleAgentTabs(driver, backend) {
+  const livePageIds = (await driver.listPages()).map((p) => p.id);
+  const [origins, leases] = await Promise.all([
+    originIndex(backend, undefined),
+    listLeases({ liveIds: livePageIds, liveBackend: backend }).catch(() => [])
+  ]);
+  const candidates = staleAgentTabs({ backend, livePageIds, origins, leases });
+  const closed = [];
+  for (const c of candidates) {
+    const res = await driver.closePage(c.targetId).catch(() => ({ success: false }));
+    if (res.success !== true)
+      continue;
+    await releaseLeaseFor(backend, c.targetId);
+    closed.push(c);
   }
-  return releaseLease(args.lease);
+  return closed;
 }
-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 as mkdir3, writeFile as writeFile3 } from "node:fs/promises";
@@ -1549,7 +1570,7 @@ class SharedToolError extends Error {
 function target3(p) {
   return { id: p.id, url: p.url, title: p.title };
 }
-function backendOf2(driver) {
+function backendOf(driver) {
   return driver.scheme === "bidi" ? "firefox" : "chrome";
 }
 async function withPage2(driver, target, fn) {
@@ -1563,7 +1584,7 @@ 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 });
+  await assertLeaseOk(backendOf(driver), hit.id, { url: hit.url, title: hit.title });
   return hit;
 }
 async function pickPage(driver, pages, selector) {
@@ -1618,8 +1639,10 @@ async function reapSet(driver, pages, all) {
   }
 }
 async function listPages(driver, args = {}) {
-  const pages = await driver.listPages({ all: args.all });
-  const ledger = await originIndex(backendOf2(driver), await reapSet(driver, pages, args.all));
+  const reaped = requireLease() ? await reapStaleAgentTabs(driver, backendOf(driver)) : [];
+  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 rec = ledger.get(p.id);
     if (!rec)
@@ -1628,16 +1651,18 @@ async function listPages(driver, args = {}) {
       return { ...p, origin: "unknown", originUnreadable: rec.unreadable };
     return { ...p, origin: "agent", label: rec.label, createdAt: rec.createdAt };
   });
-  return { pages: annotated, count: annotated.length };
+  return { pages: annotated, count: annotated.length, ...reaped.length ? { reaped } : {} };
 }
 async function newPage(driver, args = {}) {
   const label = typeof args.label === "string" && args.label.length ? args.label : defaultLabel();
-  const p = await newTrackedPage(driver, backendOf2(driver), { url: args.url, label });
-  if (args.claim !== true)
+  const p = await newTrackedPage(driver, backendOf(driver), { url: args.url, label });
+  const explicit = args.claim === true;
+  if (!explicit && !requireLease())
     return { targetId: p.id, url: p.url };
-  const { record, token } = await claimLease(backendOf2(driver), p.id, {
+  const { record, token } = await claimLease(backendOf(driver), p.id, {
     label,
-    ttlMs: typeof args.ttlMs === "number" && args.ttlMs > 0 ? args.ttlMs : leaseTtlMs()
+    ttlMs: typeof args.ttlMs === "number" && args.ttlMs > 0 ? args.ttlMs : leaseTtlMs(),
+    auto: !explicit
   });
   return { targetId: p.id, url: p.url, lease: token, label: record.label, expiresAt: record.lastUsedAt + record.ttlMs };
 }
@@ -1648,7 +1673,7 @@ async function closePage(driver, args) {
   const res = await driver.closePage(p.id);
   if (!res.success)
     return { closed: p.id, success: false, leaseReleased: false };
-  const released = await releaseLeaseFor(backendOf2(driver), p.id);
+  const released = await releaseLeaseFor(backendOf(driver), p.id);
   return { closed: p.id, success: true, ...released.released ? { leaseReleased: true } : {} };
 }
 async function writeSelectedFile(id) {
@@ -1973,6 +1998,103 @@ var SHARED_TOOLS = {
   handle_dialog: handleDialog
 };
 
+// src/leases-tools.ts
+class LeaseToolError extends Error {
+}
+function backendOf2(driver) {
+  return driver.scheme === "bidi" ? "firefox" : "chrome";
+}
+async function claimPage(driver, args = {}) {
+  const hasTarget = typeof args.target === "string" && args.target.length > 0;
+  const hasTargetId = typeof args.targetId === "string" && args.targetId.length > 0;
+  if (hasTarget && hasTargetId) {
+    throw new LeaseToolError("claim_page takes at most one of 'target' (any selector: active | index:N | url:<substr> | title:<substr> | <targetId>) or 'targetId' (an exact target id, kept for back-compat). Pass 'target' alone to claim an open tab, or neither to open a fresh one.");
+  }
+  const backend = backendOf2(driver);
+  const label = typeof args.label === "string" && args.label.length ? args.label : defaultLabel();
+  const pages = await driver.listPages();
+  let targetId;
+  let url;
+  let opened;
+  if (hasTarget) {
+    const hit = await pickPage(driver, pages, args.target).catch((err) => {
+      throw new LeaseToolError(`claim_page: no open tab matches target '${args.target}' (${err.message}). No tab was opened: claim_page never creates one when 'target' is given.`);
+    });
+    targetId = hit.id;
+    url = hit.url;
+    opened = false;
+  } else if (hasTargetId) {
+    const existing = pages.find((p) => p.id === args.targetId);
+    if (!existing)
+      throw new LeaseToolError(`claim_page: no page target with id '${args.targetId}'`);
+    targetId = existing.id;
+    url = existing.url;
+    opened = false;
+  } else {
+    const page = await newTrackedPage(driver, backend, { url: args.url, label });
+    targetId = page.id;
+    url = page.url;
+    opened = true;
+  }
+  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,
+    opened
+  };
+}
+async function releasePage(driver, args = {}) {
+  const hasLease = typeof args.lease === "string" && args.lease.length > 0;
+  const hasTarget = typeof args.target === "string" && args.target.length > 0;
+  if (hasLease === hasTarget) {
+    throw new LeaseToolError("release_page takes exactly one of 'lease' (the token claim_page returned) or 'target' (a selector for a tab this process holds)");
+  }
+  const backend = backendOf2(driver);
+  let targetId;
+  let released;
+  if (hasLease) {
+    const parts = tokenParts(args.lease);
+    if (!parts)
+      return { released: false, closed: false };
+    targetId = parts.targetId;
+    released = (await releaseLease(args.lease)).released;
+  } else {
+    const page = await resolvePage(driver, args.target);
+    targetId = page.id;
+    released = (await releaseLeaseFor(backend, targetId)).released;
+  }
+  if (!released)
+    return { released: false, closed: false, ...hasTarget ? { targetId } : {} };
+  const shouldClose = args.close === false ? false : args.close === true ? true : await readOrigin(backend, targetId) !== undefined;
+  if (!shouldClose)
+    return { released: true, closed: false, targetId };
+  const res = await driver.closePage(targetId).catch(() => ({ success: false }));
+  return { released: true, closed: res.success === true, targetId };
+}
+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 all = await listLeases({ liveIds, liveBackend: backend });
+  const leases = all.filter((l) => !(l.backend === backend && reapedIds.has(l.targetId)));
+  return { leases, count: leases.length, ...reaped.length ? { reaped } : {} };
+}
+var LEASE_TOOLS = {
+  claim_page: claimPage,
+  release_page: releasePage,
+  list_leases: listLeasesTool
+};
+
 // src/tools/console.ts
 import { readFile as readFile3 } from "node:fs/promises";