cdp-toolkit 1.6.0 → 1.7.0

package/src/shared-tools.ts

@@ -39,8 +39,9 @@ import type {
   BrowserCookie, BrowserDriver, DriverUid, ElementLocator, NavigateResult, PageDriver, PageInfo, SnapshotNode,
 } from "./driver.ts";
 import type { TargetSelector } from "./types.ts";
-import { assertLeaseOk, claimLease, defaultLabel, leaseTtlMs, releaseLeaseFor, type LeaseBackend, type LeaseToken } from "./leases.ts";
+import { assertLeaseOk, claimLease, defaultLabel, leaseTtlMs, releaseLeaseFor, requireLease, type LeaseBackend, type LeaseToken } from "./leases.ts";
 import { newTrackedPage, originIndex, type PageOrigin } from "./origins.ts";
+import { reapStaleAgentTabs, type ReapedTab } from "./reap.ts";
 
 const ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 const STATE_DIR = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
@@ -70,7 +71,9 @@ async function withPage<T>(driver: BrowserDriver, target: TargetSelector | undef
   }
 }
 
-async function resolvePage(driver: BrowserDriver, selector?: TargetSelector): Promise<PageInfo> {
+/** Exported for leases-tools.ts's release_page{target}, which needs exactly this
+ *  gate: resolving through here is what authorizes the release. */
+export async function resolvePage(driver: BrowserDriver, selector?: TargetSelector): Promise<PageInfo> {
   const pages = await driver.listPages();
   const hit = await pickPage(driver, pages, selector);
   // THE third choke point. close_page and select_page resolve here and nowhere
@@ -93,8 +96,17 @@ async function resolvePage(driver: BrowserDriver, selector?: TargetSelector): Pr
  * every branch resolves against page-type targets only EXCEPT a bare-id lookup, which (like
  * legacy resolveTarget's `targets.find`) searches the FULL unfiltered listing, so passing an
  * exact non-page targetId (a worker, an iframe) still resolves.
+ *
+ * THE GATE-FREE HALF of resolvePage, and exported for the one caller that needs
+ * resolution WITHOUT authorization: claim_page{target}. Everything else must go
+ * through resolvePage. Claiming cannot run assertLeaseOk, because under
+ * CDP_REQUIRE_LEASE the gate AUTO-ACQUIRES a lease on an unleased tab, so a
+ * claim routed through it would take the tab twice — once implicitly with an
+ * auto lease, then again explicitly, and the second claim would collide with
+ * the first. Refusing a tab another process holds is still enforced, one layer
+ * down, by claimLease's own conflict check.
  */
-async function pickPage(driver: BrowserDriver, pages: PageInfo[], selector?: TargetSelector): Promise<PageInfo> {
+export async function pickPage(driver: BrowserDriver, pages: PageInfo[], selector?: TargetSelector): Promise<PageInfo> {
   if (selector === undefined || selector === "active") {
     if (!pages.length) throw new SharedToolError("no page targets open");
     return pages[0]!;
@@ -176,8 +188,15 @@ async function reapSet(driver: BrowserDriver, pages: PageInfo[], all?: boolean):
   }
 }
 
-export async function listPages(driver: BrowserDriver, args: { all?: boolean } = {}): Promise<{ pages: ListedPage[]; count: number }> {
-  const pages = await driver.listPages({ all: args.all });
+export async function listPages(
+  driver: BrowserDriver,
+  args: { all?: boolean } = {},
+): Promise<{ pages: ListedPage[]; count: number; reaped?: ReapedTab[] }> {
+  // Reap FIRST, so a tab this call is about to close never appears in the
+  // listing it returns. Under strict mode only: see requireLease.
+  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));
   // Never let provenance break the listing: originIndex does not throw, and a
   // missing or unreadable ledger yields an empty map, so every page falls back
   // to origin "unknown" exactly as a pre-ledger consumer always saw.
@@ -188,7 +207,10 @@ export async function listPages(driver: BrowserDriver, args: { all?: boolean } =
     if (rec.unreadable !== undefined) return { ...p, origin: "unknown", originUnreadable: rec.unreadable };
     return { ...p, origin: "agent", label: rec.label, createdAt: rec.createdAt };
   });
-  return { pages: annotated, count: annotated.length };
+  // `reaped` is present only when it has something to say, so the common-case
+  // shape is byte-identical to 1.4.0. Silently closing a tab is not acceptable:
+  // if a read closed something, the read says so.
+  return { pages: annotated, count: annotated.length, ...(reaped.length ? { reaped } : {}) };
 }
 
 export async function newPage(
@@ -199,12 +221,22 @@ export async function newPage(
   // Creates the tab AND writes its creation record. The record outlives any
   // lease taken below, which is the point: a released tab is still an agent's.
   const p = await newTrackedPage(driver, backendOf(driver), { url: args.url, label });
-  if (args.claim !== true) return { targetId: p.id, url: p.url };
+  // Under strict mode a tab nobody holds is a tab nobody may drive, so creating
+  // one without claiming it would hand back a target the very next call has to
+  // auto-acquire anyway. Doing it here means the tab is never briefly unowned
+  // AND the caller is handed a token it can release with, which matters because
+  // an auto-acquired lease never returns one.
+  const explicit = args.claim === true;
+  if (!explicit && !requireLease()) return { targetId: p.id, url: p.url };
   // Atomic in the sense that matters: the tab is claimed before this call
   // returns, so no other agent can see it unclaimed and take it first.
   const { record, token } = await claimLease(backendOf(driver), p.id, {
     label,
     ttlMs: typeof args.ttlMs === "number" && args.ttlMs > 0 ? args.ttlMs : leaseTtlMs(),
+    // An explicit claim:true stays explicit under strict mode: the caller asked
+    // for the strong tier and must keep getting it, or turning strict on would
+    // silently WEAKEN every existing claim:true call site to pid-only.
+    auto: !explicit,
   });
   return { targetId: p.id, url: p.url, lease: token, label: record.label, expiresAt: record.lastUsedAt + record.ttlMs };
 }