cdp-toolkit 1.8.0 → 1.9.1

package/src/manifest.ts

@@ -89,7 +89,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         }
       },
       "required": [
@@ -110,7 +110,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         }
       },
       "required": [
@@ -131,7 +131,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         "url": {
           "type": "string",
@@ -181,7 +181,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         "text": {
           "type": "string",
@@ -204,7 +204,7 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "name": "evaluate_script",
-    "description": "Run arbitrary JavaScript in the target page's main-world context over raw CDP and return the evaluated value (returnByValue). With no 'args' the 'expression' is evaluated as a raw expression; when 'args' is provided 'expression' must be a function literal (arrow or classic) invoked on globalThis with the args passed positionally. A thrown exception surfaces as an error; non-serializable returns (DOM nodes, functions) come back as their CDP description string. Pass 'savePath' to write the evaluated value to a JSON file instead: the response then carries only {path,bytes,type,target} and the value itself never appears in it, in any form. That is the way to read a credential (a JWT or session token out of localStorage, for example) without putting the secret into the caller's transcript.",
+    "description": "Run arbitrary JavaScript in the target page's main-world context over raw CDP and return the evaluated value (returnByValue). With no 'args' the 'expression' is evaluated as a raw expression; when 'args' is provided 'expression' must be a function literal (arrow or classic) invoked on globalThis with the args passed positionally. A thrown exception surfaces as an error; non-serializable returns (DOM nodes, functions) come back as their CDP description string. Pass 'savePath' to write the evaluated value to a JSON file instead: the response then carries only {path,bytes,type,target} and the value itself never appears in it, in any form. That is the way to read a credential (a JWT or session token out of localStorage, for example) without putting the secret into the caller's transcript. This is the one tool that can EVALUATE inside an MV3 extension's background SERVICE WORKER rather than a page (list_network_requests/get_network_request/list_console_messages OBSERVE one): pass target 'worker:<extension-id>' (Chrome only) and read chrome.storage.local, chrome.runtime and the worker's own globals directly, with an idle-evicted worker started for you first (see 'wake').",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -214,11 +214,15 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Page selector: 'active' (or omit) -> first page-type target | '<32-hex targetId>' -> exact target by id | 'index:N' -> Nth page-type target (0-based) | 'url:<substring>' -> first page whose url contains substring | 'title:<substring>' -> first page whose title contains substring."
+          "description": "Page selector: 'active' (or omit) -> first page-type target | '<32-hex targetId>' -> exact target by id | 'index:N' -> Nth page-type target (0-based) | 'url:<substring>' -> first page whose url contains substring | 'title:<substring>' -> first page whose title contains substring | 'label:<name>' -> the page-type target with exactly this label (checked against the origin ledger and live leases) | 'worker:<substring>' -> a service/shared worker whose url contains the substring, which is how you reach an MV3 extension's background service worker (worker:<extension-id> or worker:background.js) and read chrome.storage.local from it. The worker: arm is CHROME-ONLY (Capability 'worker.targets') and is accepted by four tools only — evaluate_script, list_network_requests, get_network_request and list_console_messages — never as universal grammar; an MV3 worker that has been idle-evicted is started automatically first, see 'wake'."
+        },
+        "wake": {
+          "type": "boolean",
+          "description": "Only valid with a 'worker:<substring>' target, and rejected on a page target rather than ignored. Default true: an MV3 extension service worker is idle-evicted after seconds of inactivity and then exists in NO target listing, so a wake asks Chrome to start it (ServiceWorker.startWorker over a page session) and then re-reads the target list to confirm it actually came up. Pass false to fail fast instead of starting anything; the error then says the worker may simply be asleep."
         },
         "expression": {
           "type": "string",
-          "description": "JavaScript to run. Evaluated as an expression when 'args' is omitted; must be a function literal (arrow or classic) whose parameters receive 'args' when 'args' is provided."
+          "description": "JavaScript to run. Evaluated as an expression when 'args' is omitted; must be a function literal (arrow or classic) whose parameters receive 'args' when 'args' is provided. REQUIRED — the code always goes in this key, never in 'function', 'code', 'js', 'script', 'fn' or 'body'; a call using one of those instead is rejected with an error naming the wrong key."
         },
         "awaitPromise": {
           "type": "boolean",
@@ -251,7 +255,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
+          "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>'."
         },
         "domain": {
           "type": "string",
@@ -282,7 +286,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
+          "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>'."
         },
         "name": {
           "type": "string",
@@ -338,7 +342,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
+          "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>'."
         },
         "name": {
           "type": "string",
@@ -373,7 +377,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default, = first page-type target) | 'index:N' (Nth page-type target, 0-based) | 'url:<substring>' | 'title:<substring>' | '<32-hex targetId>' (exact target by id)."
+          "description": "Target page selector: 'active' (default, = first page-type target) | 'index:N' (Nth page-type target, 0-based) | 'url:<substring>' | 'title:<substring>' | 'label:<name>' (exact label match, origin ledger or live lease) | '<32-hex targetId>' (exact target by id)."
         },
         "interactiveOnly": {
           "type": "boolean",
@@ -396,7 +400,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         "uid": {
           "type": "number",
@@ -449,7 +453,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         "uid": {
           "type": "number",
@@ -476,7 +480,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         "from": {
           "type": "object",
@@ -562,7 +566,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         "uid": {
           "type": "number",
@@ -605,7 +609,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         "action": {
           "type": "string",
@@ -671,7 +675,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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."
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<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",
@@ -698,7 +702,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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."
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'. Used for the lease check and, when 'origin' is omitted, as the source of the origin to grant for."
         },
         "permissions": {
           "type": "array",
@@ -732,7 +736,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         "uid": {
           "type": "number",
@@ -765,7 +769,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         "fields": {
           "type": "array",
@@ -811,7 +815,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         "uid": {
           "type": "number",
@@ -844,7 +848,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         "key": {
           "type": "string",
@@ -876,7 +880,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         "uid": {
           "type": "number",
@@ -915,7 +919,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector. undefined or 'active' -> first page target; '<32-hex targetId>' -> exact target by id; 'index:N' -> Nth page target (0-based); 'url:<substring>' -> first page whose url contains substring; 'title:<substring>' -> first page whose title contains substring."
+          "description": "Target page selector. undefined or 'active' -> first page target; '<32-hex targetId>' -> exact target by id; 'index:N' -> Nth page target (0-based); 'url:<substring>' -> first page whose url contains substring; 'title:<substring>' -> first page whose title contains substring; 'label:<name>' -> the page with exactly this label (origin ledger or live lease)."
         },
         "format": {
           "type": "string",
@@ -966,7 +970,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         "width": {
           "type": "number",
@@ -1066,7 +1070,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         "width": {
           "type": "number",
@@ -1104,7 +1108,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (or omitted) for the first page-type target | 'index:N' (0-based) | 'url:<substring>' | 'title:<substring>' | a 32-hex <targetId>."
+          "description": "Target page selector: 'active' (or omitted) for the first page-type target | 'index:N' (0-based) | 'url:<substring>' | 'title:<substring>' | 'label:<name>' (exact label match, origin ledger or live lease) | a 32-hex <targetId>."
         },
         "accept": {
           "type": "boolean",
@@ -1131,7 +1135,7 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "name": "list_console_messages",
-    "description": "Read console output (logs, warnings, exceptions) captured for the target page. By default reads the target's existing shared buffer and returns parsed console entries (empty if no capture has run); with reload:true it reloads the page and records a fresh capture window (both console+network) so a network reload never wipes console history.",
+    "description": "Read console output (logs, warnings, exceptions) captured for the target page. By default reads the target's existing shared buffer and returns parsed console entries (empty if no capture has run); with reload:true it reloads the page and records a fresh capture window (both console+network) so a network reload never wipes console history. SERVICE WORKERS (Chrome only, Capability 'worker.targets'): pass target 'worker:<extension-id>' to watch an MV3 extension's BACKGROUND SERVICE WORKER. The outbound request that worker makes to your backend is recorded from CDP's Network domain on the worker's own session, which observes what the code ACTUALLY SENT and so needs neither of the two tricks a caller reaches for first. Both of those fail for ordinary JavaScript reasons rather than service-worker ones: a value bound at module top level is not visible from evaluate_script's global scope (plain lexical scoping, exactly the same in a page), and assigning self.fetch cannot rebind a fetch reference the module already captured. A worker's console.log arrives as Runtime.consoleAPICalled on its own session. A worker capture has no reload to drive it: reload:true means 'listen for durationMs while the worker runs', so trigger the worker's work (another tool call, an extension message, an alarm) during the window; a worker woken by the call has already run its top-level code by the time the recorder attaches, so a request it makes at startup can be missed. SIDE EFFECT, deliberate and documented: the recording holds a CDP session on the worker, and that KEEPS THE WORKER ALIVE for as long as the capture runs — an MV3 worker is otherwise idle-evicted within seconds — and Chrome resumes evicting it once the capture stops.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -1141,15 +1145,19 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
+          "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>' | 'worker:<substring>' -> a service/shared worker whose url contains the substring, which is how you reach an MV3 extension's background service worker (worker:<extension-id> or worker:background.js). The worker: arm is CHROME-ONLY (Capability 'worker.targets'), is refused on Firefox, and a bare worker target id works too."
         },
         "reload": {
           "type": "boolean",
-          "description": "Record fresh by reloading the page and capturing for a window. Default false (read the existing buffer)."
+          "description": "Record fresh by reloading the page and capturing for a window. Default false (read the existing buffer). With a worker: target there is nothing to reload: the window records for durationMs while the worker runs, and the session it holds keeps that worker from being idle-evicted until the capture stops."
         },
         "durationMs": {
           "type": "number",
           "description": "Capture window for reload mode, in milliseconds. Default 2500."
+        },
+        "wake": {
+          "type": "boolean",
+          "description": "Worker targets only, and only when a capture is being started (reload:true). Default true: an MV3 extension service worker is idle-evicted after seconds of inactivity and then exists in NO target listing, so the capture asks Chrome to start it (ServiceWorker.startWorker over a page session) and then re-reads the target list to confirm it actually came up. Pass false to fail fast instead of starting anything. Rejected rather than ignored on a page target, on a bare target id (Chrome re-mints a worker's target id when it restarts, so only the url-substring form can name a worker that is not running), and on a read-only call (the buffer is keyed by target id, so a woken worker's buffer would be empty)."
         }
       },
       "required": [],
@@ -1168,7 +1176,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
+          "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>'."
         },
         "index": {
           "type": "number",
@@ -1181,7 +1189,7 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "name": "list_network_requests",
-    "description": "Return correlated network request rows (one per requestId, with status/headers/state) for the target page. By default reads the target's existing buffer; with reload:true it reloads and records a fresh both-domains capture window. Use filterUrl to keep only requests whose URL contains a substring.",
+    "description": "Return correlated network request rows (one per requestId, with status/headers/state) for the target page. By default reads the target's existing buffer; with reload:true it reloads and records a fresh both-domains capture window. Use filterUrl to keep only requests whose URL contains a substring. SERVICE WORKERS (Chrome only, Capability 'worker.targets'): pass target 'worker:<extension-id>' to watch an MV3 extension's BACKGROUND SERVICE WORKER. The outbound request that worker makes to your backend is recorded from CDP's Network domain on the worker's own session, which observes what the code ACTUALLY SENT and so needs neither of the two tricks a caller reaches for first. Both of those fail for ordinary JavaScript reasons rather than service-worker ones: a value bound at module top level is not visible from evaluate_script's global scope (plain lexical scoping, exactly the same in a page), and assigning self.fetch cannot rebind a fetch reference the module already captured. A worker capture has no reload to drive it: reload:true means 'listen for durationMs while the worker runs', so trigger the worker's work (another tool call, an extension message, an alarm) during the window; a worker woken by the call has already run its top-level code by the time the recorder attaches, so a request it makes at startup can be missed. SIDE EFFECT, deliberate and documented: the recording holds a CDP session on the worker, and that KEEPS THE WORKER ALIVE for as long as the capture runs — an MV3 worker is otherwise idle-evicted within seconds — and Chrome resumes evicting it once the capture stops.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -1191,11 +1199,11 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
+          "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>' | 'worker:<substring>' -> a service/shared worker whose url contains the substring, which is how you reach an MV3 extension's background service worker (worker:<extension-id> or worker:background.js). The worker: arm is CHROME-ONLY (Capability 'worker.targets'), is refused on Firefox, and a bare worker target id works too."
         },
         "reload": {
           "type": "boolean",
-          "description": "Record fresh by reloading the page and capturing for a window. Default false (read the existing buffer)."
+          "description": "Record fresh by reloading the page and capturing for a window. Default false (read the existing buffer). With a worker: target there is nothing to reload: the window records for durationMs while the worker runs, and the session it holds keeps that worker from being idle-evicted until the capture stops."
         },
         "durationMs": {
           "type": "number",
@@ -1204,6 +1212,10 @@ export const MANIFEST: ToolSpec[] = [
         "filterUrl": {
           "type": "string",
           "description": "Only return requests whose URL contains this substring."
+        },
+        "wake": {
+          "type": "boolean",
+          "description": "Worker targets only, and only when a capture is being started (reload:true). Default true: an MV3 extension service worker is idle-evicted after seconds of inactivity and then exists in NO target listing, so the capture asks Chrome to start it (ServiceWorker.startWorker over a page session) and then re-reads the target list to confirm it actually came up. Pass false to fail fast instead of starting anything. Rejected rather than ignored on a page target, on a bare target id (Chrome re-mints a worker's target id when it restarts, so only the url-substring form can name a worker that is not running), and on a read-only call (the buffer is keyed by target id, so a woken worker's buffer would be empty)."
         }
       },
       "required": [],
@@ -1212,7 +1224,7 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "name": "get_network_request",
-    "description": "Return one network request (matched by exact requestId, else by url substring) including status/headers. Requires at least one of requestId or url (throws otherwise). With includeBody:true the body fetch drives a fresh reload capture and is matched by url ONLY (reload re-mints requestIds, so a carried-over requestId cannot fetch a body, so it returns metadata plus bodyUnavailableReason).",
+    "description": "Return one network request (matched by exact requestId, else by url substring) including status/headers. Requires at least one of requestId or url (throws otherwise). With includeBody:true the body fetch drives a fresh capture (a reload for a page, a listen window for a worker) and is matched by url ONLY (a fresh capture re-mints requestIds, so a carried-over requestId cannot fetch a body, so it returns metadata plus bodyUnavailableReason). SERVICE WORKERS (Chrome only, Capability 'worker.targets'): pass target 'worker:<extension-id>' to watch an MV3 extension's BACKGROUND SERVICE WORKER. The outbound request that worker makes to your backend is recorded from CDP's Network domain on the worker's own session, which observes what the code ACTUALLY SENT and so needs neither of the two tricks a caller reaches for first. Both of those fail for ordinary JavaScript reasons rather than service-worker ones: a value bound at module top level is not visible from evaluate_script's global scope (plain lexical scoping, exactly the same in a page), and assigning self.fetch cannot rebind a fetch reference the module already captured. A worker capture has no reload to drive it: reload:true means 'listen for durationMs while the worker runs', so trigger the worker's work (another tool call, an extension message, an alarm) during the window; a worker woken by the call has already run its top-level code by the time the recorder attaches, so a request it makes at startup can be missed. SIDE EFFECT, deliberate and documented: the recording holds a CDP session on the worker, and that KEEPS THE WORKER ALIVE for as long as the capture runs — an MV3 worker is otherwise idle-evicted within seconds — and Chrome resumes evicting it once the capture stops.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -1222,7 +1234,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
+          "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>' | 'worker:<substring>' -> a service/shared worker whose url contains the substring, which is how you reach an MV3 extension's background service worker (worker:<extension-id> or worker:background.js). The worker: arm is CHROME-ONLY (Capability 'worker.targets'), is refused on Firefox, and a bare worker target id works too."
         },
         "requestId": {
           "type": "string",
@@ -1239,6 +1251,10 @@ export const MANIFEST: ToolSpec[] = [
         "durationMs": {
           "type": "number",
           "description": "Capture window for the reload-driven body fetch, in milliseconds. Default 2500."
+        },
+        "wake": {
+          "type": "boolean",
+          "description": "Worker targets only, and only when a capture is being started (includeBody together with url). Default true: an MV3 extension service worker is idle-evicted after seconds of inactivity and then exists in NO target listing, so the capture asks Chrome to start it (ServiceWorker.startWorker over a page session) and then re-reads the target list to confirm it actually came up. Pass false to fail fast instead of starting anything. Rejected rather than ignored on a page target, on a bare target id (Chrome re-mints a worker's target id when it restarts, so only the url-substring form can name a worker that is not running), and on a read-only call (the buffer is keyed by target id, so a woken worker's buffer would be empty)."
         }
       },
       "required": [],
@@ -1257,7 +1273,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         "categories": {
           "type": "array",
@@ -1283,7 +1299,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         }
       },
       "required": [],
@@ -1321,7 +1337,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         "durationMs": {
           "type": "number",
@@ -1359,7 +1375,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         "format": {
           "type": "string",
@@ -1406,7 +1422,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Which recording to stop: 'active' (default, valid only when exactly one recording is in flight) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          "description": "Which recording to stop: 'active' (default, valid only when exactly one recording is in flight) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         "savePath": {
           "type": "string",
@@ -1429,7 +1445,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         "savePath": {
           "type": "string",
@@ -1496,7 +1512,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target selector: active | index:N | url:<substr> | title:<substr> | <targetId>. Defaults to the active page."
+          "description": "Target selector: active | index:N | url:<substr> | title:<substr> | label:<name> | <targetId>. Defaults to the active page."
         },
         "urlPattern": {
           "type": "string",
@@ -1604,7 +1620,7 @@ export const MANIFEST: ToolSpec[] = [
       "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."
+          "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> | label:<name> | <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",
@@ -1639,7 +1655,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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."
+          "description": "Target selector for a tab this process holds: active | index:N | url:<substr> | title:<substr> | label:<name> | <targetId>. Mutually exclusive with 'lease'. Refused if another process holds the tab."
         },
         "close": {
           "type": "boolean",

package/src/mcp.ts

@@ -24,7 +24,7 @@ import { toolAvailability } from "./capabilities.ts";
 import { FIREFOX_TOOLS } from "./firefox-tools.ts";
 import { leaseFromArgs, markLongLivedProcess, withLeaseScope } from "./leases.ts";
 
-const VERSION = "1.8.0";
+const VERSION = "1.9.1";
 
 // --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).

package/src/origins.ts

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