cdp-toolkit 1.4.0 → 1.7.0

package/src/reap.ts

@@ -0,0 +1,114 @@
+/**
+ * Closing tabs whose agent died, without a background sweeper.
+ *
+ * WHY REAP AT ALL. release_page closes a tab an agent gives back, but an agent
+ * that crashes, is killed, or simply stops calling never gives anything back.
+ * Its tab stays open forever with a lease file nobody will ever release. That
+ * is the failure this module exists for, and it is the common one: a timeout is
+ * a more likely end to an agent than a clean shutdown.
+ *
+ * WHY REAP-ON-READ AND NOT A SWEEPER. Same reasoning as origins.ts's ledger: a
+ * background sweeper is a second lifetime to reason about and a process that
+ * has to be running. list_pages and list_leases already hold the browser's
+ * target list and the lease directory at the moment they run, so doing it there
+ * costs one extra pass over data already in hand and needs nothing scheduled.
+ *
+ * WHY THE SELECTION IS A PURE FUNCTION. Every mistake in this module closes a
+ * tab someone wanted. A pure selector over plain data is testable across the
+ * whole matrix of {provenance} x {lease state} x {liveness} with no browser and
+ * no filesystem, which is the only way to be confident about a destructive
+ * operation. The impure wrapper below does nothing but call it and act.
+ */
+import type { BrowserDriver } from "./driver.ts";
+import { listLeases, releaseLeaseFor, type LeaseBackend, type LeaseSummary } from "./leases.ts";
+import { originIndex, type OriginSummary } from "./origins.ts";
+
+export interface ReapedTab {
+  targetId: string;
+  label: string;
+  /** Why it was reaped. Deliberately narrower than LeaseStaleReason: see below. */
+  reason: "dead-pid" | "expired";
+}
+
+export interface ReapInput {
+  backend: LeaseBackend;
+  /**
+   * Ids from the PAGE-ONLY listing, never from an `all:true` listing. A worker,
+   * iframe or background page can carry a lease (pickPage's bare-id branch
+   * resolves non-page targets), and "close the stale tab" is meaningless for
+   * one. This is a different set from the one shared-tools' reapSet feeds to the
+   * origin ledger, which deliberately uses the unfiltered listing so a live but
+   * filtered-out target does not lose its provenance record. Two reaps, two
+   * questions, two id sets: do not merge them.
+   */
+  livePageIds: readonly string[];
+  origins: ReadonlyMap<string, OriginSummary>;
+  leases: readonly LeaseSummary[];
+}
+
+/**
+ * Select the tabs that may be closed. PURE: no I/O, no driver, no clock.
+ *
+ * All four conditions must hold, and condition 4 is the load-bearing one:
+ *
+ *  1. the lease row is for this backend and READABLE. An `unreadable` row is
+ *     never reaped for the same reason listLeases reports it as stale:false -
+ *     we cannot see who owns it, and a guess in the destructive direction is
+ *     the one guess that cannot be undone.
+ *  2. it is stale for `dead-pid` or `expired`. NOT `target-gone`, which means
+ *     the tab is already closed and there is nothing to do, and obviously not
+ *     `false`.
+ *  3. the target is actually still open, per livePageIds.
+ *  4. the toolkit OPENED it. An agent-created tab with NO lease is deliberately
+ *     never reaped: that is exactly what new_page produces for a user who never
+ *     touches leases, and closing those would be a data-loss bug rather than a
+ *     cleanup. Only a tab that was claimed and then abandoned qualifies.
+ */
+export function staleAgentTabs(input: ReapInput): ReapedTab[] {
+  const live = new Set(input.livePageIds);
+  const out: ReapedTab[] = [];
+  for (const row of input.leases) {
+    if (row.backend !== input.backend) continue;
+    if (row.unreadable !== undefined) continue;
+    if (row.stale !== "dead-pid" && row.stale !== "expired") continue;
+    if (!live.has(row.targetId)) continue;
+    const origin = input.origins.get(row.targetId);
+    if (origin === undefined || origin.unreadable !== undefined) continue;
+    out.push({ targetId: row.targetId, label: row.label, reason: row.stale });
+  }
+  return out;
+}
+
+/**
+ * Select, close, and drop the leases. Returns ONLY the tabs actually closed.
+ *
+ * A close that fails is not reported, and that asymmetry is deliberate: the
+ * caller filters its listing by this array, so reporting a tab we failed to
+ * close would hide a tab that is still open. Failing quietly leaves the tab
+ * visible and the lease in place, and the next read tries again.
+ *
+ * The lease file is unlinked; the ORIGIN record is not. listOrigins already
+ * reaps records for targets the browser no longer has, so the record disappears
+ * on the next listing. One lifetime rule for origin records, not three.
+ */
+export async function reapStaleAgentTabs(driver: BrowserDriver, backend: LeaseBackend): Promise<ReapedTab[]> {
+  // The PAGE-ONLY listing: see ReapInput.livePageIds.
+  const livePageIds = (await driver.listPages()).map((p) => p.id);
+  const [origins, leases] = await Promise.all([
+    // undefined liveIds = reap nothing from the ledger here. Reaping origin
+    // records is list_pages' job and it uses a DIFFERENT id set (the unfiltered
+    // listing); doing it here too would delete records for targets that are
+    // live but filtered out of the page-only view.
+    originIndex(backend, undefined),
+    listLeases({ liveIds: livePageIds, liveBackend: backend }).catch(() => [] as LeaseSummary[]),
+  ]);
+  const candidates = staleAgentTabs({ backend, livePageIds, origins, leases });
+  const closed: ReapedTab[] = [];
+  for (const c of candidates) {
+    const res = await driver.closePage(c.targetId).catch(() => ({ success: false }));
+    if (res.success !== true) continue;
+    await releaseLeaseFor(backend, c.targetId);
+    closed.push(c);
+  }
+  return closed;
+}

package/src/shared-tools.ts

@@ -3,7 +3,8 @@
  * (ADR-001), used by BOTH Chrome (via cdp/driver.ts's createCdpDriver()) and Firefox (via
  * bidi/driver.ts's createFirefoxDriver()). This file replaces the split that used to exist
  * between src/tools/*.ts (raw CDP, Chrome only) and src/neutral.ts (Driver-based, Firefox only)
- * for the 20 tools below.
+ * for 20 of the 23 tools below. The other three, the list_cookies/set_cookie/delete_cookies
+ * cookie group, landed here directly and never had a Chrome-only copy.
  *
  * THE HARD REQUIREMENT this file exists to satisfy: Chrome's return shape, timing, and quirks
  * stay byte-identical to what src/tools/*.ts produced before this migration: that already
@@ -38,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";
@@ -69,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
@@ -92,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]!;
@@ -175,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.
@@ -187,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(
@@ -198,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 };
 }