cdp-toolkit 1.1.0 → 1.4.0

package/src/driver.ts

@@ -1,5 +1,5 @@
 /**
- * ADR-001: one browser-neutral Driver interface behind the 33 tools.
+ * ADR-001: one browser-neutral Driver interface behind the 36 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`
@@ -281,6 +281,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 +477,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,14 +1,17 @@
 /**
- * The complete Firefox tool registry: the 20 tools shared with Chrome (src/shared-tools.ts) plus
- * the 7 Firefox-only console/network/mock tools (src/bidi-tools.ts). This is what src/neutral.ts
- * used to be; it now composes two files instead of reimplementing everything in one.
+ * 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.
  */
 import type { BrowserDriver } from "./driver.ts";
 import type { ToolName } from "./index.ts";
 import { SHARED_TOOLS } from "./shared-tools.ts";
 import { BIDI_ONLY_TOOLS } from "./bidi-tools.ts";
+import { LEASE_TOOLS } from "./leases-tools.ts";
 
 export const FIREFOX_TOOLS: Partial<Record<ToolName, (driver: BrowserDriver, args: never) => Promise<unknown>>> = {
   ...SHARED_TOOLS,
   ...BIDI_ONLY_TOOLS,
+  ...LEASE_TOOLS,
 };

package/src/index.ts

@@ -19,6 +19,7 @@
 // the byte-identical-Chrome-behavior contract this bind honors, and for the 7 tools that stay
 // two implementations (console/network/mock, immediately below, unchanged from before).
 import { createCdpDriver } from "./cdp/driver.ts";
+import { LEASE_TOOLS } from "./leases-tools.ts";
 import { SHARED_TOOLS } from "./shared-tools.ts";
 // --- console + network (read the recorder buffer) ---
 import { listConsoleMessages, getConsoleMessage } from "./tools/console.ts";
@@ -55,8 +56,11 @@ 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).
- * 33 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).
+ * 39 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/
@@ -75,6 +79,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)
@@ -110,6 +118,10 @@ export const TOOLS = {
   mock_request: mockRequest,
   list_mocks: listMocks,
   clear_mocks: clearMocks,
+  // tab leases (3) : opt-in ownership so many agents can share one browser
+  claim_page: onCdp(LEASE_TOOLS.claim_page),
+  release_page: onCdp(LEASE_TOOLS.release_page),
+  list_leases: onCdp(LEASE_TOOLS.list_leases),
 } satisfies Record<string, (args: never) => Promise<unknown>>;
 
 /** Canonical MCP tool name accepted by the registry. */

package/src/leases-tools.ts

@@ -0,0 +1,107 @@
+/**
+ * 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.
+ */
+import type { BrowserDriver } from "./driver.ts";
+import { newTrackedPage } from "./origins.ts";
+import {
+  claimLease,
+  defaultLabel,
+  leaseTtlMs,
+  listLeases,
+  releaseLease,
+  type LeaseBackend,
+  type LeaseSummary,
+  type LeaseToken,
+} from "./leases.ts";
+
+class LeaseToolError extends Error {}
+
+/** The driver's uid scheme is the one stable per-backend discriminator on the
+ *  BrowserDriver surface ("cdp" for Chrome, "bidi" for Firefox). */
+function backendOf(driver: BrowserDriver): LeaseBackend {
+  return driver.scheme === "bidi" ? "firefox" : "chrome";
+}
+
+export interface ClaimPageResult {
+  lease: LeaseToken;
+  targetId: string;
+  url: string;
+  label: string;
+  ttlMs: number;
+  expiresAt: number;
+}
+
+/**
+ * Claim a tab. With no targetId, opens a fresh tab first (optionally at `url`)
+ * and claims that, so "give me my own tab" is one call. With a targetId, claims
+ * an already-open tab.
+ */
+export async function claimPage(
+  driver: BrowserDriver,
+  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 : defaultLabel();
+  const pages = await driver.listPages();
+  let targetId = args.targetId;
+  let url = args.url ?? "about:blank";
+  if (targetId === undefined || targetId === "") {
+    // 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 {
+    const existing = pages.find((p) => p.id === targetId);
+    if (!existing) throw new LeaseToolError(`claim_page: no page target with id '${targetId}'`);
+    url = existing.url;
+  }
+  const liveIds = [...pages.map((p) => p.id), targetId];
+  const { record, token } = await claimLease(backend, targetId, {
+    label,
+    ttlMs: typeof args.ttlMs === "number" && args.ttlMs > 0 ? args.ttlMs : leaseTtlMs(),
+    liveIds,
+  });
+  return {
+    lease: token,
+    targetId,
+    url,
+    label: record.label,
+    ttlMs: record.ttlMs,
+    expiresAt: record.lastUsedAt + record.ttlMs,
+  };
+}
+
+/** Release a held lease. Idempotent: an already-released or reclaimed lease
+ *  reports released:false rather than throwing. */
+export async function releasePage(
+  _driver: BrowserDriver,
+  args: { lease?: LeaseToken },
+): Promise<{ released: boolean }> {
+  if (typeof args.lease !== "string" || !args.lease.length) {
+    throw new LeaseToolError("release_page requires the 'lease' token returned by claim_page");
+  }
+  return releaseLease(args.lease);
+}
+
+/** Enumerate active leases for diagnosis. Requires no token by design. */
+export async function listLeasesTool(
+  driver: BrowserDriver,
+  _args: Record<string, never> = {} as Record<string, never>,
+): Promise<{ leases: LeaseSummary[]; count: number }> {
+  const liveIds = (await driver.listPages()).map((p) => p.id);
+  // liveBackend scopes the target-gone test to the browser these ids came from,
+  // so leases held on the OTHER backend are not mislabeled as reclaimable.
+  const leases = await listLeases({ liveIds, liveBackend: backendOf(driver) });
+  return { leases, count: leases.length };
+}
+
+export const LEASE_TOOLS = {
+  claim_page: claimPage,
+  release_page: releasePage,
+  list_leases: listLeasesTool,
+} satisfies Record<string, (driver: BrowserDriver, args: never) => Promise<unknown>>;