cdp-toolkit 1.2.0 → 1.6.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cdp-toolkit",
-  "version": "1.2.0",
-  "description": "A lightweight chrome-devtools-mcp alternative: a single-target MCP server + CLI that drives one tab over a 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. 36 tools including built-in network mocking. No Puppeteer, no all-target fan-out.",
+  "version": "1.6.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. 41 tools including built-in network mocking, a cookie group, tab leases, and tab-to-video screen recording so several agents can drive one browser without stealing each other's tabs. No Puppeteer, no all-target fan-out.",
   "type": "module",
   "license": "MIT",
   "author": {
@@ -75,8 +75,10 @@
     "test": "bun test",
     "smoke": "bun run ./test/smoke.ts",
     "mock:smoke": "bun run ./test/mock-smoke.ts",
+    "screencast:smoke": "bun run ./test/screencast-smoke.ts",
     "mcp:smoke": "bun run ./test/mcp-smoke.ts",
-    "firefox:smoke": "bun run ./test/firefox-smoke.ts"
+    "firefox:smoke": "bun run ./test/firefox-smoke.ts",
+    "lease:smoke": "bun run ./test/lease-smoke.ts"
   },
   "devDependencies": {
     "@types/node": "22.10.10",

package/src/bidi/driver.ts

@@ -25,7 +25,8 @@
 import type { TargetSelector } from "../types.ts";
 import {
   UID_STAMP_ATTR, isDriverError,
-  type BrowserDriver, type Capability, type HandledDialogInfo, type DriverError, type DriverErrorCode, type DriverEvent,
+  type BrowserCookie, type BrowserDriver, type Capability, type DeleteCookiesFilter, type HandledDialogInfo, type DriverError, type DriverErrorCode, type DriverEvent,
+  type SetCookieParams,
   type DriverUid, type ElementLocator, type EmulationOptions, type InterceptRule, type KeyPress, type LifetimeModel,
   type MouseButtonOptions, type NavigateOptions, type NavigateResult, type PageDriver, type PageInfo,
   type ScreenshotOptions, type SnapshotNode, type UidStability,
@@ -38,8 +39,60 @@ import type {
   BrowsingContextId, BrowsingContextInfo, BrowsingContextLocator, BrowsingContextReadinessState,
   BrowsingContextCaptureScreenshotParameters, ScriptSharedReference, ScriptRemoteValue, ScriptLocalValue,
   ScriptNodeRemoteValue, ScriptExceptionDetails, InputSourceActions, InputPointerSourceAction, InputKeySourceAction,
+  NetworkCookie,
 } from "./protocol.ts";
 
+/* ---------------------------------- cookies ---------------------------------- */
+/**
+ * BiDi's cookie shape to the neutral one. Three differences to absorb:
+ *  - the value is a network.BytesValue, either a plain string or base64, so a
+ *    base64 one is decoded rather than handed back as opaque base64;
+ *  - `expiry` is optional and simply absent for a session cookie, which becomes
+ *    the neutral -1 that CDP reports directly;
+ *  - `session` has no BiDi field at all, so it is derived from that same
+ *    absence, which is exactly what a session cookie means.
+ * `sameSite` already uses the lowercase vocabulary the neutral shape adopted.
+ */
+export function normalizeBidiCookie(c: NetworkCookie): BrowserCookie {
+  const value = c.value.type === "base64" ? Buffer.from(c.value.value, "base64").toString("utf8") : c.value.value;
+  const hasExpiry = typeof c.expiry === "number";
+  return {
+    name: c.name, value, domain: c.domain, path: c.path,
+    expires: hasExpiry ? (c.expiry as number) : -1,
+    size: typeof c.size === "number" ? c.size : Buffer.byteLength(`${c.name}${value}`, "utf8"),
+    httpOnly: c.httpOnly === true, secure: c.secure === true,
+    sameSite: c.sameSite ?? "default", session: !hasExpiry,
+  };
+}
+
+/**
+ * The host of a url, for the BiDi cookie calls that require a `domain` and have
+ * no `url` parameter of their own.
+ *
+ * Exported so a test can pin the failure cases without a browser. Every branch
+ * that cannot produce a host THROWS: an absent url, an unparseable one, and a
+ * parseable one with an empty host (about:blank, data:, javascript:) all raise
+ * a message naming the tool and what it needs. The alternative, sending the
+ * call without a domain, is a request Firefox answers cleanly while writing or
+ * deleting nothing recognizable, which is the exact wrong-but-plausible ack
+ * this driver refuses to emit.
+ */
+export function hostFromUrl(url: string | undefined, toolName: string): string {
+  if (url === undefined || url === "") {
+    throw driverError("unsupported", `${toolName} on Firefox needs a 'domain': BiDi's storage cookie calls have no 'url' parameter, and no url was given to derive one from.`);
+  }
+  let host = "";
+  try {
+    host = new URL(url).hostname;
+  } catch {
+    throw driverError("unsupported", `${toolName} could not parse the url '${url}' to derive the 'domain' BiDi requires. Pass 'domain' explicitly.`);
+  }
+  if (host === "") {
+    throw driverError("unsupported", `${toolName} cannot derive a 'domain' from '${url}': that url has no host. Pass 'domain' explicitly.`);
+  }
+  return host;
+}
+
 /* ------------------------------ error + uid codec ------------------------------ */
 function driverError(code: DriverErrorCode, message: string, data?: unknown): DriverError {
   return Object.assign(new Error(message), { code, ...(data !== undefined ? { data } : {}) }) as DriverError;
@@ -216,6 +269,10 @@ const BUTTON_CODES: Record<"left" | "right" | "middle", number> = { left: 0, mid
  * supported yet" on real Firefox 153.0.3, contradicting the initial assumption that both text and
  * xpath locators were live; ElementLocator's `text` branch still resolves and correctly surfaces
  * "unsupported" rather than silently misbehaving, it is simply not offered as a capability.
+ * capture.screencast is absent because WebDriver BiDi has no streamed-frame primitive at all:
+ * the spec offers only the one-shot browsingContext.captureScreenshot, with no screencast
+ * start/stop command and no per-repaint frame event to subscribe to, so the screen-recording
+ * pair is honestly missing under Firefox rather than present and throwing.
  * network.intercept rides network.addIntercept + network.beforeRequestSent, verified working
  * (see intercept()'s comment on why urlPatterns is never populated). screenshot.fullPage uses
  * captureScreenshot's origin:"document", screenshot.element uses its clip:{type:"element"}, both verified.
@@ -643,6 +700,88 @@ class BidiPageDriver implements PageDriver {
     return this.handleOneDialog(accept, promptText, opts?.timeoutMs ?? 15_000);
   }
 
+  /**
+   * storage.getCookies, partitioned by THIS browsing context.
+   *
+   * The context partition is the BiDi counterpart of the CDP driver's choice of
+   * the page-scoped Network.getCookies over the browser-wide jar: it asks for
+   * the cookies of the tab that was resolved, not for every cookie the profile
+   * holds. httpOnly cookies are included, since this reads the cookie store
+   * over the protocol rather than evaluating document.cookie in the page.
+   */
+  async getCookies(): Promise<BrowserCookie[]> {
+    try {
+      const { cookies } = await this.conn.send("storage.getCookies", { partition: { type: "context", context: this.contextId } });
+      return (cookies ?? []).map(normalizeBidiCookie);
+    } catch (e) {
+      throw mapBidiError(e);
+    }
+  }
+
+  /**
+   * storage.setCookie, partitioned by THIS browsing context.
+   *
+   * One real difference from CDP to absorb, and it is absorbed EXPLICITLY
+   * rather than papered over: BiDi has no `url` parameter and requires
+   * `domain`, while CDP accepts either and derives the rest from the url. So a
+   * caller who supplied only a url gets its host used as the domain, and a url
+   * with no host (about:blank, a data: URL, a malformed string) throws instead
+   * of being dropped, because a set that silently did nothing is the failure
+   * this tool must never produce.
+   *
+   * Note the derivation is narrower than CDP's: CDP also takes `path` and
+   * `secure` from the url, and this does not, so those stay exactly as the
+   * caller gave them on both backends.
+   */
+  async setCookie(params: SetCookieParams): Promise<void> {
+    const domain = params.domain ?? hostFromUrl(params.url, "set_cookie");
+    try {
+      await this.conn.send("storage.setCookie", {
+        cookie: {
+          name: params.name,
+          value: { type: "string", value: params.value },
+          domain,
+          ...(params.path !== undefined ? { path: params.path } : {}),
+          ...(params.expires !== undefined ? { expiry: params.expires } : {}),
+          ...(params.httpOnly !== undefined ? { httpOnly: params.httpOnly } : {}),
+          ...(params.secure !== undefined ? { secure: params.secure } : {}),
+          ...(params.sameSite !== undefined ? { sameSite: params.sameSite } : {}),
+        },
+        partition: { type: "context", context: this.contextId },
+      });
+    } catch (e) {
+      throw mapBidiError(e);
+    }
+  }
+
+  /**
+   * storage.deleteCookies with a filter, partitioned by THIS browsing context.
+   *
+   * Same url-to-domain derivation as setCookie and for the same reason: the
+   * BiDi filter has `domain` and no `url`, and a filter that quietly dropped
+   * the only site constraint would delete by name across the partition, which
+   * is a bigger deletion than the caller asked for.
+   *
+   * BiDi reports a partitionKey and no count, exactly as CDP reports nothing,
+   * so this returns nothing on both backends rather than one of them inventing
+   * a number the other cannot produce.
+   */
+  async deleteCookies(filter: DeleteCookiesFilter): Promise<void> {
+    const domain = filter.domain ?? hostFromUrl(filter.url, "delete_cookies");
+    try {
+      await this.conn.send("storage.deleteCookies", {
+        filter: {
+          name: filter.name,
+          domain,
+          ...(filter.path !== undefined ? { path: filter.path } : {}),
+        },
+        partition: { type: "context", context: this.contextId },
+      });
+    } catch (e) {
+      throw mapBidiError(e);
+    }
+  }
+
   // Response bodies need network.addDataCollector armed BEFORE the request, per the established
   // fact this driver was handed: no way to read a body for a request that happened before
   // capture was armed. That is the mirror of the CDP driver's own honest omission of

package/src/capabilities.ts

@@ -1,5 +1,5 @@
 /**
- * Per-backend tool availability: filters the 36-tool registry down to what a
+ * Per-backend tool availability: filters the 41-tool registry down to what a
  * given DriverKind can actually run, per ADR-001's rule that tools/list
  * discovers gaps, not runtime "unsupported" throws. Pure and I/O-free: driver
  * construction reads a static readonly `capabilities` set, it does not dial a

package/src/cdp/driver.ts

@@ -7,10 +7,12 @@
  */
 import { type CdpConnection, CdpError, listTargets, openBrowser, openPage, resolveTarget } from "../client.ts";
 import type { Target, TargetSelector } from "../types.ts";
+import { LeaseConflictError } from "../leases.ts";
 import { resolveUid } from "../tools/snapshot.ts";
 import { buildFulfillParams, effectiveAction, selectRule } from "../tools/network_mock.ts";
 import {
-  LEGACY_NUMERIC_UID, type BrowserDriver, type Capability, type HandledDialogInfo, type DriverError, type DriverErrorCode, type DriverEvent,
+  LEGACY_NUMERIC_UID, type BrowserCookie, type BrowserDriver, type Capability, type DeleteCookiesFilter, type HandledDialogInfo, type DriverError, type DriverErrorCode, type DriverEvent,
+  type SetCookieParams,
   type DriverUid, type ElementLocator, type EmulationOptions, type InterceptRule, type KeyPress, type LifetimeModel, type MouseButtonOptions,
   type NavigateOptions, type NavigateResult, type PageDriver, type PageInfo, type ScreenshotOptions, type SnapshotNode, type UidStability,
 } from "../driver.ts";
@@ -29,6 +31,49 @@ function decodeUid(uid: DriverUid): number {
   if (!Number.isSafeInteger(n) || n <= 0) throw driverError("foreign-uid", `malformed cdp uid payload: ${uid}`);
   return n;
 }
+/* ---------------------------------- cookies ---------------------------------- */
+/** The subset of CDP's `Network.Cookie` this driver reads. */
+export interface CdpCookie {
+  name: string; value: string; domain: string; path: string; expires: number; size: number;
+  httpOnly: boolean; secure: boolean; session: boolean; sameSite?: string;
+}
+
+/**
+ * CDP's cookie shape to the neutral one. Two mappings carry the difference:
+ * `sameSite` is capitalized by CDP and absent when the cookie never set the
+ * attribute, so it lowercases and falls back to "default" (BiDi's word for the
+ * same state); `expires` is already CDP's Unix seconds with -1 for a session
+ * cookie, so it passes through, with `session` kept as the browser's own flag
+ * rather than re-derived from the timestamp.
+ */
+export function normalizeCdpCookie(c: CdpCookie): BrowserCookie {
+  const same = (c.sameSite ?? "").toLowerCase();
+  const sameSite: BrowserCookie["sameSite"] =
+    same === "strict" || same === "lax" || same === "none" ? same : "default";
+  return {
+    name: c.name, value: c.value, domain: c.domain, path: c.path,
+    expires: typeof c.expires === "number" ? c.expires : -1,
+    size: typeof c.size === "number" ? c.size : Buffer.byteLength(`${c.name}${c.value}`, "utf8"),
+    httpOnly: c.httpOnly === true, secure: c.secure === true, sameSite, session: c.session === true,
+  };
+}
+
+/**
+ * The neutral lowercase `sameSite` back to CDP's own vocabulary.
+ *
+ * The inverse of normalizeCdpCookie's mapping, and it has to be the inverse:
+ * CDP capitalizes the three real values and has NO word for "default", which
+ * is BiDi's name for a cookie that never set the attribute. So "default"
+ * returns undefined and the caller omits the field, which is exactly the state
+ * it describes.
+ */
+export function cdpSameSite(sameSite?: "strict" | "lax" | "none" | "default"): "Strict" | "Lax" | "None" | undefined {
+  if (sameSite === "strict") return "Strict";
+  if (sameSite === "lax") return "Lax";
+  if (sameSite === "none") return "None";
+  return undefined;
+}
+
 /* ---------------------- copied helpers, see attributions below ---------------------- */
 // Copied verbatim from src/tools/input.ts `centerOf`: scroll into view, read viewport-space center.
 async function centerOf(conn: CdpConnection, objectId: string): Promise<{ x: number; y: number }> {
@@ -214,12 +259,15 @@ async function elementClip(conn: CdpConnection, loc: ElementLocator): Promise<{
  * not "not armed in advance", so an honest capability set omits it rather than reading true by
  * construction. locate.text/locate.xpath both ride DOM.performSearch (see searchLocate above),
  * which is a real Chrome capability, not a line-budget artifact, so both ARE declared.
+ * capture.screencast rides Page.startScreencast / Page.screencastFrame / Page.screencastFrameAck,
+ * the streamed-repaint primitive behind start_screen_recording and stop_screen_recording.
  */
 const CDP_CAPABILITIES: ReadonlySet<Capability> = new Set<Capability>([
   "trace.performance", "heap.snapshot", "audit.lighthouse", "emulate.cpuThrottling",
   "emulate.mediaFeatures", "emulate.deviceMetrics", "emulate.networkConditions",
   "screenshot.fullPage", "screenshot.element", "network.intercept",
   "snapshot.accessibilityTree", "input.insertTextAtomic", "locate.text", "locate.xpath",
+  "capture.screencast",
 ]);
 /* ---------------------------------- PageDriver ---------------------------------- */
 class CdpPageDriver implements PageDriver {
@@ -535,6 +583,79 @@ class CdpPageDriver implements PageDriver {
       });
     });
   }
+  /**
+   * `Network.getCookies` over `Storage.getCookies`, deliberately.
+   *
+   * The two differ in SCOPE, not in detail: `Storage.getCookies` returns the
+   * whole browser jar (every cookie for every site the profile has), while
+   * `Network.getCookies`, called with no `urls`, returns the cookies of the
+   * page this connection is attached to and its subframes. This driver is
+   * always attached to one resolved target, so the page-scoped call is the one
+   * that answers the question the caller asked. It also keeps unrelated sites'
+   * session credentials out of a result that only named one tab.
+   *
+   * The Network domain is enabled with the same lazy ensureDomain the rest of
+   * the class uses. httpOnly cookies come back either way: this is a protocol
+   * read of the cookie store, not a `document.cookie` evaluation, which is the
+   * entire reason a tool is better here than a script.
+   */
+  async getCookies(): Promise<BrowserCookie[]> {
+    await this.ensureDomain("Network");
+    const { cookies } = await this.conn.send<{ cookies: CdpCookie[] }>("Network.getCookies");
+    return (cookies ?? []).map(normalizeCdpCookie);
+  }
+  /**
+   * `Network.setCookie`, which answers `{success: boolean}` rather than an
+   * error when it declines a cookie.
+   *
+   * That return is the whole reason this method is more than one line. Chrome
+   * refuses a cookie for plenty of ordinary reasons (a domain the url does not
+   * belong to, `secure` on an insecure origin, an oversized value) and reports
+   * the refusal as `success:false` with a perfectly successful protocol reply.
+   * Resolving on that would hand the caller a "cookie set" that is not set, so
+   * a false is turned into a thrown error naming the cookie.
+   *
+   * `path` is passed through as given, not defaulted: with a `url` CDP derives
+   * the path from it, and inventing "/" here would silently widen the scope of
+   * a cookie the caller asked to scope narrowly.
+   */
+  async setCookie(params: SetCookieParams): Promise<void> {
+    await this.ensureDomain("Network");
+    const sameSite = cdpSameSite(params.sameSite);
+    const { success } = await this.conn.send<{ success: boolean }>("Network.setCookie", {
+      name: params.name,
+      value: params.value,
+      ...(params.url !== undefined ? { url: params.url } : {}),
+      ...(params.domain !== undefined ? { domain: params.domain } : {}),
+      ...(params.path !== undefined ? { path: params.path } : {}),
+      ...(params.expires !== undefined ? { expires: params.expires } : {}),
+      ...(params.httpOnly !== undefined ? { httpOnly: params.httpOnly } : {}),
+      ...(params.secure !== undefined ? { secure: params.secure } : {}),
+      ...(sameSite !== undefined ? { sameSite } : {}),
+    });
+    if (success !== true) {
+      // "page-error" is this file's code for a browser-side refusal of an
+      // operation that reached the browser intact, which is precisely this.
+      throw driverError(
+        "page-error",
+        `Network.setCookie declined the cookie '${params.name}'. Chrome rejects a cookie whose domain does not match the url, a secure cookie on an insecure origin, and an oversized name or value.`,
+      );
+    }
+  }
+  /**
+   * `Network.deleteCookies`. Unlike setCookie it reports nothing at all, not
+   * even a count, so this resolves on the protocol acknowledgement and the tool
+   * above it returns a boolean ack instead of a fabricated number.
+   */
+  async deleteCookies(filter: DeleteCookiesFilter): Promise<void> {
+    await this.ensureDomain("Network");
+    await this.conn.send("Network.deleteCookies", {
+      name: filter.name,
+      ...(filter.url !== undefined ? { url: filter.url } : {}),
+      ...(filter.domain !== undefined ? { domain: filter.domain } : {}),
+      ...(filter.path !== undefined ? { path: filter.path } : {}),
+    });
+  }
   async startBodyCapture(): Promise<() => Promise<void>> {
     await this.ensureDomain("Network");
     return async () => {
@@ -587,7 +708,33 @@ async function withBrowserConn<T>(fn: (conn: CdpConnection) => Promise<T>): Prom
     conn.close();
   }
 }
+/**
+ * Relabel a target-resolution failure as `no-such-target`, but ONLY when the
+ * failure carries no type of its own.
+ *
+ * This used to relabel everything, and that was wrong in a way no unit test
+ * caught, because the message text survived and the MCP surface reads message
+ * text. resolveTarget is where the Chrome lease gate lives, so a
+ * LeaseConflictError raised by assertLeaseOk came through here and lost its
+ * class, its targetId and its holder, and came out coded `no-such-target`,
+ * which tells a caller the selector matched nothing and it should stop. A lease
+ * conflict is the one case where retrying, or going to fetch the token, is the
+ * right move. readLease's deliberate rethrow on an UNREADABLE lease file was
+ * mislabeled the same way, which is precisely the confusion that throw exists
+ * to prevent. BiDi never had a blanket catch, so the two backends disagreed.
+ *
+ * The pass-through is by TYPE, not by an enumerated list of errors, so a typed
+ * error added anywhere below this frame is protected without anyone having to
+ * remember to come back here:
+ *   - LeaseConflictError, named because it is the one the caller acts on;
+ *   - anything carrying a STRING `code`, which covers every DriverError and
+ *     every fs errno (an EACCES out of readLease reaches this frame).
+ * CdpError's `code` is a NUMBER (a CDP protocol error code), so a genuine
+ * "that target does not exist" from pickTarget still relabels, as it must.
+ */
 function noSuchTarget(e: unknown): never {
+  if (e instanceof LeaseConflictError) throw e;
+  if (typeof (e as { code?: unknown } | null | undefined)?.code === "string") throw e;
   throw driverError("no-such-target", e instanceof CdpError ? e.message : String(e));
 }
 class CdpBrowserDriver implements BrowserDriver {

package/src/driver.ts

@@ -1,5 +1,5 @@
 /**
- * ADR-001: one browser-neutral Driver interface behind the 36 tools.
+ * ADR-001: one browser-neutral Driver interface behind the 41 tools.
  *
  * Context. Every tool in src/tools/ is a stateless one-shot on withPage():
  * open a socket, act, always close. That is only correct because a CDP `Uid`
@@ -126,6 +126,7 @@ export type Capability =
   | "trace.performance" // Chrome tracing, behind every performance_* tool
   | "heap.snapshot" // V8 heap snapshots
   | "audit.lighthouse" // shelling out to lighthouse against a debug port
+  | "capture.screencast" // streamed repaint frames (CDP Page.startScreencast); BiDi has no equivalent
   | "emulate.cpuThrottling" // CPU multiplier; absent from BiDi's emulation module
   | "emulate.mediaFeatures" // media type + features, e.g. prefers-color-scheme
   | "emulate.deviceMetrics" // past width/height: scale factor, mobile flag
@@ -151,6 +152,8 @@ export const REQUIRED_CAPABILITIES: Partial<Record<ToolName, readonly Capability
   performance_trace: ["trace.performance"],
   take_heapsnapshot: ["heap.snapshot"],
   lighthouse_audit: ["audit.lighthouse"],
+  start_screen_recording: ["capture.screencast"],
+  stop_screen_recording: ["capture.screencast"],
   mock_request: ["network.intercept"],
   list_mocks: ["network.intercept"],
   clear_mocks: ["network.intercept"],
@@ -281,6 +284,80 @@ export interface HandledDialogInfo extends DialogInfo {
   handled: true;
 }
 
+/**
+ * One cookie, neutral over CDP's `Network.Cookie` and BiDi's `network.Cookie`.
+ *
+ * Every flag a caller needs to reason about a session credential is present:
+ * an httpOnly cookie is exactly the one `document.cookie` cannot read, so a
+ * shape that dropped `httpOnly` would make the reason this exists invisible.
+ *
+ * Two normalizations, applied by both drivers so the shape does not change
+ * with the backend:
+ *  - `expires` is a Unix timestamp in SECONDS, or -1 for a session cookie.
+ *    CDP reports exactly that; BiDi reports an optional `expiry` and omits it
+ *    for a session cookie, which the BiDi driver maps to -1.
+ *  - `sameSite` is lowercased to BiDi's vocabulary ("strict" | "lax" | "none"
+ *    | "default"). CDP capitalizes it and omits it entirely when unset, which
+ *    the CDP driver maps to "default".
+ */
+export interface BrowserCookie {
+  name: string;
+  value: string;
+  domain: string;
+  path: string;
+  /** Unix seconds, or -1 for a session cookie. */
+  expires: number;
+  /** Byte length of name plus value, as the browser reports it. */
+  size: number;
+  httpOnly: boolean;
+  secure: boolean;
+  sameSite: "strict" | "lax" | "none" | "default";
+  /** True when the cookie expires with the browsing session (no expiry set). */
+  session: boolean;
+}
+
+/**
+ * One cookie to WRITE, neutral over CDP's `Network.setCookie` and BiDi's
+ * `storage.setCookie`.
+ *
+ * `url` and `domain` are both optional here but not both omittable: the cookie
+ * has to be attributed to a site somehow, and every backend refuses without
+ * one. The tool layer enforces that before either driver is reached, so the
+ * refusal is one message rather than two different protocol errors.
+ *
+ * `expires` follows the read shape: Unix seconds. Omit it for a session cookie,
+ * which is what both backends do when no expiry is supplied.
+ */
+export interface SetCookieParams {
+  name: string;
+  value: string;
+  /** The URL the cookie is being set for. CDP derives domain, path and secure
+   *  from it; BiDi has no url parameter, so its driver derives the domain. */
+  url?: string;
+  domain?: string;
+  path?: string;
+  /** Unix seconds. Omitted means a session cookie. */
+  expires?: number;
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: "strict" | "lax" | "none" | "default";
+}
+
+/**
+ * Which cookies to DELETE, neutral over CDP's `Network.deleteCookies` and
+ * BiDi's `storage.deleteCookies` filter.
+ *
+ * `name` is required and there is no wildcard: this deletes a named cookie, not
+ * a swathe of them. As with SetCookieParams, one of `url` or `domain` must be
+ * present, and the tool layer enforces it.
+ */
+export interface DeleteCookiesFilter {
+  name: string;
+  url?: string;
+  domain?: string;
+  path?: string;
+}
+
 export interface InterceptRule {
   /** Glob: `*` any run, `?` one char. Both drivers normalize to this. */
   urlPattern: string;
@@ -403,6 +480,38 @@ export interface PageDriver {
     opts?: { timeoutMs?: number; autoMs?: number },
   ): Promise<HandledDialogInfo | { handled: HandledDialogInfo[]; count: number }>;
 
+  /* cookies */
+  /**
+   * Every cookie visible to THIS page, httpOnly ones included.
+   *
+   * Deliberately page-scoped, not browser-scoped. Both protocols offer a
+   * browser-wide jar (CDP's `Storage.getCookies` with no browserContextId,
+   * BiDi's storageKey partition), and both would hand back every credential
+   * for every site the browser has ever visited on a call that named one tab.
+   * A tool scoped to a target returns that target's cookies; a caller who
+   * wants another site's cookies points at a page on that site.
+   */
+  getCookies(): Promise<BrowserCookie[]>;
+
+  /**
+   * Write one cookie into the store this page reads from.
+   *
+   * Resolves only when the backend confirms the write. A backend that reports
+   * a refusal (CDP's `Network.setCookie` answers `{success:false}` for a cookie
+   * it will not accept) must throw rather than resolve, because a resolved
+   * promise here reads as "the cookie is set" and a caller will believe it.
+   */
+  setCookie(params: SetCookieParams): Promise<void>;
+
+  /**
+   * Remove the cookies matching the filter from the store this page reads from.
+   *
+   * Neither backend reports how many cookies it removed, so this returns
+   * nothing rather than an invented count. Deleting a cookie that was never
+   * there is not an error on either backend.
+   */
+  deleteCookies(filter: DeleteCookiesFilter): Promise<void>;
+
   /* network */
   /** Begin retaining response bodies. REQUIRED before getResponseBody unless
    *  the driver declares "network.responseBodyPostHoc". Returns a stop fn. */

package/src/firefox-tools.ts

@@ -1,5 +1,5 @@
 /**
- * The complete Firefox tool registry: the 20 tools shared with Chrome (src/shared-tools.ts), the
+ * The complete Firefox tool registry: the 23 tools shared with Chrome (src/shared-tools.ts), the
  * 7 Firefox-only console/network/mock tools (src/bidi-tools.ts), and the 3 lease tools
  * (src/leases-tools.ts), which are backend-neutral by construction. This is what src/neutral.ts
  * used to be; it now composes three files instead of reimplementing everything in one.

package/src/index.ts

@@ -3,7 +3,8 @@
  *
  * Two exports:
  *   1. `TOOLS` : the registry mapping every chrome-devtools-mcp tool name
- *      (snake_case string, all 29) to its raw-CDP implementation function. The
+ *      (snake_case string, all 29 of them) plus the toolkit's own superset
+ *      tools, 41 entries in all, to its raw-CDP implementation function. The
  *      CLI and any embedder dispatch through this single table.
  *   2. The client primitives, re-exported so consumers can build their own
  *      flows on the same connection/timeout machinery the tools use.
@@ -12,8 +13,9 @@
  * value (or throws). See CONTRACT.md for the design rules each module follows.
  */
 
-// --- the 20 tools unified with Firefox onto one Driver-based implementation ---
+// --- the 23 tools unified with Firefox onto one Driver-based implementation ---
 // (list_pages/new_page/close_page/select_page, navigate_page/wait_for, evaluate_script,
+// list_cookies/set_cookie/delete_cookies,
 // take_snapshot, click/hover/drag/fill/fill_form/type_text/press_key/upload_file,
 // take_screenshot/emulate/resize_page, handle_dialog). See shared-tools.ts's file header for
 // the byte-identical-Chrome-behavior contract this bind honors, and for the 7 tools that stay
@@ -31,6 +33,8 @@ import {
   performanceAnalyzeInsight,
   performanceTrace,
 } from "./tools/performance.ts";
+// --- screen recording (Page.startScreencast + ffmpeg) ---
+import { startScreenRecording, stopScreenRecording } from "./tools/screencast.ts";
 // --- heap ---
 import { takeHeapsnapshot } from "./tools/heap.ts";
 // --- lighthouse (the sole non-CDP tool) ---
@@ -56,8 +60,15 @@ function onCdp<A>(fn: (driver: ReturnType<typeof createCdpDriver>, args: A) => P
  * their canonical MCP (snake_case) name, plus one convenience superset tool
  * (`performance_trace`, a robust single-call trace : the start/stop pair cannot
  * span two stateless CLI processes), plus a 3-tool network-mocking group
- * (mock_request/list_mocks/clear_mocks : a persistent per-target fake backend).
- * 36 entries total. Listed explicitly so the mapping is auditable at a glance and
+ * (mock_request/list_mocks/clear_mocks : a persistent per-target fake backend),
+ * plus a 3-tool cookie group (list_cookies/set_cookie/delete_cookies : the
+ * cookie store including httpOnly cookies, which no page script can read or
+ * write), plus a 3-tool lease group (claim_page/release_page/list_leases :
+ * opt-in tab ownership so many agents can share one browser), plus a 2-tool
+ * screen-recording pair (start_screen_recording/stop_screen_recording : a tab
+ * captured to an H.265 MP4 with per-frame durations, so a variable-rate
+ * repaint stream plays back at wallclock speed).
+ * 29 + 1 + 3 + 3 + 3 + 2 = 41 entries total. Listed explicitly so the mapping is auditable at a glance and
  * the CLI can `--list` it.
  *
  * 20 of the 29 MCP-parity tools (pages/navigation/evaluate/snapshot/interaction/
@@ -76,6 +87,10 @@ export const TOOLS = {
   wait_for: onCdp(SHARED_TOOLS.wait_for),
   // evaluate (1)
   evaluate_script: onCdp(SHARED_TOOLS.evaluate_script),
+  // cookies (3) : toolkit addition, reads and writes httpOnly cookies that document.cookie cannot touch
+  list_cookies: onCdp(SHARED_TOOLS.list_cookies),
+  set_cookie: onCdp(SHARED_TOOLS.set_cookie),
+  delete_cookies: onCdp(SHARED_TOOLS.delete_cookies),
   // snapshot (1)
   take_snapshot: onCdp(SHARED_TOOLS.take_snapshot),
   // interaction (8)
@@ -103,6 +118,9 @@ export const TOOLS = {
   performance_stop_trace: performanceStopTrace,
   performance_analyze_insight: performanceAnalyzeInsight,
   performance_trace: performanceTrace,
+  // screen recording (2) : toolkit addition, a tab-to-H.265-MP4 pair over Page.startScreencast
+  start_screen_recording: startScreenRecording,
+  stop_screen_recording: stopScreenRecording,
   // heap (1)
   take_heapsnapshot: takeHeapsnapshot,
   // lighthouse (1) : the only non-CDP tool

package/src/leases-tools.ts

@@ -1,11 +1,13 @@
 /**
  * The three lease tools, shaped like src/shared-tools.ts entries
  * ((driver, args) => Promise<result>) so ONE implementation serves Chrome and
- * Firefox, exactly as the other 20 unified tools do.
+ * Firefox, exactly as the 23 unified tools in that file do.
  */
 import type { BrowserDriver } from "./driver.ts";
+import { newTrackedPage } from "./origins.ts";
 import {
   claimLease,
+  defaultLabel,
   leaseTtlMs,
   listLeases,
   releaseLease,
@@ -41,12 +43,16 @@ export async function claimPage(
   args: { targetId?: string; url?: string; label?: string; ttlMs?: number } = {},
 ): Promise<ClaimPageResult> {
   const backend = backendOf(driver);
-  const label = typeof args.label === "string" && args.label.length ? args.label : `pid-${process.pid}`;
+  const label = typeof args.label === "string" && args.label.length ? args.label : defaultLabel();
   const pages = await driver.listPages();
   let targetId = args.targetId;
   let url = args.url ?? "about:blank";
   if (targetId === undefined || targetId === "") {
-    const page = await driver.newPage(args.url);
+    // Creation ledger, not the lease: this record survives release_page and
+    // expiry, so the tab stays attributable to `label` after the lease is gone.
+    // Claiming an EXISTING tab (the else branch) records nothing, because this
+    // toolkit did not create it and provenance is not ownership.
+    const page = await newTrackedPage(driver, backend, { url: args.url, label });
     targetId = page.id;
     url = page.url;
   } else {