cdp-toolkit 1.6.0 → 1.7.0

package/src/manifest.ts

@@ -25,13 +25,13 @@ export interface ToolSpec {
 export const MANIFEST: ToolSpec[] = [
   {
     "name": "list_pages",
-    "description": "Enumerate browser page targets via the CDP browser endpoint (GET /json/list). By default returns only page-type tabs; set 'all' to also include workers and background pages. Each entry carries the targetId used as a target selector elsewhere, plus an 'origin' field recording where the tab came from: 'agent' means this toolkit created it (the entry then also carries the creating 'label' and 'createdAt'), and this stays true after the creating agent releases its lease or dies, which is what makes a stray agent tab findable later. 'unknown' means there is no creation record. It never says 'human': the toolkit cannot prove a person opened a tab, so 'unknown' is the honest word for a tab it did not create, one opened before the toolkit ran, or one whose record could not be written. A tab whose record exists but could not be read reports origin 'unknown' plus 'originUnreadable', so a broken record is never mistaken for no record.",
+    "description": "Enumerate browser page targets via the CDP browser endpoint (GET /json/list). By default returns only page-type tabs; set 'all' to also include workers and background pages. Each entry carries the targetId used as a target selector elsewhere, plus an 'origin' field recording where the tab came from: 'agent' means this toolkit created it (the entry then also carries the creating 'label' and 'createdAt'), and this stays true after the creating agent releases its lease or dies, which is what makes a stray agent tab findable later. 'unknown' means there is no creation record. It never says 'human': the toolkit cannot prove a person opened a tab, so 'unknown' is the honest word for a tab it did not create, one opened before the toolkit ran, or one whose record could not be written. A tab whose record exists but could not be read reports origin 'unknown' plus 'originUnreadable', so a broken record is never mistaken for no record. Under CDP_REQUIRE_LEASE this call also reaps: a tab this toolkit created whose lease is stale because the owning process died or the TTL elapsed is closed, and the closed tabs are reported in an additive 'reaped' array ({targetId,label,reason}) that is present only when something was actually closed. A tab with no lease is never reaped, so tabs opened by a caller that never uses leases are untouched.",
     "inputSchema": {
       "type": "object",
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "all": {
           "type": "boolean",
@@ -50,7 +50,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "url": {
           "type": "string",
@@ -58,7 +58,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "claim": {
           "type": "boolean",
-          "description": "Claim the new tab atomically as part of creating it and return a lease token alongside {targetId,url}. Default false, which is byte-identical to the pre-1.2 behavior."
+          "description": "Claim the new tab atomically as part of creating it and return a lease token alongside {targetId,url}. Default false, which is byte-identical to the pre-1.2 behavior. Under CDP_REQUIRE_LEASE the new tab is claimed and a lease returned even without claim:true, because a tab nobody holds is a tab nobody may drive; passing claim:true additionally makes the lease an explicit one, which requires its token on every later call even from this same process."
         },
         "label": {
           "type": "string",
@@ -81,7 +81,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -102,7 +102,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -123,7 +123,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -165,7 +165,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -198,7 +198,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -235,7 +235,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -266,7 +266,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -322,7 +322,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -357,7 +357,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -380,7 +380,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -420,7 +420,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -447,7 +447,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -499,7 +499,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -532,7 +532,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -578,7 +578,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -611,7 +611,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -643,7 +643,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -682,7 +682,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -733,7 +733,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -833,7 +833,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -871,7 +871,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -908,7 +908,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -935,7 +935,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -958,7 +958,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -989,7 +989,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -1024,7 +1024,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -1050,7 +1050,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -1069,7 +1069,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "tracePath": {
           "type": "string",
@@ -1088,7 +1088,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -1126,7 +1126,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -1173,7 +1173,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -1196,7 +1196,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -1219,7 +1219,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "url": {
           "type": "string",
@@ -1263,7 +1263,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -1333,7 +1333,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -1352,7 +1352,7 @@ export const MANIFEST: ToolSpec[] = [
       "properties": {
         "lease": {
           "type": "string",
-          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+          "description": "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
         },
         "target": {
           "type": "string",
@@ -1369,17 +1369,21 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "name": "claim_page",
-    "description": "Take exclusive ownership of a browser tab and return an opaque lease token. With no targetId, opens a fresh tab (optionally at url) and claims it, so 'give me my own tab' is one call. Any later tool call against a leased tab must carry the matching token in its 'lease' argument or it is refused, naming the holder. The lease is reclaimable once its owning process dies, its ttlMs elapses without use, or its tab is closed. Refused from the CLI: a CLI invocation is one process per call, so its lease would be reclaimable immediately.",
+    "description": "Take exclusive ownership of a browser tab and return an opaque lease token. Two modes. FRESH TAB: with no target and no targetId, opens a new tab (optionally at url) and claims it, so 'give me my own tab' is one call. TAKEOVER: with target, claims a tab that is already open — this is how you work in a tab the human already has open when they ask you to, instead of opening your own — resolving any target selector against the live page list and never creating anything. The answer's 'opened' flag says which happened (true only when this call created the tab), and that same creation record is what release_page consults, so a tab you took over is left open when you release it. Any later tool call against a leased tab must carry the matching token in its 'lease' argument or it is refused, naming the holder. The lease is reclaimable once its owning process dies, its ttlMs elapses without use, or its tab is closed. Refused from the CLI: a CLI invocation is one process per call, so its lease would be reclaimable immediately.",
     "inputSchema": {
       "type": "object",
       "properties": {
+        "target": {
+          "type": "string",
+          "description": "Take over an already-open tab, e.g. one the human has open, when asked to: pass any target selector — active | index:N | url:<substr> | title:<substr> | <targetId>. Resolved against the live page list only, so it NEVER opens a tab: a selector that matches nothing is an error, not a new blank tab. The tab is left open on release because the toolkit did not create it. Refused if another live process holds it, including a lease the gate acquired for that process automatically under CDP_REQUIRE_LEASE: this takes over unleased (human) tabs and never steals one from a live agent. Mutually exclusive with targetId."
+        },
         "targetId": {
           "type": "string",
-          "description": "Claim this already-open page target instead of opening a new tab. Must be an exact target id, not a selector."
+          "description": "Claim this already-open page target instead of opening a new tab. Must be an exact target id, not a selector. Kept for back-compat: prefer 'target', which accepts an exact id too plus every other selector form. Mutually exclusive with target."
         },
         "url": {
           "type": "string",
-          "description": "When opening a fresh tab, navigate it here. Ignored when targetId is given."
+          "description": "When opening a fresh tab, navigate it here. Ignored when target or targetId is given, since both of those claim a tab that is already open."
         },
         "label": {
           "type": "string",
@@ -1396,24 +1400,30 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "name": "release_page",
-    "description": "Release a held lease, given its token. Idempotent: releasing an already-released, reclaimed, or expired lease reports released:false rather than erroring. Does not close the tab.",
+    "description": "Give a lease back, and close the tab if this toolkit opened it. Takes exactly one of 'lease' (the token claim_page returned) or 'target' (a selector for a tab this process holds, which is how you release a lease the gate acquired for you automatically, since that path never hands you a token). A tab with a creation record from this toolkit is closed; a tab that was already open and merely claimed is released and left alone. Override either way with 'close'. Idempotent: an already-released, reclaimed, or expired lease reports released:false, and a release that did not happen never closes anything, because by then the tab may belong to another agent. Answers {released, closed, targetId}.",
     "inputSchema": {
       "type": "object",
       "properties": {
         "lease": {
           "type": "string",
-          "description": "The opaque token claim_page (or new_page with claim:true) returned."
+          "description": "The opaque token claim_page (or new_page with claim:true) returned. Mutually exclusive with 'target'. Under CDP_REQUIRE_LEASE a lease the gate acquired for you automatically never produced a token in the first place, so give 'target' instead."
+        },
+        "target": {
+          "type": "string",
+          "description": "Target selector for a tab this process holds: active | index:N | url:<substr> | title:<substr> | <targetId>. Mutually exclusive with 'lease'. Refused if another process holds the tab."
+        },
+        "close": {
+          "type": "boolean",
+          "description": "Force the close decision instead of letting the creation ledger decide. true closes even a tab this toolkit did not open; false keeps an agent-created tab open. Omit for the default, which closes only tabs this toolkit created."
         }
       },
-      "required": [
-        "lease"
-      ],
+      "required": [],
       "additionalProperties": false
     }
   },
   {
     "name": "list_leases",
-    "description": "Enumerate every active lease for diagnosis: backend, target id, agent label, pid, createdAt, lastUsedAt, ttlMs, whether the owning process is still alive, and whether the lease is reclaimable and why. Requires no token. Never returns the lease nonce, so this cannot be used to forge a token. A row for a lease file that could not be read or parsed instead carries `unreadable` (the errno, or \"unparseable\"), with label, pid, and the timestamp fields as zero placeholders and stale always false, since stale is what marks a lease free to take and an unreadable one must never read that way.",
+    "description": "Enumerate every active lease for diagnosis: backend, target id, agent label, pid, createdAt, lastUsedAt, ttlMs, whether the owning process is still alive, and whether the lease is reclaimable and why. Requires no token. Never returns the lease nonce, so this cannot be used to forge a token. A row for a lease file that could not be read or parsed instead carries `unreadable` (the errno, or \"unparseable\"), with label, pid, and the timestamp fields as zero placeholders and stale always false, since stale is what marks a lease free to take and an unreadable one must never read that way. Under CDP_REQUIRE_LEASE this call reaps abandoned agent tabs exactly as list_pages does, reporting them in an additive 'reaped' array and omitting their rows from the listing.",
     "inputSchema": {
       "type": "object",
       "properties": {},

package/src/mcp.ts

@@ -21,9 +21,9 @@ import { MANIFEST } from "./manifest.ts";
 import { resolveBrowserKind, stripBrowserFlag, getOrCreateFirefoxSession, disposeFirefoxSession } from "./backend.ts";
 import { toolAvailability } from "./capabilities.ts";
 import { FIREFOX_TOOLS } from "./firefox-tools.ts";
-import { leaseFromArgs, withLeaseScope } from "./leases.ts";
+import { leaseFromArgs, markLongLivedProcess, withLeaseScope } from "./leases.ts";
 
-const VERSION = "1.6.0";
+const VERSION = "1.7.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).
@@ -100,6 +100,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 });
 
 auditCoverage();
+// This process is the long-lived MCP server, which is what makes strict mode
+// (CDP_REQUIRE_LEASE) safe to honor here and unsafe in cli.ts. See requireLease.
+markLongLivedProcess();
 await server.connect(new StdioServerTransport());
 console.error(`[cdp-toolkit] MCP server v${VERSION} ready, browser=${BROWSER}, ${AVAILABILITY.available.length} tools, CDP_BASE=${BASE}`);
 

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;
+}