cdp-toolkit 1.7.0 → 1.8.0

package/src/manifest.ts

@@ -25,7 +25,7 @@ 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. 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.",
+    "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 abandoned agent tabs, but reap-CLOSE and lease-RECLAIMABLE (list_leases' 'stale') now fire at different times: a lease reads reclaimable the moment its TTL elapses, cheap and reversible since another agent may simply take it, while this call only CLOSES the tab, destructively, after an ADDITIONAL grace period past that TTL (CDP_REAP_GRACE_MS, default 2700000ms/45 minutes, so 60 minutes total after last use) — a tab an agent is mid-build between calls on is not destroyed out from under it. A dead-pid lease is reaped immediately regardless of grace: that process is never coming back. Closed tabs are reported in an additive 'reaped' array ({targetId,label,reason}) present only when something was actually closed; a tab with no lease is never reaped. Every entry under an active, readable lease of this backend also carries 'lease': {label, pid, idleMs, expiresAt, stale} — idleMs and expiresAt are computed fresh on every call (now-lastUsedAt and lastUsedAt+ttlMs), never read off disk, and this is unconditional on 'probe'. Set 'probe' to true to also ping each page-type target's renderer: one bounded (500ms) check per target, never more, so a single wedged tab cannot stall the listing beyond its own budget. This adds 'responsive' (true iff the ping answered in time; false on a timeout, a page-side exception, or an unreachable target — never an error for the whole call) and, where that same round trip found human-attributed input, 'humanActiveMs' (see claim_page and list_leases for what that field means and cannot prove). 'responsive' and 'humanActiveMs' are both ABSENT — never false/null — when 'probe' is not set, and 'responsive' is likewise absent on a backend that cannot answer this ping at all.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -36,6 +36,10 @@ export const MANIFEST: ToolSpec[] = [
         "all": {
           "type": "boolean",
           "description": "Include non-page targets (service/shared workers, background pages) when true; otherwise only page-type tabs are listed."
+        },
+        "probe": {
+          "type": "boolean",
+          "description": "Ping each page-type target's renderer before returning: one bounded (500ms) Runtime.evaluate per target, never more. Adds 'responsive' to every page-type entry and, where the same round trip finds human-attributed input, 'humanActiveMs'. A wedged or unreachable tab reports responsive:false rather than failing the call. Defaults to false, which is byte-identical to the pre-1.8.0 shape."
         }
       },
       "required": [],
@@ -117,7 +121,7 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "name": "navigate_page",
-    "description": "Navigate a target page to a URL (Page.navigate) OR reload it (reload:true) over raw CDP, then wait for the load milestone with a bounded timeout so a wedged renderer can't hang. Returns {url,frameId,waitedFor} (plus reloaded:true on a reload); waitUntil supports 'load'|'domcontentloaded' only (no 'networkidle'), and there is no auto-snapshot of the new page. Pass reload:true with ignoreCache:true for a hard reload that refetches every subresource (e.g. to pick up a freshly-deployed, non-content-hashed bundle the HTTP cache would serve stale).",
+    "description": "Navigate a target page to a URL (Page.navigate), reload it (reload:true), OR go back/forward in its session history (history:'back'|'forward'), then wait for the load milestone with a bounded timeout so a wedged renderer can't hang. Exactly one of url / reload / history per call. Returns {url,frameId,waitedFor} (plus reloaded:true on a reload, traversed:'back'|'forward' on a history move); waitUntil supports 'load'|'domcontentloaded' only (no 'networkidle'), and there is no auto-snapshot of the new page. Pass reload:true with ignoreCache:true for a hard reload that refetches every subresource (e.g. to pick up a freshly-deployed, non-content-hashed bundle the HTTP cache would serve stale).",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -137,6 +141,14 @@ export const MANIFEST: ToolSpec[] = [
           "type": "boolean",
           "description": "Reload the current page (Page.reload) instead of navigating to url. Default false."
         },
+        "history": {
+          "type": "string",
+          "enum": [
+            "back",
+            "forward"
+          ],
+          "description": "Traverse this tab's session history instead of loading a url: 'back' and 'forward' are the browser's Back and Forward buttons. Mutually exclusive with 'url' and 'reload' — passing two of the three is refused by name rather than resolved by precedence. Works on BOTH backends (Chrome: Page.getNavigationHistory + Page.navigateToHistoryEntry; Firefox: browsingContext.traverseHistory) and waits for the same load milestone as an ordinary navigation. Going back from the first entry, or forward from the last, is an ERROR naming the direction — never a silent success that navigated nowhere. The result carries traversed:'back'|'forward' alongside the resulting url."
+        },
         "ignoreCache": {
           "type": "boolean",
           "description": "On reload, bypass the HTTP cache (hard reload) so subresources are refetched. Ignored unless reload:true. Default false."
@@ -374,7 +386,7 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "name": "click",
-    "description": "Click an element via a synthetic mouse press/release at the element's scrolled-into-view bounding-rect center. Target the element with exactly one of 'uid' (a CDP backendDOMNodeId from take_snapshot) or 'selector' (a CSS selector).",
+    "description": "Click an element via a synthetic mouse press/release at the element's scrolled-into-view bounding-rect center. Target the element with exactly one of 'uid' (a CDP backendDOMNodeId from take_snapshot) or 'selector' (a CSS selector). clickCount:3 triple-clicks (selects a paragraph/line in most editors). 'modifiers' holds Alt/Control/Meta/Shift for the press and release, like a real modifier-click; on the Firefox backend a non-empty 'modifiers' throws (not yet supported over BiDi), so a modifier click there needs --browser chrome.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -405,7 +417,20 @@ export const MANIFEST: ToolSpec[] = [
         },
         "clickCount": {
           "type": "number",
-          "description": "Number of clicks: 1 = single (default), 2 = double-click."
+          "description": "Number of clicks: 1 = single (default), 2 = double-click, 3 = triple-click."
+        },
+        "modifiers": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "Alt",
+              "Control",
+              "Meta",
+              "Shift"
+            ]
+          },
+          "description": "Modifier keys held for the click's press and release, e.g. ['Shift'] for a shift-click. Not supported on the Firefox backend: passing a non-empty array there throws."
         }
       },
       "required": [],
@@ -441,7 +466,7 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "name": "drag",
-    "description": "Drag from a source element to a destination element via synthetic mouse press/move/release (approximates HTML5 drag-and-drop; not guaranteed for every custom DnD library). 'from' and 'to' each take exactly one of uid (a CDP backendDOMNodeId from take_snapshot) or selector.",
+    "description": "Drag from a source element to a destination. 'from' takes exactly one of uid (a CDP backendDOMNodeId from take_snapshot) or selector. The destination is exactly one of 'to' (an element via uid/selector, or an absolute viewport point via x+y) or 'by' ({dx,dy} offset from the source point — sliders, map panning, resize handles). mode:'mouse' (default) dispatches synthetic mouse press/move/release: right for widgets built on raw pointer events, and Chrome does turn it into a real drag, but WHICH drag events reach the page depends on where the interpolated pointer path happens to land — measured on Chrome 151, the default steps:2 delivers ZERO dragover events, so an HTML5 drop zone written the standard way (preventDefault inside dragover) refuses the drop entirely. mode:'html5' performs the drag deterministically instead: Chrome's drag interception hands back the DragData the page's own dragstart built, and the toolkit replays it as dragEnter/dragOver/drop exactly at the destination, so a draggable=\"true\" / dataTransfer drop zone works regardless of the pointer path. mode:'html5' is CHROME-ONLY: it requires capability 'input.html5Drag' and is rejected with a clear error under the Firefox backend, where the tool itself remains available for mouse-mode drags. 'steps' (default 2) sets how many interpolated mouse-move events are dispatched between source and destination; raise it for DnD libraries with a movement threshold or per-frame sampling.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -470,7 +495,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "to": {
           "type": "object",
-          "description": "Destination element to drag to. Provide exactly one of uid or selector.",
+          "description": "Where the drag ends: exactly one of uid, selector, or x+y. Mutually exclusive with 'by'; exactly one of to/by is required.",
           "properties": {
             "uid": {
               "type": "number",
@@ -479,18 +504,222 @@ export const MANIFEST: ToolSpec[] = [
             "selector": {
               "type": "string",
               "description": "CSS selector for the destination element (resolved via document.querySelector)."
+            },
+            "x": {
+              "type": "number",
+              "description": "Absolute viewport x-coordinate to drop at. Must be given together with 'y'. Use this when there is no droppable element to name (a canvas, a slider track)."
+            },
+            "y": {
+              "type": "number",
+              "description": "Absolute viewport y-coordinate to drop at. Must be given together with 'x'."
+            }
+          },
+          "additionalProperties": false
+        },
+        "by": {
+          "type": "object",
+          "description": "Drag by an offset from the source element's center instead of to a destination: at least one of dx/dy, the other defaults to 0. Mutually exclusive with 'to'; exactly one of to/by is required. Use for sliders (by:{dx:40}), map panning, and resize handles.",
+          "properties": {
+            "dx": {
+              "type": "number",
+              "description": "Horizontal offset in CSS pixels; positive drags RIGHT."
+            },
+            "dy": {
+              "type": "number",
+              "description": "Vertical offset in CSS pixels; positive drags DOWN."
             }
           },
           "additionalProperties": false
+        },
+        "mode": {
+          "type": "string",
+          "enum": [
+            "mouse",
+            "html5"
+          ],
+          "description": "'mouse' (default): synthetic mouse press/move/release, right for widgets built on raw pointer events. Chrome does turn this into a real HTML5 drag too, but WHICH drag events reach the page depends on the interpolated pointer path: at the default steps:2, an HTML5 drop zone written the standard way (preventDefault inside dragover) sees zero dragover events and refuses the drop. 'html5': real HTML5 drag-and-drop (dragstart/dragEnter/dragOver/drop with the page's own dataTransfer), deterministic regardless of pointer path. 'html5' is CHROME-ONLY and is rejected with a clear error under the Firefox backend."
+        },
+        "steps": {
+          "type": "number",
+          "description": "Number of interpolated mouse-move events dispatched between the source and destination points, evenly spaced, the last landing exactly on the destination. Integer 1-500, default 2 (midpoint then destination). Raise it for DnD libraries with a movement threshold or per-frame sampling."
         }
       },
       "required": [
-        "from",
-        "to"
+        "from"
       ],
       "additionalProperties": false
     }
   },
+  {
+    "name": "scroll",
+    "description": "Dispatch a wheel/scroll event at an anchor point: provide at most one of 'uid', 'selector', or 'x'+'y'; omit all three to scroll at the viewport center. An element anchor ('uid' or 'selector') is scrolled into view first, the same as click/hover. At least one of 'deltaX'/'deltaY' is required; positive 'deltaY' scrolls DOWN and positive 'deltaX' scrolls RIGHT (wheel-event convention). Chrome dispatches Input.dispatchMouseEvent{type:'mouseWheel'}; Firefox dispatches WebDriver BiDi's 'wheel' input source. Returns the resolved anchor point ({x,y}) plus the delta actually dispatched.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "lease": {
+          "type": "string",
+          "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",
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+        },
+        "uid": {
+          "type": "number",
+          "description": "CDP backendDOMNodeId of the element to scroll into view and anchor at, obtained from take_snapshot. Provide at most one of uid, selector, or x+y; omit all three to scroll at the viewport center."
+        },
+        "selector": {
+          "type": "string",
+          "description": "CSS selector for the element to scroll into view and anchor at (resolved via document.querySelector). Provide at most one of uid, selector, or x+y; omit all three to scroll at the viewport center."
+        },
+        "x": {
+          "type": "number",
+          "description": "Absolute viewport x-coordinate to anchor the scroll at. Must be given together with 'y'. Provide at most one of uid, selector, or x+y."
+        },
+        "y": {
+          "type": "number",
+          "description": "Absolute viewport y-coordinate to anchor the scroll at. Must be given together with 'x'. Provide at most one of uid, selector, or x+y."
+        },
+        "deltaX": {
+          "type": "number",
+          "description": "Horizontal scroll delta; positive scrolls RIGHT. At least one of deltaX/deltaY is required."
+        },
+        "deltaY": {
+          "type": "number",
+          "description": "Vertical scroll delta; positive scrolls DOWN. At least one of deltaX/deltaY is required."
+        }
+      },
+      "required": [],
+      "additionalProperties": false
+    }
+  },
+  {
+    "name": "dispatch_mouse",
+    "description": "Dispatch exactly one raw mouse event ('move', 'down', or 'up') at absolute viewport coordinates: the toolkit's lowest-level input primitive. Compose move/down/move/up calls yourself to reach anything a physical mouse can do that click/drag's fixed sequences cannot — canvas drag-painting, marquee/rubber-band selection, a custom widget with its own hit-testing. Chrome-only (capability 'input.raw'): absent from tools/list under the Firefox backend, never present-and-throwing.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "lease": {
+          "type": "string",
+          "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",
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+        },
+        "action": {
+          "type": "string",
+          "enum": [
+            "move",
+            "down",
+            "up"
+          ],
+          "description": "Which raw event to dispatch: 'move' (mouseMoved), 'down' (mousePressed), or 'up' (mouseReleased)."
+        },
+        "x": {
+          "type": "number",
+          "description": "Viewport x-coordinate. Required on every call: CDP has no notion of a 'current pointer position' to default from."
+        },
+        "y": {
+          "type": "number",
+          "description": "Viewport y-coordinate. Required on every call."
+        },
+        "button": {
+          "type": "string",
+          "enum": [
+            "left",
+            "right",
+            "middle"
+          ],
+          "description": "Mouse button: 'left' (default), 'right', or 'middle'."
+        },
+        "clickCount": {
+          "type": "number",
+          "description": "Click-run length for a 'down' or 'up' event (2 = the second half of a double-click, 3 = triple-click). Ignored for 'move'; defaults to 1."
+        },
+        "modifiers": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "Alt",
+              "Control",
+              "Meta",
+              "Shift"
+            ]
+          },
+          "description": "Modifier keys held for this one event, e.g. ['Shift']."
+        }
+      },
+      "required": [
+        "action",
+        "x",
+        "y"
+      ],
+      "additionalProperties": false
+    }
+  },
+  {
+    "name": "wait_for_download",
+    "description": "Wait for a file download to finish and return it as a real file on disk: {path,suggestedFilename,bytes,url,target}. The file is written under the artifact dir's downloads/ folder and renamed from Chrome's internal guid to the page's own filename, collision-suffixed (report.csv, report-1.csv, ...). ORDERING RULE, and it is not optional: download capture must be ARMED BEFORE the click that starts the download — call wait_for_download{arm:true} first (it arms and returns immediately, reporting {armed:true,downloadPath,pending}), then click, then call wait_for_download to collect the finished file. This is Chrome's behavior, not a preference: the download-behavior override is per-connection state that Chrome REVERTS the moment the arming client disconnects, and an unarmed headless Chrome denies the download outright, so a download triggered before anything armed is lost with no file anywhere. SIDE EFFECT, browser-global: arming redirects EVERY download in this browser (all tabs, all origins) into the toolkit's downloads directory for as long as this server runs, and downloads no longer land in the user's normal Downloads folder. Because the arm lives on a connection this server process holds open, this is an MCP-server capability: under the one-shot CLI the connection dies with the process and nothing is captured. Chrome-only (capability 'browser.downloads'): absent from tools/list under the Firefox backend, never present-and-throwing, because WebDriver BiDi has no command to redirect a download to a chosen directory.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "lease": {
+          "type": "string",
+          "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",
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'. A download is browser-scoped, so this names the tab for the lease check and for the echoed target, not which download is returned."
+        },
+        "arm": {
+          "type": "boolean",
+          "description": "Arm download capture and return immediately instead of waiting: {armed:true,downloadPath,pending}. Call this BEFORE the click that triggers the download. 'pending' counts downloads that already completed and have not been collected yet, so an arm call doubles as a peek."
+        },
+        "timeoutMs": {
+          "type": "number",
+          "description": "How long to wait for a download to complete, in milliseconds. Default 30000. Ignored with arm:true. A download that already completed and was not yet collected is returned immediately, so this only bounds the wait for a download still in flight."
+        }
+      },
+      "required": [],
+      "additionalProperties": false
+    }
+  },
+  {
+    "name": "grant_permissions",
+    "description": "Grant browser permissions for an origin up front, so a page asking for geolocation / notifications / clipboard gets an answer instead of showing a prompt no agent can click. 'permissions' takes CDP PermissionType values ('geolocation', 'notifications', 'clipboardReadWrite', 'camera', 'microphone', 'midi', ...); an unknown name is refused by Chrome with the bad value in the message. Returns {granted,origin,target}, or {reset:true,target} for a reset-only call. Grants are keyed by ORIGIN, not by tab: every tab on that origin is affected, including ones opened later. reset:true clears this server's previous grants first (or instead, when no permissions are given) — note CDP's reset is not origin-scoped, so it clears them for every origin at once. The grant lives on a connection this server process holds open and Chrome DISCARDS IT when that connection closes, so this is an MCP-server capability: under the one-shot CLI the grant dies with the process. Chrome-only (capability 'browser.permissions'): absent from tools/list under the Firefox backend, never present-and-throwing.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "lease": {
+          "type": "string",
+          "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",
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'. Used for the lease check and, when 'origin' is omitted, as the source of the origin to grant for."
+        },
+        "permissions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "CDP PermissionType values to grant, e.g. ['geolocation'] or ['clipboardReadWrite','clipboardSanitizedWrite']. Required unless reset:true. An empty array is refused rather than treated as a successful no-op."
+        },
+        "origin": {
+          "type": "string",
+          "description": "Origin the grant applies to, e.g. 'https://example.com'. Defaults to the target tab's own origin. Required explicitly when that tab has no grantable origin (data:, blob:, about:blank all serialize to the opaque origin 'null'), which is refused with a message naming the tab's url."
+        },
+        "reset": {
+          "type": "boolean",
+          "description": "Clear this server's previous permission grants (Browser.resetPermissions). With 'permissions' it resets FIRST and then grants, so the result is exactly the listed permissions; on its own it is a reset-only call answering {reset:true}. Not scoped to 'origin': CDP resets every origin at once."
+        }
+      },
+      "required": [],
+      "additionalProperties": false
+    }
+  },
   {
     "name": "fill",
     "description": "Fill an element by focusing it, clearing existing content, then inserting 'value' via Input.insertText (atomic paste-like commit, not per-character keystrokes). Target with exactly one of 'uid' (a CDP backendDOMNodeId from take_snapshot) or 'selector' (a CSS selector).",
@@ -1369,7 +1598,7 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "name": "claim_page",
-    "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.",
+    "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. IS SOMEBODY ELSE IN THIS TAB: the answer also carries 'humanActiveMs', milliseconds since input that this server did not dispatch — i.e. since a person last clicked, typed, or scrolled here. null means NO DATA (the tab carries no activity beacon, which is normal the first time anyone claims a person's tab, or every input on it was this server's own); it never means 'no human'. The field is absent entirely on a backend that cannot answer. On a takeover of a tab a human used within the last 30 seconds the answer additionally carries 'contention', a warning string. THE CLAIM IS NEVER REFUSED FOR THIS: taking over a person's tab is what takeover mode is for, so by the time you read the warning you already hold the lease and the tab is yours to drive. It tells you that driving it now means fighting a live person for the keyboard and mouse, so you can open your own tab instead or ask first. Known limits: input inside a cross-origin iframe is invisible to it, and a second MCP server's clicks read as human to this one.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -1423,7 +1652,7 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "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. 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.",
+    "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 (see that tool's description for the grace period between a lease reading reclaimable and its tab actually being closed), reporting them in an additive 'reaped' array and omitting their rows from the listing. A row also carries 'humanActiveMs' — milliseconds since input this server did not dispatch, i.e. since a person last used that tab — WHERE THE TAB CAN ANSWER. The field is ABSENT rather than null when it cannot: no activity beacon on that tab, every input on it accounted for by this server, a row belonging to the other backend, a tab no longer open, or a page that would not evaluate. Absence therefore means 'no answer', never 'nobody is there'. Note that lastUsedAt measures TOOLKIT calls only, so a tab a person has been typing in for ten minutes looks perfectly idle by that field and is exactly the case humanActiveMs exists to expose. Two further fields are computed fresh on every call, never read off disk: 'idleMs' (now minus lastUsedAt) and 'expiresAt' (lastUsedAt plus ttlMs — the same value claim_page already returns under that name). Both are omitted on an 'unreadable' row, whose lastUsedAt and ttlMs are the zeroed placeholders described above.",
     "inputSchema": {
       "type": "object",
       "properties": {},

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.8.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/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 }));