cdp-toolkit 1.7.0 → 1.9.0

package/src/mcp.ts

@@ -19,11 +19,12 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 import { TOOLS, TOOL_NAMES, BASE } from "./index.ts";
 import { MANIFEST } from "./manifest.ts";
 import { resolveBrowserKind, stripBrowserFlag, getOrCreateFirefoxSession, disposeFirefoxSession } from "./backend.ts";
+import { disposeBrowserSession } from "./tools/browser-session.ts";
 import { toolAvailability } from "./capabilities.ts";
 import { FIREFOX_TOOLS } from "./firefox-tools.ts";
 import { leaseFromArgs, markLongLivedProcess, withLeaseScope } from "./leases.ts";
 
-const VERSION = "1.7.0";
+const VERSION = "1.9.0";
 
 // --browser is read once at startup (MCP has no per-call notion of backend): explicit flag,
 // else CDP_BROWSER env var, else "chrome" (zero behavior change for existing users/configs).
@@ -115,6 +116,10 @@ async function shutdown(): Promise<void> {
   if (shuttingDown) return;
   shuttingDown = true;
   await disposeFirefoxSession();
+  // The standing browser-endpoint connection behind wait_for_download / grant_permissions (1.8.0
+  // Track P3). Unlike Firefox it owns no OS process, so process.exit would collect it anyway; it is
+  // closed explicitly so shutdown does not depend on that, and is a no-op when neither tool ran.
+  await disposeBrowserSession();
   process.exit(0);
 }
 process.on("SIGINT", () => void shutdown());

package/src/origins.ts

@@ -32,7 +32,7 @@
 import { mkdir, readFile, readdir, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import type { BrowserDriver, PageInfo } from "./driver.ts";
-import { defaultLabel, leaseDir, type LeaseBackend } from "./leases.ts";
+import { defaultLabel, leaseDir, listLeases, type LeaseBackend } from "./leases.ts";
 
 /** What list_pages can say about where a tab came from. There is deliberately
  *  no "human": see the file header. */
@@ -264,3 +264,43 @@ export async function newTrackedPage(
   await recordOrigin(backend, page.id, { label: opts.label });
   return page;
 }
+
+/** What "label:<name>" resolution found, common to all three selector-grammar
+ *  copies (shared-tools.ts's pickPage, client.ts's pickTarget, bidi/driver.ts's
+ *  pickContext): 0, 1 or >1 live targetIds carrying the queried label, plus
+ *  every label actually in use, for a miss error that teaches something. */
+export interface LabelResolution {
+  matchIds: string[];
+  /** Deduped, sorted. Empty when no live target has any recorded label. */
+  knownLabels: string[];
+}
+
+/**
+ * The shared core of "label:<name>" resolution: exact match against BOTH the
+ * origin ledger (agent-created tabs) and live lease records (covers a
+ * taken-over tab claimed with a label, which has no origin record — see
+ * leases-tools.ts's claimPage), scoped to `liveIds` so a label whose tab is
+ * gone neither matches nor pollutes the miss list.
+ *
+ * PURE OVER ITS INPUTS BEYOND THE TWO READS: no reap, no write, no lease gate.
+ * Each of the three callers formats its own error in its own idiom
+ * (SharedToolError, CdpError, DriverError), so this returns data, never
+ * throws — a caller decides what "matches.length !== 1" means to it.
+ */
+export async function resolveLiveLabel(backend: LeaseBackend, label: string, liveIds: readonly string[]): Promise<LabelResolution> {
+  const live = new Set(liveIds);
+  const [origins, leases] = await Promise.all([originIndex(backend), listLeases({ liveBackend: backend })]);
+  const knownLabels = new Set<string>();
+  const matchIds = new Set<string>();
+  for (const rec of origins.values()) {
+    if (rec.unreadable !== undefined || !live.has(rec.targetId)) continue;
+    knownLabels.add(rec.label);
+    if (rec.label === label) matchIds.add(rec.targetId);
+  }
+  for (const rec of leases) {
+    if (rec.backend !== backend || rec.unreadable !== undefined || !live.has(rec.targetId)) continue;
+    knownLabels.add(rec.label);
+    if (rec.label === label) matchIds.add(rec.targetId);
+  }
+  return { matchIds: [...matchIds], knownLabels: [...knownLabels].sort() };
+}

package/src/reap.ts

@@ -18,6 +18,16 @@
  * 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.
+ *
+ * WHY REAPING SPLIT FROM RECLAIMABILITY (1.8.0). Before this version `expired`
+ * meant one thing everywhere: at ttlMs, both "another agent may take this
+ * lease" AND "this tab gets closed" fired at once. That is wrong for the
+ * second question and right for the first: a lease going reclaimable at ttlMs
+ * is cheap and reversible, but closing someone's tab is not, and an agent 20
+ * minutes into a build between browser calls looks identical to one that died.
+ * leases.ts's staleReason keeps deciding reclaimability at ttlMs, unchanged;
+ * this module alone additionally waits reapGraceMs past that before treating
+ * `expired` as grounds to close anything. See staleAgentTabs' condition 4.
  */
 import type { BrowserDriver } from "./driver.ts";
 import { listLeases, releaseLeaseFor, type LeaseBackend, type LeaseSummary } from "./leases.ts";
@@ -44,12 +54,19 @@ export interface ReapInput {
   livePageIds: readonly string[];
   origins: ReadonlyMap<string, OriginSummary>;
   leases: readonly LeaseSummary[];
+  /** Clock for the grace check below. Threaded in rather than read internally
+   *  (Date.now()) so this function stays pure and the whole matrix is testable
+   *  with no wall clock. */
+  now: number;
+  /** How much longer an `expired` lease survives before its tab is destroyed,
+   *  on top of the ttlMs that already made it reclaimable. See reapGraceMs(). */
+  reapGraceMs: number;
 }
 
 /**
  * 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:
+ * All conditions must hold, and condition 4 (the grace check) is new in 1.8.0:
  *
  *  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 -
@@ -59,7 +76,17 @@ export interface ReapInput {
  *     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
+ *  4. THE GRACE WINDOW. `stale === "expired"` alone is the RECLAIMABILITY
+ *     signal (see leases.ts's staleReason): it fires at ttlMs and is cheap and
+ *     reversible — another agent may simply take the lease. Closing the tab is
+ *     a different, destructive question, and it does not fire until an
+ *     ADDITIONAL reapGraceMs has elapsed past that same ttlMs, so an agent that
+ *     is 20 minutes into a build between browser calls gets a window to come
+ *     back before its tab is destroyed. `dead-pid` skips this check entirely:
+ *     a process that no longer exists is never coming back to reclaim
+ *     anything, so there is nothing to wait for, and that is why dead-pid stays
+ *     immediate while expired does not.
+ *  5. 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.
@@ -71,6 +98,7 @@ export function staleAgentTabs(input: ReapInput): ReapedTab[] {
     if (row.backend !== input.backend) continue;
     if (row.unreadable !== undefined) 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);
     if (origin === undefined || origin.unreadable !== undefined) continue;
@@ -79,6 +107,24 @@ export function staleAgentTabs(input: ReapInput): ReapedTab[] {
   return out;
 }
 
+/**
+ * 45 minutes. Combined with the default 15-minute lease TTL (leases.ts), the
+ * total fuse from an agent's last touch to its tab being destroyed is 60
+ * minutes — generous, because the cost of guessing wrong here is a tab an
+ * agent was still using getting closed out from under it, not merely a lease
+ * another agent could have taken.
+ */
+export const DEFAULT_REAP_GRACE_MS = 2_700_000;
+
+/** Read per call, not at module load, so a test can redirect the value — same
+ *  rule as leaseTtlMs() in leases.ts. Unlike a TTL, zero is a legitimate
+ *  override (disables the grace period, reverting to at-TTL reaping), so the
+ *  validity check is `>= 0` rather than `> 0`. */
+export function reapGraceMs(): number {
+  const raw = Number(process.env.CDP_REAP_GRACE_MS);
+  return Number.isFinite(raw) && raw >= 0 ? raw : DEFAULT_REAP_GRACE_MS;
+}
+
 /**
  * Select, close, and drop the leases. Returns ONLY the tabs actually closed.
  *
@@ -92,6 +138,11 @@ export function staleAgentTabs(input: ReapInput): ReapedTab[] {
  * on the next listing. One lifetime rule for origin records, not three.
  */
 export async function reapStaleAgentTabs(driver: BrowserDriver, backend: LeaseBackend): Promise<ReapedTab[]> {
+  // ONE clock reading, shared with listLeases' own staleReason classification
+  // below: the "expired" verdict a lease reads at and the grace check applied
+  // to it here must agree on what "now" was, or the two could disagree at the
+  // margin.
+  const now = Date.now();
   // The PAGE-ONLY listing: see ReapInput.livePageIds.
   const livePageIds = (await driver.listPages()).map((p) => p.id);
   const [origins, leases] = await Promise.all([
@@ -100,9 +151,9 @@ export async function reapStaleAgentTabs(driver: BrowserDriver, backend: LeaseBa
     // 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[]),
+    listLeases({ now, liveIds: livePageIds, liveBackend: backend }).catch(() => [] as LeaseSummary[]),
   ]);
-  const candidates = staleAgentTabs({ backend, livePageIds, origins, leases });
+  const candidates = staleAgentTabs({ backend, livePageIds, origins, leases, now, reapGraceMs: reapGraceMs() });
   const closed: ReapedTab[] = [];
   for (const c of candidates) {
     const res = await driver.closePage(c.targetId).catch(() => ({ success: false }));