cdp-toolkit 1.6.0 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdp-toolkit",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "A lightweight chrome-devtools-mcp alternative: an MCP server + CLI that drives the tabs you name, one target per call over one direct WebSocket, with a bounded timeout on every call, so a stuck page can't wedge your agent or force a /mcp restart. Chrome over CDP and Firefox over WebDriver BiDi, with tools a backend can't run absent from tools/list rather than throwing mid-task. 41 tools including built-in network mocking, a cookie group, tab leases, and tab-to-video screen recording so several agents can drive one browser without stealing each other's tabs. No Puppeteer, no all-target fan-out.",
   "type": "module",
   "license": "MIT",

package/src/leases-tools.ts

@@ -4,13 +4,19 @@
  * Firefox, exactly as the 23 unified tools in that file do.
  */
 import type { BrowserDriver } from "./driver.ts";
-import { newTrackedPage } from "./origins.ts";
+import { newTrackedPage, readOrigin } from "./origins.ts";
+import { reapStaleAgentTabs, type ReapedTab } from "./reap.ts";
+import { pickPage, resolvePage } from "./shared-tools.ts";
+import type { TargetSelector } from "./types.ts";
 import {
   claimLease,
   defaultLabel,
   leaseTtlMs,
   listLeases,
   releaseLease,
+  releaseLeaseFor,
+  requireLease,
+  tokenParts,
   type LeaseBackend,
   type LeaseSummary,
   type LeaseToken,
@@ -31,34 +37,87 @@ export interface ClaimPageResult {
   label: string;
   ttlMs: number;
   expiresAt: number;
+  /** true when this call CREATED the tab, false when it claimed one that was
+   *  already open. The same distinction the creation ledger records, surfaced
+   *  in the answer so a caller knows without a second lookup whether
+   *  release_page will close the tab. */
+  opened: boolean;
 }
 
 /**
- * Claim a tab. With no targetId, opens a fresh tab first (optionally at `url`)
- * and claims that, so "give me my own tab" is one call. With a targetId, claims
- * an already-open tab.
+ * Claim a tab, in one of two modes.
+ *
+ * OPEN: with neither `target` nor `targetId`, opens a fresh tab (optionally at
+ * `url`) and claims that, so "give me my own tab" is one call.
+ *
+ * TAKE OVER: with `target`, claims a tab that is ALREADY OPEN — the first-class
+ * path for "work in the tab I have open", which previously had none, because
+ * `targetId` demands an exact id a human never has to hand and no id at all
+ * meant a brand new tab. `target` takes the toolkit's whole selector grammar
+ * (active | index:N | url:<substr> | title:<substr> | <targetId>).
+ *
+ * `targetId` is unchanged and still accepted; `target` is the same thing with a
+ * grammar, so exactly one of the two may be given.
+ *
+ * WHY RESOLUTION IS GATE-FREE HERE. `target` resolves through pickPage, NOT
+ * resolvePage. resolvePage runs assertLeaseOk, which under CDP_REQUIRE_LEASE
+ * auto-acquires a lease on an unleased tab: routing a claim through it would
+ * claim the tab twice and collide with itself. The protection is not lost, only
+ * moved — claimLease below still refuses a tab a live process holds.
+ *
+ * TAKEOVER IS OF UNLEASED TABS ONLY. There is deliberately no force/steal
+ * option: a tab another live agent holds stays refused with the same conflict
+ * error as before. The tab this feature exists to take over is a human's, and a
+ * human's tab carries no lease.
+ *
+ * RESOLUTION NEVER CREATES A TAB. With `target` given, the open branch is
+ * unreachable: an unmatched selector is an error, never a silently substituted
+ * new tab, because "the tab I asked for is not there" and "here is an empty one
+ * instead" are answers a caller must be able to tell apart.
  */
 export async function claimPage(
   driver: BrowserDriver,
-  args: { targetId?: string; url?: string; label?: string; ttlMs?: number } = {},
+  args: { target?: TargetSelector; targetId?: string; url?: string; label?: string; ttlMs?: number } = {},
 ): Promise<ClaimPageResult> {
+  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 = 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 === "") {
+  let targetId: string;
+  let url: string;
+  let opened: boolean;
+  if (hasTarget) {
+    // Gate-free on purpose: see the header. No tab is created on this path,
+    // including when nothing matches.
+    const hit = await pickPage(driver, pages, args.target).catch((err: unknown) => {
+      throw new LeaseToolError(
+        `claim_page: no open tab matches target '${args.target}' (${(err as Error).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 {
     // Creation ledger, not the lease: this record survives release_page and
     // expiry, so the tab stays attributable to `label` after the lease is gone.
-    // Claiming an EXISTING tab (the else branch) records nothing, because this
-    // toolkit did not create it and provenance is not ownership.
+    // Claiming an EXISTING tab (the branches above) records nothing, because
+    // this toolkit did not create it and provenance is not ownership.
     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;
+    opened = true;
   }
   const liveIds = [...pages.map((p) => p.id), targetId];
   const { record, token } = await claimLease(backend, targetId, {
@@ -73,31 +132,93 @@ export async function claimPage(
     label: record.label,
     ttlMs: record.ttlMs,
     expiresAt: record.lastUsedAt + record.ttlMs,
+    opened,
   };
 }
 
-/** Release a held lease. Idempotent: an already-released or reclaimed lease
- *  reports released:false rather than throwing. */
+/**
+ * Give a lease back, and close the tab if this toolkit opened it.
+ *
+ * TWO WAYS IN, because an auto-acquired lease never handed the caller a token:
+ * `lease` is the 1.4.0 path, `target` resolves through shared-tools' resolvePage
+ * and is authorized by the same gate as any other call. Exactly one is required;
+ * accepting both would leave it ambiguous which one authorizes the close.
+ *
+ * WHY PROVENANCE DECIDES THE CLOSE. A lease says who is driving a tab, never who
+ * opened it. Closing on release is right for a tab this toolkit opened for an
+ * agent and wrong for a tab the human already had open and an agent merely
+ * claimed. origins.ts records exactly that distinction and its records outlive
+ * the lease, so the answer is still there at release time.
+ *
+ * A RELEASE THAT DID NOT HAPPEN NEVER CLOSES. An already-released or reclaimed
+ * lease reports released:false, and the tab may well belong to another agent by
+ * then; closing it would destroy a tab someone else is driving. This is the one
+ * rule in this function that is a safety property rather than a convenience.
+ */
 export async function releasePage(
-  _driver: BrowserDriver,
-  args: { lease?: LeaseToken },
-): Promise<{ released: boolean }> {
-  if (typeof args.lease !== "string" || !args.lease.length) {
-    throw new LeaseToolError("release_page requires the 'lease' token returned by claim_page");
+  driver: BrowserDriver,
+  args: { lease?: LeaseToken; target?: TargetSelector; close?: boolean } = {},
+): Promise<{ released: boolean; closed: boolean; targetId?: string }> {
+  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 = backendOf(driver);
+  let targetId: string;
+  let released: boolean;
+
+  if (hasLease) {
+    const parts = tokenParts(args.lease as LeaseToken);
+    // A malformed token names no tab, so there is nothing to release and
+    // nothing to close. Idempotent rather than throwing, as in 1.4.0.
+    if (!parts) return { released: false, closed: false };
+    targetId = parts.targetId;
+    released = (await releaseLease(args.lease as LeaseToken)).released;
+  } else {
+    // resolvePage runs assertLeaseOk, which IS the authorization: a tab held by
+    // another process throws here, and under strict mode an unleased tab is
+    // acquired first, so the caller holds it by the time we release it.
+    const page = await resolvePage(driver, args.target);
+    targetId = page.id;
+    released = (await releaseLeaseFor(backend, targetId)).released;
   }
-  return releaseLease(args.lease);
+
+  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 };
+
+  // The release already succeeded and is not undone by a failed close: the
+  // caller has genuinely given the lease back either way, and throwing here
+  // would report a release that did happen as an error.
+  const res = await driver.closePage(targetId).catch(() => ({ success: false }));
+  return { released: true, closed: res.success === true, targetId };
 }
 
 /** Enumerate active leases for diagnosis. Requires no token by design. */
 export async function listLeasesTool(
   driver: BrowserDriver,
   _args: Record<string, never> = {} as Record<string, never>,
-): Promise<{ leases: LeaseSummary[]; count: number }> {
+): Promise<{ leases: LeaseSummary[]; count: number; reaped?: ReapedTab[] }> {
+  const backend = backendOf(driver);
+  // Same reap as list_pages, and for the same reason: this is the other tool an
+  // operator runs when tabs look wrong, so it must not report a lease it is
+  // about to delete. Strict mode only.
+  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);
   // liveBackend scopes the target-gone test to the browser these ids came from,
   // so leases held on the OTHER backend are not mislabeled as reclaimable.
-  const leases = await listLeases({ liveIds, liveBackend: backendOf(driver) });
-  return { leases, count: leases.length };
+  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 } : {}) };
 }
 
 export const LEASE_TOOLS = {

package/src/leases.ts

@@ -49,6 +49,15 @@ export interface LeaseRecord {
   createdAt: number;
   lastUsedAt: number;
   ttlMs: number;
+  /**
+   * How this lease was taken, and therefore who may use it without a token.
+   *   true  - the gate acquired it implicitly; passes for any call from `pid`.
+   *   false - claim_page or new_page{claim:true}; the token is required, even
+   *           from the owning process.
+   * Absent on records written by <=1.4.0 and read as false, so an upgrade never
+   * downgrades a held lease from token-required to pid-only.
+   */
+  auto?: boolean;
 }
 
 /** 15 minutes. Refresh-on-use means an active agent never expires, so this only
@@ -65,6 +74,43 @@ export function leaseTtlMs(): number {
   return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_LEASE_TTL_MS;
 }
 
+/**
+ * Whether THIS process is the long-lived MCP server rather than a one-shot CLI
+ * invocation. Module state, which this file's header otherwise forbids: that
+ * prohibition is about state describing OTHER processes' ownership, which must
+ * live on disk because two MCP servers drive one browser. This describes this
+ * process's own role, which no other process can observe or contend for, so a
+ * module flag is the correct scope rather than a violation of the rule.
+ */
+let longLived = false;
+
+/** Called once by mcp.ts at startup. cli.ts never calls it. The parameter
+ *  exists so a test can put the module back into CLI state. */
+export function markLongLivedProcess(value = true): void {
+  longLived = value;
+}
+
+/**
+ * Strict mode: every tool call acquires a lease for the tab it resolves, and
+ * stale agent tabs are reaped on read. Off by default, so 1.4.0 consumers are
+ * unaffected.
+ *
+ * ALWAYS FALSE UNDER THE CLI, regardless of the env var, and that is not a
+ * convenience. cli.ts already refuses claim_page because a CLI invocation is
+ * one process per call, so its lease is reclaimable by the dead-pid rule the
+ * moment the process exits, and "a lease that is reclaimable on arrival is
+ * worse than no lease". Auto-acquire would mint exactly such a lease on every
+ * call. The sharper danger is reap: those dead-pid records would read as
+ * orphaned agent tabs, so a CLI user running list_pages twice could watch the
+ * second run close the tabs the first run leased. Read per call, like
+ * leaseDir(), so a test can flip it.
+ */
+export function requireLease(): boolean {
+  if (!longLived) return false;
+  const raw = (process.env.CDP_REQUIRE_LEASE ?? "").trim().toLowerCase();
+  return raw === "1" || raw === "true" || raw === "yes" || raw === "on";
+}
+
 /** The label recorded when a caller supplies none. ONE definition, because it
  *  is now written by three call sites (claim_page, new_page, and the origin
  *  ledger) and a second rule would make the same tab describe itself two
@@ -158,6 +204,9 @@ export interface ClaimOptions {
   now?: number;
   /** Live target ids from the browser, enabling the "target-gone" reclamation. */
   liveIds?: readonly string[];
+  /** Marks the lease gate-acquired. See LeaseRecord.auto. Defaults to false:
+   *  an unmarked claim is an explicit one, which is the stricter reading. */
+  auto?: boolean;
 }
 
 /** Why an existing lease may be taken over. All three are sufficient alone. */
@@ -214,6 +263,7 @@ export async function claimLease(
       createdAt: now,
       lastUsedAt: now,
       ttlMs: opts.ttlMs ?? leaseTtlMs(),
+      auto: opts.auto === true,
     };
     try {
       await writeFile(leaseFile(backend, targetId), JSON.stringify(record), { flag: "wx" });
@@ -370,7 +420,29 @@ export async function assertLeaseOk(
   const where = describeTarget(targetId, ctx);
 
   if (token === undefined) {
-    if (!held) return; // unleased, or leased-but-reclaimable: today's behavior
+    if (!held) {
+      // STRICT MODE: acquire rather than wave through. This is the change that
+      // makes "you cannot drive a tab you do not hold" true, and it is done
+      // here rather than by refusing because refusing would force every caller
+      // to learn a claim/release protocol to do what used to just work.
+      // Marked auto:true, which is what lets a later call from this same
+      // process pass with no token. A LeaseConflictError from claimLease (two
+      // processes racing to acquire the same tab, resolved by the "wx"
+      // exclusive create) propagates: the loser is genuinely refused.
+      if (requireLease()) {
+        await claimLease(backend, targetId, { label: defaultLabel(), ttlMs: leaseTtlMs(), auto: true, now });
+      }
+      return; // unleased, or leased-but-reclaimable: today's behavior
+    }
+    // An auto lease is owned by a PROCESS, not by a token, so any call from the
+    // owning pid passes. NOT gated on requireLease(): an auto:true record can
+    // only exist because strict mode created it, and gating this too would mean
+    // turning the flag off locks this process out of leases it still holds. It
+    // cannot regress 1.4.0, where no auto:true record can exist at all.
+    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,
@@ -396,8 +468,16 @@ export async function assertLeaseOk(
   // call arrives here, select_page via activatePage included.
   if (parts.backend !== backend || parts.targetId !== targetId) {
     // The token is about a different tab, so it says nothing about this one.
-    // An unleased tab is open to everyone, token in hand or not.
-    if (!held) return;
+    // Under strict mode this tab still has to be acquired: an agent holding
+    // tab A that reaches into unleased tab C is exactly the case the feature
+    // exists to cover, and it is the COMMON case under the ambient dispatch
+    // scope, not an edge one.
+    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,