cdp-toolkit 1.8.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdp-toolkit",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "A lightweight chrome-devtools-mcp alternative: an MCP server + CLI that drives the tabs you name, one target per call over one direct WebSocket, with a bounded timeout on every call, so a stuck page can't wedge your agent or force a /mcp restart. Chrome over CDP and Firefox over WebDriver BiDi, with tools a backend can't run absent from tools/list rather than throwing mid-task. 45 tools including built-in network mocking, a cookie group, tab leases with human-activity detection, real HTML5 drag-and-drop, raw mouse/scroll dispatch, downloads, permission grants, and tab-to-video screen recording so several agents can drive one browser without stealing each other's tabs or a human's. No Puppeteer, no all-target fan-out.",
   "type": "module",
   "license": "MIT",
@@ -80,7 +80,8 @@
     "firefox:smoke": "bun run ./test/firefox-smoke.ts",
     "lease:smoke": "bun run ./test/lease-smoke.ts",
     "staleness:smoke": "bun run ./test/staleness-smoke.ts",
-    "input:smoke": "bun run ./test/input-smoke.ts"
+    "input:smoke": "bun run ./test/input-smoke.ts",
+    "extension:smoke": "bun run ./test/extension-smoke.ts"
   },
   "devDependencies": {
     "@types/node": "22.10.10",

package/src/bidi/driver.ts

@@ -33,6 +33,8 @@ import {
   type ScreenshotOptions, type ScrollOptions, type SnapshotNode, type UidStability,
 } from "../driver.ts";
 import { assertLeaseOk } from "../leases.ts";
+import { resolveLiveLabel } from "../origins.ts";
+import { isWorkerSelector, WORKER_SELECTOR_UNSUPPORTED_MESSAGE } from "../workers.ts";
 import { BEACON_FUNCTION_DECLARATION, BEACON_READ_EXPRESSION, BEACON_SOURCE, recordDispatch } from "../activity.ts";
 import { BidiConnection, BidiError, connectBidiSession } from "./client.ts";
 import { takeStampedSnapshot } from "./snapshot.ts";
@@ -384,6 +386,32 @@ async function pickContext(
     for (const c of contexts) if ((await safeTitle(conn, c.context)).includes(needle)) return c;
     throw driverError("no-such-target", `no context with title containing '${needle}'`);
   }
+  if (selector.startsWith("label:")) {
+    const label = selector.slice(6);
+    const { matchIds, knownLabels } = await resolveLiveLabel("firefox", label, contexts.map((c) => c.context));
+    if (matchIds.length > 1) {
+      throw driverError("no-such-target", `label 'label:${label}' matches more than one live target: ${matchIds.join(", ")}. Resolve by target id instead.`);
+    }
+    if (matchIds.length === 1) {
+      const hit = contexts.find((c) => c.context === matchIds[0]);
+      if (hit) return hit;
+    }
+    throw driverError(
+      "no-such-target",
+      knownLabels.length
+        ? `no live target with label '${label}' (labels currently in use: ${knownLabels.join(", ")})`
+        : `no live target with label '${label}' (no labels are currently assigned to any open target)`,
+    );
+  }
+  if (isWorkerSelector(selector)) {
+    // Capability-gated, not unimplemented: "unsupported" is the DriverErrorCode
+    // that tells a caller to check the capability rather than retry. The tool
+    // itself stays available on Firefox — only this arm of the grammar is
+    // refused, exactly as drag's mode:'html5' is. Refusing loudly beats the
+    // alternative the bare-id fall-through would produce, which is a confusing
+    // "no context matching 'worker:abc'" that reads like a typo.
+    throw driverError("unsupported", WORKER_SELECTOR_UNSUPPORTED_MESSAGE);
+  }
   const exact = contexts.find((c) => c.context === selector);
   if (exact) return exact;
   throw driverError("no-such-target", `no context matching '${selector}'`);

package/src/cdp/driver.ts

@@ -10,6 +10,7 @@ import type { Target, TargetSelector } from "../types.ts";
 import { LeaseConflictError } from "../leases.ts";
 import { BEACON_READ_EXPRESSION, BEACON_SOURCE, BeaconSessions, RENDERER_PROBE_EXPRESSION, RENDERER_PROBE_TIMEOUT_MS, sendInput } from "../activity.ts";
 import { resolveUid } from "../tools/snapshot.ts";
+import { resolveWorkerSelector } from "./workers.ts";
 import { buildFulfillParams, effectiveAction, selectRule } from "../tools/network_mock.ts";
 import {
   LEGACY_NUMERIC_UID, interpolatePoints, type BrowserCookie, type BrowserDriver, type Capability, type DeleteCookiesFilter, type HandledDialogInfo, type DriverError, type DriverErrorCode, type DriverEvent,
@@ -348,7 +349,7 @@ const CDP_CAPABILITIES: ReadonlySet<Capability> = new Set<Capability>([
   "screenshot.fullPage", "screenshot.element", "network.intercept",
   "snapshot.accessibilityTree", "input.insertTextAtomic", "locate.text", "locate.xpath",
   "capture.screencast", "input.raw", "input.html5Drag",
-  "browser.downloads", "browser.permissions",
+  "browser.downloads", "browser.permissions", "worker.targets",
 ]);
 /* ---------------------------------- PageDriver ---------------------------------- */
 class CdpPageDriver implements PageDriver {
@@ -1106,6 +1107,20 @@ class CdpBrowserDriver implements BrowserDriver {
     await withBrowserConn((conn) => conn.send("Target.activateTarget", { targetId: target.id }));
     return { id: target.id, url: target.url, title: target.title };
   }
+  /**
+   * Capability "worker.targets". Resolution and the wake live in ./workers.ts;
+   * this is the driver-shaped door onto them.
+   *
+   * The catch is noSuchTarget for the same reason page() uses it: a genuine
+   * "nothing matched" is a CdpError (numeric code) and must surface as a
+   * `no-such-target` DriverError, while a typed error from underneath — a lease
+   * conflict, an fs errno — passes through with its class intact. The teaching
+   * text in the miss message is the CdpError's message and survives relabeling.
+   */
+  async resolveWorkerTarget(selector: string, opts: { wake: boolean }): Promise<PageInfo> {
+    const target = await resolveWorkerSelector(selector, opts).catch(noSuchTarget);
+    return { id: target.id, url: target.url, title: target.title, type: target.type };
+  }
   async page(selector: TargetSelector): Promise<PageDriver> {
     const { conn, target } = await openPage(selector).catch(noSuchTarget);
     // Deliberately NOT enabling ANY domain here (previously eagerly enabled Page+Runtime on every

package/src/cdp/workers.ts

@@ -0,0 +1,177 @@
+/**
+ * Chrome-only: resolving a "worker:<substring>" selector, including WAKING an
+ * idle-evicted MV3 service worker so there is something to resolve.
+ *
+ * EVERY PROTOCOL CHOICE BELOW WAS MEASURED against Chrome 151.0.7922.109 for
+ * 1.9.0, because the obvious ones are wrong:
+ *
+ *  1. `ServiceWorker.enable` and `ServiceWorker.startWorker` DO NOT EXIST on the
+ *     browser endpoint — both answer `-32601 wasn't found` there. The domain is
+ *     reachable only over a session attached to a PAGE target. Any page works;
+ *     a plain `about:blank` tab hosted the wake in the probe, so no page on the
+ *     extension's own origin is needed. That is why this opens a browser
+ *     connection and then attaches a flattened session to some page, rather
+ *     than talking to the browser endpoint directly.
+ *
+ *  2. A STOPPED worker is not a target. It is absent from `/json/list` and from
+ *     `Target.getTargets` under every filter tried (including an explicit
+ *     all-types filter, and after `Target.setDiscoverTargets`). The ONLY place a
+ *     stopped worker is visible is the registration inventory that
+ *     `ServiceWorker.enable` pushes as `workerRegistrationUpdated` /
+ *     `workerVersionUpdated`. So matching a substring against a sleeping worker
+ *     means matching against those events, not against a target list.
+ *
+ *  3. `ServiceWorker.startWorker` RETURNS EMPTY SUCCESS FOR A SCOPE THAT DOES
+ *     NOT EXIST — a completely invented `chrome-extension://aaaa.../` scope
+ *     answers `{}` exactly like a real one. Its result is therefore worthless as
+ *     evidence, and nothing here reports a wake on the strength of it: the
+ *     caller re-reads the target list and only a worker that actually shows up
+ *     counts. This is the one dishonesty the feature could most easily ship.
+ *
+ * WHY THE CONNECTION IS ALWAYS CLOSED IN A `finally`. Two reasons, and the
+ * second is not obvious: a leaked socket keeps the process alive (the standing
+ * harness rule), AND an attached CDP session KEEPS A SERVICE WORKER FROM BEING
+ * EVICTED. A connection left open here would suppress the very eviction this
+ * module exists to recover from, so the leak would hide itself.
+ */
+import { CdpError, listTargets, openBrowser } from "../client.ts";
+import type { Target } from "../types.ts";
+import {
+  resolveWorkerTargets,
+  workerAmbiguityMessage,
+  workerMissMessage,
+  workerNeedle,
+  WORKER_EMPTY_NEEDLE_MESSAGE,
+} from "../workers.ts";
+
+/** Bounded wait for the first inventory event after ServiceWorker.enable. A
+ *  browser with no registrations at all never sends one, so this must time out
+ *  rather than hang; the settle that follows collects the rest of the batch. */
+const INVENTORY_FIRST_EVENT_MS = 1_500;
+const INVENTORY_SETTLE_MS = 250;
+/** Wake poll budget: 30 x 300ms = 9s. The probe saw a worker reappear in well
+ *  under 2s; the headroom is for a cold worker whose top-level code does work. */
+const WAKE_POLL_MS = 300;
+const WAKE_POLL_ATTEMPTS = 30;
+
+const NO_HOST_PAGE_MESSAGE =
+  "cannot start a service worker: the ServiceWorker CDP domain is only reachable over a page session, " +
+  "and this browser has no page target open. Open any tab (new_page) and retry — the tab does not have " +
+  "to belong to the extension.";
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+interface RegistrationEvent {
+  registrationId?: unknown;
+  scopeURL?: unknown;
+  isDeleted?: unknown;
+}
+interface VersionEvent {
+  registrationId?: unknown;
+  scriptURL?: unknown;
+  runningStatus?: unknown;
+}
+
+export interface WorkerStartAttempt {
+  /** True only when a matching registration was found AND a start was issued.
+   *  Says nothing about whether the worker actually came up: see fact 3. */
+  startRequested: boolean;
+  /** Every registered scope this browser reported, for the miss message. */
+  scopes: string[];
+}
+
+/**
+ * Read the service-worker registration inventory and, when exactly one
+ * registration matches `needle`, ask Chrome to start it.
+ *
+ * Matching is against the version's scriptURL OR the registration's scopeURL,
+ * so both `worker:<extension-id>` (which appears in both) and
+ * `worker:background.js` (which appears only in the scriptURL) resolve.
+ */
+export async function requestWorkerStart(needle: string): Promise<WorkerStartAttempt> {
+  const conn = await openBrowser();
+  try {
+    const host = (await listTargets()).find((t) => t.type === "page");
+    if (!host) throw new CdpError(NO_HOST_PAGE_MESSAGE);
+    const { sessionId } = await conn.send<{ sessionId?: string }>("Target.attachToTarget", {
+      targetId: host.id,
+      flatten: true,
+    });
+    if (!sessionId) throw new CdpError("could not attach a session to host the ServiceWorker domain");
+
+    const scopeById = new Map<string, string>();
+    const versions: Array<{ registrationId: string; scriptURL: string }> = [];
+    conn.on("ServiceWorker.workerRegistrationUpdated", (params) => {
+      for (const r of (params.registrations as RegistrationEvent[] | undefined) ?? []) {
+        if (r.isDeleted === true) continue;
+        scopeById.set(String(r.registrationId), String(r.scopeURL ?? ""));
+      }
+    });
+    conn.on("ServiceWorker.workerVersionUpdated", (params) => {
+      for (const v of (params.versions as VersionEvent[] | undefined) ?? []) {
+        versions.push({ registrationId: String(v.registrationId), scriptURL: String(v.scriptURL ?? "") });
+      }
+    });
+
+    await conn.send("ServiceWorker.enable", {}, { sessionId });
+    // The inventory arrives as events AFTER the enable response, so waiting on
+    // the response alone would read an empty map every time.
+    await conn.waitFor("ServiceWorker.workerVersionUpdated", undefined, INVENTORY_FIRST_EVENT_MS).catch(() => undefined);
+    await sleep(INVENTORY_SETTLE_MS);
+
+    const scopes = [...new Set(scopeById.values())].filter((s) => s.length > 0).sort();
+    const matched = new Set<string>();
+    for (const v of versions) {
+      const scope = scopeById.get(v.registrationId);
+      if (scope === undefined) continue;
+      if (v.scriptURL.includes(needle) || scope.includes(needle)) matched.add(scope);
+    }
+    if (matched.size === 0) return { startRequested: false, scopes };
+    if (matched.size > 1) {
+      throw new CdpError(
+        `'worker:${needle}' matches more than one registered service-worker scope: ${[...matched].sort().join(", ")}. ` +
+          "Narrow the substring.",
+      );
+    }
+    await conn.send("ServiceWorker.startWorker", { scopeURL: [...matched][0]! }, { sessionId });
+    return { startRequested: true, scopes };
+  } finally {
+    // See the header: a held session also suppresses eviction.
+    conn.close();
+  }
+}
+
+/**
+ * Resolve a `worker:<substring>` selector to a live worker target, waking an
+ * evicted worker first when `wake` is true (the default at the tool surface).
+ *
+ * The wake path is: match running targets -> nothing -> ask for a start ->
+ * RE-READ THE TARGET LIST until the worker appears or the budget runs out.
+ * The re-read is the only evidence accepted that a wake happened.
+ */
+export async function resolveWorkerSelector(selector: string, opts: { wake: boolean }): Promise<Target> {
+  const needle = workerNeedle(selector);
+  if (needle === "") throw new CdpError(WORKER_EMPTY_NEEDLE_MESSAGE);
+
+  const first = resolveWorkerTargets(await listTargets(), needle);
+  if (first.matches.length > 1) throw new CdpError(workerAmbiguityMessage(needle, first.matches));
+  if (first.matches.length === 1) return first.matches[0]!;
+
+  if (!opts.wake) {
+    throw new CdpError(workerMissMessage(needle, { wakeAttempted: false, liveWorkers: first.liveWorkers }));
+  }
+
+  const { startRequested, scopes } = await requestWorkerStart(needle);
+  if (startRequested) {
+    for (let i = 0; i < WAKE_POLL_ATTEMPTS; i++) {
+      await sleep(WAKE_POLL_MS);
+      const again = resolveWorkerTargets(await listTargets(), needle);
+      if (again.matches.length > 1) throw new CdpError(workerAmbiguityMessage(needle, again.matches));
+      if (again.matches.length === 1) return again.matches[0]!;
+    }
+  }
+  const final = resolveWorkerTargets(await listTargets(), needle);
+  throw new CdpError(
+    workerMissMessage(needle, { wakeAttempted: true, liveWorkers: final.liveWorkers, registeredScopes: scopes }),
+  );
+}

package/src/cli.ts

@@ -48,7 +48,9 @@ Backend selection: --browser chrome|firefox, else the CDP_BROWSER env var, else
 zero behavior change for existing users). Firefox is LAUNCHED per invocation (it cannot be attached
 to), used for exactly one tool call, then disposed before the process exits.
 
-Target selector grammar: active | index:N | url:<substr> | title:<substr> | <targetId>
+Target selector grammar: active | index:N | url:<substr> | title:<substr> | label:<name> | <targetId>
+  plus worker:<substr> for evaluate_script ONLY (Chrome only): an MV3 extension's background service
+  worker, e.g. worker:<extension-id>. An idle-evicted worker is started first unless wake:false.
 Leases: pass --lease <token> to act on a tab another agent claimed with claim_page (MCP only).
 Run list_leases to see who holds what; release_page --lease <token> gives a lease back.
 Run with --list to print every tool name available under the selected backend.

package/src/client.ts

@@ -5,6 +5,16 @@
  */
 import type { CdpResponse, Target, TargetSelector } from "./types.ts";
 import { assertLeaseOk } from "./leases.ts";
+import { resolveLiveLabel } from "./origins.ts";
+import {
+  isWorkerSelector,
+  isWorkerTargetType,
+  resolveWorkerTargets,
+  workerAmbiguityMessage,
+  workerMissMessage,
+  workerNeedle,
+  WORKER_EMPTY_NEEDLE_MESSAGE,
+} from "./workers.ts";
 
 /** Base HTTP origin of the DevTools endpoint. Override with CDP_BASE. */
 export const BASE = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
@@ -197,7 +207,19 @@ export async function browserWsUrl(): Promise<string> {
  *  the ambient lease scope instead (see leases.ts). */
 export async function resolveTarget(selector: TargetSelector, opts: { lease?: string } = {}): Promise<Target> {
   const targets = await listTargets();
-  const hit = pickTarget(targets, selector);
+  const hit = await pickTarget(targets, selector);
+  // WORKER TARGETS BYPASS THE LEASE GATE ENTIRELY, and that is a decision, not
+  // an omission. A lease answers "who is driving this TAB", and every
+  // consequence of holding one is a tab consequence: reap CLOSES an abandoned
+  // leased tab, and "close the stale tab" is meaningless for a service worker
+  // that Chrome starts and stops on its own schedule (see ReapInput.livePageIds,
+  // which is deliberately fed the page-only listing for exactly this reason).
+  // Letting strict mode auto-acquire here would mint a lease file per worker
+  // evaluate, keyed on an id that vanishes the moment the worker idles out —
+  // garbage that the page-only reap set can never collect. It also cannot be
+  // used to sneak past a lease: a worker is not a tab, so there is no tab
+  // someone else holds that this could reach.
+  if (isWorkerTargetType(hit.type)) return hit;
   // THE Chrome choke point. Every tool reaches a page through here, so a tool
   // added after this shipped is protected with no action from its author.
   //
@@ -211,7 +233,7 @@ export async function resolveTarget(selector: TargetSelector, opts: { lease?: st
   return hit;
 }
 
-function pickTarget(targets: Target[], selector: TargetSelector): Target {
+async function pickTarget(targets: Target[], selector: TargetSelector): Promise<Target> {
   const pages = targets.filter((t) => t.type === "page");
   if (!selector || selector === "active") {
     if (!pages.length) throw new CdpError("no page targets open");
@@ -234,6 +256,34 @@ function pickTarget(targets: Target[], selector: TargetSelector): Target {
     if (!hit) throw new CdpError(`no page title containing '${needle}'`);
     return hit;
   }
+  if (selector.startsWith("label:")) {
+    const label = selector.slice(6);
+    const { matchIds, knownLabels } = await resolveLiveLabel("chrome", label, pages.map((t) => t.id));
+    if (matchIds.length > 1) {
+      throw new CdpError(`label 'label:${label}' matches more than one live target: ${matchIds.join(", ")}. Resolve by target id instead.`);
+    }
+    if (matchIds.length === 1) {
+      const hit = pages.find((t) => t.id === matchIds[0]);
+      if (hit) return hit;
+    }
+    throw new CdpError(
+      knownLabels.length
+        ? `no live target with label '${label}' (labels currently in use: ${knownLabels.join(", ")})`
+        : `no live target with label '${label}' (no labels are currently assigned to any open target)`,
+    );
+  }
+  if (isWorkerSelector(selector)) {
+    // Resolved against the UNFILTERED listing, never `pages`: a worker is not a
+    // page target and would not be in it. Waking an evicted worker is NOT done
+    // here — this stays a pure pick over what the browser already reports, and
+    // the wake path lives in cdp/workers.ts, reached only from evaluate_script.
+    const needle = workerNeedle(selector);
+    if (needle === "") throw new CdpError(WORKER_EMPTY_NEEDLE_MESSAGE);
+    const { matches, liveWorkers } = resolveWorkerTargets(targets, needle);
+    if (matches.length > 1) throw new CdpError(workerAmbiguityMessage(needle, matches));
+    if (matches.length === 1) return matches[0]!;
+    throw new CdpError(workerMissMessage(needle, { wakeAttempted: false, liveWorkers }));
+  }
   // bare id
   const byId = targets.find((t) => t.id === selector);
   if (!byId) throw new CdpError(`no target with id '${selector}'`);

package/src/driver.ts

@@ -142,7 +142,8 @@ export type Capability =
   | "input.raw" // raw single mouse-event dispatch (dispatch_mouse's move/down/up primitive); Chrome only
   | "input.html5Drag" // real HTML5 drag events (drag's mode:"html5"); Chrome only, see PageDriver.drag
   | "browser.downloads" // capture a file download to a known path (wait_for_download); Chrome only
-  | "browser.permissions"; // grant/reset browser permissions for an origin (grant_permissions); Chrome only
+  | "browser.permissions" // grant/reset browser permissions for an origin (grant_permissions); Chrome only
+  | "worker.targets"; // address a service/shared worker as a target ("worker:<substr>"), incl. waking an evicted MV3 worker; Chrome only
 
 /**
  * Tools whose availability depends on a capability. A tool absent from this
@@ -563,6 +564,31 @@ export interface BrowserDriver {
    */
   probeRenderer?(targetId: string, timeoutMs?: number): Promise<{ responsive: boolean; beaconTs: number | null }>;
 
+  /**
+   * Resolve a "worker:<substring>" selector to a concrete service/shared-worker
+   * target, STARTING an idle-evicted MV3 service worker first when `wake` is
+   * true. The returned PageInfo's id is a plain target id, so the caller then
+   * acquires it through the ordinary page() path.
+   *
+   * OPTIONAL **and** gated by Capability "worker.targets", unlike
+   * installActivityBeacon / readActivityBeacon / probeRenderer, which are
+   * optional but deliberately NOT capabilities. The difference is what a caller
+   * can observe: those three produce an absent FIELD on a result that is
+   * otherwise complete, so silence is the honest answer. This one decides
+   * whether an argument the caller explicitly wrote is honoured, and silently
+   * resolving `worker:...` to something else — or to nothing — would be a wrong
+   * answer rather than a missing annotation. So it refuses out loud, exactly as
+   * drag's mode:'html5' does behind "input.html5Drag" (see resolveDragMode).
+   * No tool is gated out of tools/list: evaluate_script is universal, only this
+   * one arm of its `target` grammar is Chrome-only.
+   *
+   * MUST NOT report a wake it cannot see: an implementation is required to
+   * confirm the worker is back in the target listing rather than trusting the
+   * start command's own result. See cdp/workers.ts for why that is not
+   * paranoia.
+   */
+  resolveWorkerTarget?(selector: string, opts: { wake: boolean }): Promise<PageInfo>;
+
   /** Tear down the transport: process exit (CLI) or shutdown (MCP server).
    *  Idempotent. MUST NOT be called by a tool. */
   dispose(): Promise<void>;

package/src/leases-tools.ts

@@ -73,7 +73,7 @@ export interface ClaimPageResult {
  * path for "work in the tab I have open", which previously had none, because
  * `targetId` demands an exact id a human never has to hand and no id at all
  * meant a brand new tab. `target` takes the toolkit's whole selector grammar
- * (active | index:N | url:<substr> | title:<substr> | <targetId>).
+ * (active | index:N | url:<substr> | title:<substr> | label:<name> | <targetId>).
  *
  * `targetId` is unchanged and still accepted; `target` is the same thing with a
  * grammar, so exactly one of the two may be given.
@@ -123,7 +123,7 @@ export async function claimPage(
   const hasTargetId = typeof args.targetId === "string" && args.targetId.length > 0;
   if (hasTarget && hasTargetId) {
     throw new LeaseToolError(
-      "claim_page takes at most one of 'target' (any selector: active | index:N | url:<substr> | title:<substr> | <targetId>) or 'targetId' (an exact target id, kept for back-compat). Pass 'target' alone to claim an open tab, or neither to open a fresh one.",
+      "claim_page takes at most one of 'target' (any selector: active | index:N | url:<substr> | title:<substr> | label:<name> | <targetId>) or 'targetId' (an exact target id, kept for back-compat). Pass 'target' alone to claim an open tab, or neither to open a fresh one.",
     );
   }
   const backend = backendOf(driver);