cdp-toolkit 1.6.0 → 1.8.0

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" });
@@ -265,7 +315,7 @@ export async function releaseLeaseFor(backend: LeaseBackend, targetId: string):
  * This exists so enforcement can stay at ONE point per resolution path while
  * the token still reaches it. The token arrives as a key on a tool's args
  * object, many frames above resolveTarget, and threading a parameter through
- * all 41 tools would put the burden on every future contributor to remember
+ * all 45 tools would put the burden on every future contributor to remember
  * the check exists: one missed tool would silently defeat the feature for that
  * tool. mcp.ts and cli.ts open this scope once per dispatch instead, so a tool
  * added tomorrow is covered with no action from whoever writes it.
@@ -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,