cdp-mcp 0.1.3 → 0.2.0

package/README.md

@@ -6,9 +6,11 @@ Designed for agents running in CLIs (Claude Code, GitHub Copilot CLI) that have
 
 **Status:** alpha. **License:** [MIT](./LICENSE).
 
+**Last updated: 2026-06-09**
+
 ## What it gives an agent
 
-Across 39 tools:
+Across 48 tools:
 
 - **Breakpoints in TS source** — `set_breakpoint(file="src/foo.ts", line=42, condition?, log_message?)`. The server matches source maps and binds in every script that maps back to that file.
 - **Stepping** — `step_over`, `step_into`, `step_out`, `resume`, `pause`, plus the authoritative sync point `wait_for_pause`.
@@ -16,6 +18,8 @@ Across 39 tools:
 - **Buffered console + network** — pull-based, paginated by monotonic `seq`. Bodies are lazy-loaded via `get_request_body` / `get_response_body`.
 - **Light DOM interaction** — `query_selector`, `click`, `type_text`, `press_key`, `screenshot` so the agent can drive a flow to a breakpoint.
 - **Structured DOM querying** — Playwright-inspired `locate` (LocatorSpec: CSS, text, role, test-id, label, placeholder, name), `wait_for` (poll until DOM state), `get_form_state` (read named form fields).
+- **Form driving** — `fill`, `check` / `uncheck`, `select_option`, plus `suggest_locator` to get a robust semantic locator for an element.
+- **Session portability** — `export_storage_state` / `load_storage_state` carry a logged-in session (cookies + localStorage) across runs; `get_cookies` / `set_cookies` read and set cookies directly (`get_cookies` redacts likely-auth / HttpOnly values for safe logging).
 - **Source-map diagnostics** — `list_scripts`, `resolve_source_position`, `get_script_source`.
 
 Auto-attaches to iframes and workers via `Target.setAutoAttach({ flatten: true })`.
@@ -67,9 +71,11 @@ SSE mode caveats:
   tears down client A's session).
 - **Non-loopback bind requires opt-in.** `--allow-remote` (or
   `CDP_MCP_ALLOW_REMOTE=1`) is required to bind to anything other than
-  loopback. MCP tools include `evaluate` (in-page code exec) and a
-  `screenshot path=` filesystem write; the gate makes remote exposure
-  a deliberate operator decision rather than a default.
+  loopback. MCP tools include `evaluate` (in-page code exec), a
+  `screenshot path=` filesystem write, `export_storage_state` (writes full
+  cookie values — including HttpOnly auth secrets — to a server-side file) and
+  `load_storage_state` (reads an arbitrary server-side file); the gate makes
+  remote exposure a deliberate operator decision rather than a default.
 - **Host / Origin headers are validated on loopback binds** to block
   DNS-rebinding against `127.0.0.1` / `localhost` / `[::1]`. On
   non-loopback binds the operator has already accepted exposure via
@@ -101,10 +107,10 @@ grader/trace/oracle units. See `docs/test-eval-plan.md` for the full pyramid.
 npm run test:e2e
 ```
 
-Drives the 39 MCP tools against a real headless Chromium attached to a
-built copy of `examples/sample-app/`. Nine specs cover lifecycle, breakpoints,
-stepping, exceptions, console, network, workers, screenshot, and DOM
-interaction. Sequential (one Chrome shared across specs, isolated by a
+Drives the 48 MCP tools against a real headless Chromium attached to a
+built copy of `examples/sample-app/`. Eleven specs cover lifecycle, breakpoints,
+stepping, exceptions, console, network, workers, screenshot, DOM
+interaction, form driving, and storage portability. Sequential (one Chrome shared across specs, isolated by a
 shared `afterEach(close_session)`). Run time is a few seconds on a warm
 machine.
 
@@ -140,14 +146,17 @@ pretest hook) enforces this.
 `launch_chrome` defaults to `--no-sandbox` for Ubuntu/Playwright-Chromium
 compatibility. See [`docs/chromium-sandboxing.md`](docs/chromium-sandboxing.md)
 before changing that default or relying on `sandbox: true`, AppArmor, snap
-confinement, or Bubblewrap.
+confinement, or Bubblewrap. For the step-by-step setup that gets local
+`npm run test:e2e` passing with the sandbox **on** (install Playwright Chromium
++ attach the AppArmor profile), see
+[`docs/local-l3-e2e-setup.md`](docs/local-l3-e2e-setup.md).
 
 ### L4 — LLM agent evals
 
 ```sh
 export ANTHROPIC_API_KEY=...
-npm run eval:quick                 # 1 scenario × 1 trial (~$0.50–2 at default Opus-4.7-medium; ~$0.05 with EVAL_MODEL_OVERRIDE=claude-sonnet-4-6)
-npm run eval                       # all scenarios × 3 trials (first observed ~$4 at default Opus-4.7-medium on a reference host — one data point, not the steady-state band)
+npm run eval:quick                 # 1 scenario × 1 trial (~$0.50–2 at default Opus-4.8-medium; ~$0.05 with EVAL_MODEL_OVERRIDE=claude-sonnet-4-6)
+npm run eval                       # all scenarios × 3 trials (~$4 full pass — first observed on Opus-4.7-medium, the prior default; 4.8 shares its rate card)
 npm run eval -- --scenarios=compute-step --trials=1
 ```
 
@@ -155,8 +164,10 @@ Use `npm run eval` (or `npm run eval:quick`) — NOT `npx tsx evals/cli.ts` dire
 
 Drives the cdp-mcp tool surface through an LLM agent via the
 `VendorAdapter` seam (`evals/harness/vendor.ts`); the Anthropic adapter
-backed by `@anthropic-ai/sdk` is the default and only production path
-today. Each trial spawns a fresh `dist/index.js` MCP subprocess + a
+backed by `@anthropic-ai/sdk` is the default; OpenAI, Vertex, DeepSeek,
+and Moonshot/Kimi are also shipped production adapters (plus an LM Studio
+reference adapter for local models), each selected via `EVAL_PROVIDER`.
+Each trial spawns a fresh `dist/index.js` MCP subprocess + a
 static server for the scenario's sample-app variant; the tool-use loop
 drives the page, sets source-level breakpoints, inspects pauses, and
 produces a natural-language final answer. NDJSON traces land under
@@ -165,7 +176,7 @@ produces a natural-language final answer. NDJSON traces land under
 exercise the debugger workflow under test) + **correctness** (did the
 final answer name the bug) — plus efficiency ratio and recovery count.
 
-**Default model**: `claude-opus-4-7` with adaptive thinking at
+**Default model**: `claude-opus-4-8` with adaptive thinking at
 `effort=medium` (set in `evals/harness/model.ts`). Adaptive-style models
 (Opus 4.7+) default to medium-effort thinking when no env override is
 set; budget-style models (Sonnet 4.6, selectable via
@@ -199,23 +210,27 @@ each `t:"usage"` trace entry (the Anthropic adapter populates
 `cacheTokens.cacheReadInputTokens` and `cacheTokens.cacheCreationInputTokens`
 verbatim from the SDK's `cache_read_input_tokens` / `cache_creation_input_tokens`).
 
-Non-Anthropic backends: the OpenAI vendor adapter ships with #50/#58
-(target: GPT-5.5) — `EVAL_PROVIDER=openai` plus `OPENAI_API_KEY`
-+ `EVAL_OPENAI_MODEL` activates it. Reasoning-off trials route to
-`/v1/chat/completions` (#50); reasoning-on trials route to
-`/v1/responses` (#58), the only OpenAI surface that supports tools
-× reasoning_effort on GPT-5.5. An LM Studio investigation artifact
-is wired behind the same seam for issue #45. See
-[evals/README.md](evals/README.md) for full `EVAL_PROVIDER` /
-`EVAL_OPENAI_*` / `EVAL_LM_STUDIO_*` details. Vertex (#51) is the last
-backend adapter still pending.
-
-Currently registered scenarios (8): `compute-step` and
-`adversarial-out-of-order` ship against the canonical `examples/sample-app/`;
-`network-bug`, `console-error`, `event-binding`, `deep-source-map`,
-`worker-bug`, and `conditional-bp` have committed per-scenario forks
-under `evals/sample-app-variants/<name>/` and build via
-`npm run sample:build` (`scripts/build-variants.mjs`).
+Non-Anthropic backends ship behind the same seam, each selected via
+`EVAL_PROVIDER`: OpenAI / GPT-5.5 (#50/#58) — reasoning-off trials route to
+`/v1/chat/completions` (#50), reasoning-on trials to `/v1/responses` (#58),
+the only OpenAI surface that supports tools × reasoning_effort on GPT-5.5;
+Vertex / Gemini (#51); and DeepSeek + Moonshot/Kimi (GH #8), remote
+OpenAI-compatible `/v1` vendors. An LM Studio investigation artifact is
+wired behind the seam for local models (issue #45). See
+[evals/README.md](evals/README.md) for full `EVAL_PROVIDER` / `EVAL_OPENAI_*`
+/ `EVAL_VERTEX_*` / `EVAL_DEEPSEEK_*` / `EVAL_MOONSHOT_*` / `EVAL_LM_STUDIO_*`
+details.
+
+Currently registered scenarios (14) — 8 **debugger** scenarios
+(`compute-step`, `adversarial-out-of-order`, `network-bug`, `console-error`,
+`event-binding`, `deep-source-map`, `worker-bug`, `conditional-bp`) plus 6
+**driving + session-portability** scenarios from issue #12 (`form-drive`,
+`clearing-fill`, `idempotent-toggle`, `robust-locator`, `session-resume`,
+`cookie-redaction`). `compute-step` is the canonical `npm run eval:quick`
+target; some scenarios run against the stock `examples/sample-app/`, others
+against per-scenario forks under `evals/sample-app-variants/<name>/` built via
+`npm run sample:build` (`scripts/build-variants.mjs`). See
+[evals/README.md](evals/README.md) for the full scenario table.
 
 ## Wire into Claude Code
 
@@ -253,6 +268,27 @@ Or via `~/.claude.json`:
 - **Errors** come back as `isError: true` with a structured `{ error, message }` JSON payload.
 - **Compact returns**: previews trimmed to ~200 chars, lists capped at sensible defaults — bodies lazy-loaded via dedicated tools.
 
+## Programmatic contract (`cdp-mcp/contract`)
+
+The structured `LocatorSpec` that `locate`, `wait_for`, and the form-driving tools
+accept is published as a side-effect-free subpath export, so external tooling can
+*produce and validate* specs without duplicating the shape or pulling in the CLI:
+
+```ts
+import { locatorSchema, parseLocator, serializeLocator } from "cdp-mcp/contract";
+import type { LocatorSpec } from "cdp-mcp/contract";
+
+const spec = parseLocator({ by: "role", role: "button", name: "Submit" });
+locatorSchema.parse(spec);          // throws on an invalid shape
+serializeLocator(spec);             // stable, normalized JSON
+```
+
+Exports: `LocatorSpec` (type), `LocatorBy`, `locatorSchema` / `locatorShape` /
+`locatorBySchema` (Zod), and `normalizeLocator` / `parseLocator` / `serializeLocator`
+/ `LocatorError`. This module imports only `zod`. The subpath is **ESM-only** (the
+`exports` map defines `import`, not `require`) — consume it from an ESM module or a
+bundler.
+
 ## Prior art
 
 If `cdp-mcp` doesn't fit your workflow, look at:

package/dist/contract.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Public package contract, published under the `cdp-mcp/contract` subpath export.
+ *
+ * Keep this a thin, side-effect-free barrel: it must only re-export from modules
+ * (like `./locator.js`) whose import graph never reaches the CLI/server entry
+ * (`./index.js`, `./server.js`, `./session/*`). That guarantee is what lets a
+ * downstream consumer `import { locatorSchema } from "cdp-mcp/contract"` without
+ * dragging in the executable's transport/shebang side effects.
+ */
+export { LocatorError, locatorBySchema, locatorShape, locatorSchema, normalizeLocator, parseLocator, serializeLocator, } from "./locator.js";
+export type { LocatorBy, LocatorSpec } from "./locator.js";

package/dist/contract.js

@@ -0,0 +1,11 @@
+/**
+ * Public package contract, published under the `cdp-mcp/contract` subpath export.
+ *
+ * Keep this a thin, side-effect-free barrel: it must only re-export from modules
+ * (like `./locator.js`) whose import graph never reaches the CLI/server entry
+ * (`./index.js`, `./server.js`, `./session/*`). That guarantee is what lets a
+ * downstream consumer `import { locatorSchema } from "cdp-mcp/contract"` without
+ * dragging in the executable's transport/shebang side effects.
+ */
+export { LocatorError, locatorBySchema, locatorShape, locatorSchema, normalizeLocator, parseLocator, serializeLocator, } from "./locator.js";
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EACL,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,GACjB,MAAM,cAAc,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export interface SseClient {
+    server: McpServer;
+    transport: SSEServerTransport;
+}
+export declare function handleSseRequest({ req, res, clients, host, port, validateHostOrigin, allowedHosts, allowedOrigins, }: {
+    req: IncomingMessage;
+    res: ServerResponse;
+    clients: Map<string, SseClient>;
+    host: string;
+    port: number;
+    validateHostOrigin: boolean;
+    allowedHosts: Set<string>;
+    allowedOrigins: Set<string>;
+}): Promise<void>;

package/dist/locator.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Canonical `LocatorSpec` contract for cdp-mcp.
+ *
+ * This module is the single source of truth for the structured element-locator
+ * shape that `locate`, `wait_for`, and the form-driving tools accept. It is
+ * deliberately **side-effect free** and depends only on `zod`, so external
+ * consumers can import it (via `cdp-mcp/contract`) to produce and validate specs
+ * without pulling in the CLI/server. Tool code re-imports these symbols rather
+ * than redefining them, so the published contract can never silently drift from
+ * what the tools actually accept.
+ */
+import { z } from "zod";
+/**
+ * Error thrown by {@link normalizeLocator} / {@link parseLocator} for an invalid
+ * spec. `code` mirrors the cdp-mcp tool error codes so tool handlers can re-wrap it
+ * structurally: `"missing_arg"` when a spec is under-specified for its strategy,
+ * `"invalid_locator"` for an unsupported strategy.
+ */
+export declare class LocatorError extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string);
+}
+/** The locator strategies cdp-mcp understands. `css` is the default when a selector is given. */
+export declare const locatorBySchema: z.ZodEnum<["css", "text", "role", "test_id", "testId", "label", "placeholder", "name"]>;
+/**
+ * The raw Zod shape for a LocatorSpec. Spread into tool input schemas
+ * (`{ ...locatorShape, ... }`) so the field docs stay identical everywhere.
+ */
+export declare const locatorShape: {
+    by: z.ZodOptional<z.ZodEnum<["css", "text", "role", "test_id", "testId", "label", "placeholder", "name"]>>;
+    selector: z.ZodOptional<z.ZodString>;
+    css: z.ZodOptional<z.ZodString>;
+    text: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    test_id: z.ZodOptional<z.ZodString>;
+    testId: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    placeholder: z.ZodOptional<z.ZodString>;
+    exact: z.ZodOptional<z.ZodBoolean>;
+};
+/** A standalone `ZodObject` for a LocatorSpec — external consumers can `.parse()`/`.safeParse()`. */
+export declare const locatorSchema: z.ZodObject<{
+    by: z.ZodOptional<z.ZodEnum<["css", "text", "role", "test_id", "testId", "label", "placeholder", "name"]>>;
+    selector: z.ZodOptional<z.ZodString>;
+    css: z.ZodOptional<z.ZodString>;
+    text: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    test_id: z.ZodOptional<z.ZodString>;
+    testId: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    placeholder: z.ZodOptional<z.ZodString>;
+    exact: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    css?: string | undefined;
+    text?: string | undefined;
+    role?: string | undefined;
+    test_id?: string | undefined;
+    testId?: string | undefined;
+    label?: string | undefined;
+    placeholder?: string | undefined;
+    name?: string | undefined;
+    exact?: boolean | undefined;
+    by?: "css" | "text" | "role" | "test_id" | "testId" | "label" | "placeholder" | "name" | undefined;
+    selector?: string | undefined;
+}, {
+    css?: string | undefined;
+    text?: string | undefined;
+    role?: string | undefined;
+    test_id?: string | undefined;
+    testId?: string | undefined;
+    label?: string | undefined;
+    placeholder?: string | undefined;
+    name?: string | undefined;
+    exact?: boolean | undefined;
+    by?: "css" | "text" | "role" | "test_id" | "testId" | "label" | "placeholder" | "name" | undefined;
+    selector?: string | undefined;
+}>;
+export type LocatorBy = z.infer<typeof locatorBySchema>;
+export interface LocatorSpec {
+    by?: LocatorBy;
+    selector?: string;
+    css?: string;
+    text?: string;
+    role?: string;
+    name?: string;
+    test_id?: string;
+    testId?: string;
+    label?: string;
+    placeholder?: string;
+    exact?: boolean;
+}
+/**
+ * Validate and canonicalize a spec: infer `by` from selector/css, enforce the
+ * required field for the chosen strategy, and fold the `name` fallback into the
+ * strategy-specific field. Throws {@link LocatorError} on an under-specified spec.
+ */
+export declare function normalizeLocator(input: LocatorSpec): LocatorSpec;
+/** Validate an unknown value as a LocatorSpec (shape + strategy requirements). */
+export declare function parseLocator(input: unknown): LocatorSpec;
+/**
+ * Serialize a LocatorSpec to a stable, normalized JSON string. Equivalent specs
+ * serialize identically regardless of which alias the caller used — e.g.
+ * `{ css: ".x" }` and `{ selector: ".x" }` both yield `{"by":"css","selector":".x"}`
+ * — so the output is safe to use as a cache key or for equality checks.
+ */
+export declare function serializeLocator(spec: LocatorSpec): string;

package/dist/locator.js

@@ -0,0 +1,176 @@
+/**
+ * Canonical `LocatorSpec` contract for cdp-mcp.
+ *
+ * This module is the single source of truth for the structured element-locator
+ * shape that `locate`, `wait_for`, and the form-driving tools accept. It is
+ * deliberately **side-effect free** and depends only on `zod`, so external
+ * consumers can import it (via `cdp-mcp/contract`) to produce and validate specs
+ * without pulling in the CLI/server. Tool code re-imports these symbols rather
+ * than redefining them, so the published contract can never silently drift from
+ * what the tools actually accept.
+ */
+import { z } from "zod";
+/**
+ * Error thrown by {@link normalizeLocator} / {@link parseLocator} for an invalid
+ * spec. `code` mirrors the cdp-mcp tool error codes so tool handlers can re-wrap it
+ * structurally: `"missing_arg"` when a spec is under-specified for its strategy,
+ * `"invalid_locator"` for an unsupported strategy.
+ */
+export class LocatorError extends Error {
+    code;
+    constructor(message, code = "missing_arg") {
+        super(message);
+        this.name = "LocatorError";
+        this.code = code;
+    }
+}
+/** The locator strategies cdp-mcp understands. `css` is the default when a selector is given. */
+export const locatorBySchema = z.enum([
+    "css",
+    "text",
+    "role",
+    "test_id",
+    "testId",
+    "label",
+    "placeholder",
+    "name",
+]);
+/**
+ * The raw Zod shape for a LocatorSpec. Spread into tool input schemas
+ * (`{ ...locatorShape, ... }`) so the field docs stay identical everywhere.
+ */
+export const locatorShape = {
+    by: locatorBySchema.optional().describe("Locator strategy. Omit when passing selector/css for a CSS lookup."),
+    selector: z.string().optional().describe("CSS selector. Equivalent to by=css."),
+    css: z.string().optional().describe("CSS selector. Equivalent to selector."),
+    text: z.string().optional().describe("Text to match for by=text."),
+    role: z.string().optional().describe("ARIA/implicit role for by=role, e.g. button, link, textbox."),
+    name: z.string().optional().describe("Accessible name, field name, or fallback value depending on the locator strategy."),
+    test_id: z.string().optional().describe("Value for data-testid, data-test-id, or data-test."),
+    // Both snake_case (`test_id`) and camelCase (`testId`) are accepted so callers
+    // can use whichever matches their convention; `normalizeLocator` /
+    // `serializeLocator` fold them to the canonical `test_id`. Likewise `name` is a
+    // cross-strategy fallback that gets folded into the strategy-specific field.
+    testId: z.string().optional().describe("CamelCase alias for test_id."),
+    label: z.string().optional().describe("Label text for by=label."),
+    placeholder: z.string().optional().describe("Placeholder text for by=placeholder."),
+    exact: z.boolean().optional().describe("Default false: substring match for text/name-like fields."),
+};
+/** A standalone `ZodObject` for a LocatorSpec — external consumers can `.parse()`/`.safeParse()`. */
+export const locatorSchema = z.object(locatorShape);
+/**
+ * Validate and canonicalize a spec: infer `by` from selector/css, enforce the
+ * required field for the chosen strategy, and fold the `name` fallback into the
+ * strategy-specific field. Throws {@link LocatorError} on an under-specified spec.
+ */
+export function normalizeLocator(input) {
+    const by = input.by ?? (input.selector || input.css ? "css" : undefined);
+    if (!by)
+        throw new LocatorError("by is required unless selector/css is supplied");
+    switch (by) {
+        case "css": {
+            const selector = input.selector ?? input.css;
+            if (!selector)
+                throw new LocatorError("selector or css is required for by=css");
+            return { ...input, by, selector };
+        }
+        case "role":
+            if (!input.role)
+                throw new LocatorError("role is required for by=role");
+            return { ...input, by };
+        case "text":
+            if (!input.text && !input.name)
+                throw new LocatorError("text or name is required for by=text");
+            return { ...input, by, text: input.text ?? input.name };
+        case "test_id":
+        case "testId": {
+            const testId = input.test_id ?? input.testId ?? input.name;
+            if (!testId)
+                throw new LocatorError(`test_id, testId, or name is required for by=${by}`);
+            return { ...input, by, test_id: testId };
+        }
+        case "label": {
+            const label = input.label ?? input.name;
+            if (!label)
+                throw new LocatorError("label or name is required for by=label");
+            return { ...input, by, label };
+        }
+        case "placeholder": {
+            const placeholder = input.placeholder ?? input.name;
+            if (!placeholder)
+                throw new LocatorError("placeholder or name is required for by=placeholder");
+            return { ...input, by, placeholder };
+        }
+        case "name":
+            if (!input.name)
+                throw new LocatorError("name is required for by=name");
+            return { ...input, by };
+        default: {
+            // Compile-time exhaustiveness: if `locatorBySchema` gains a strategy and a
+            // case here is missed, `by` is no longer `never` and this fails to build
+            // (pairs with `noFallthroughCasesInSwitch`).
+            const _exhaustive = by;
+            throw new LocatorError(`unsupported locator strategy: ${String(_exhaustive)}`, "invalid_locator");
+        }
+    }
+}
+/** Validate an unknown value as a LocatorSpec (shape + strategy requirements). */
+export function parseLocator(input) {
+    return normalizeLocator(locatorSchema.parse(input));
+}
+/**
+ * Serialize a LocatorSpec to a stable, normalized JSON string. Equivalent specs
+ * serialize identically regardless of which alias the caller used — e.g.
+ * `{ css: ".x" }` and `{ selector: ".x" }` both yield `{"by":"css","selector":".x"}`
+ * — so the output is safe to use as a cache key or for equality checks.
+ */
+export function serializeLocator(spec) {
+    return JSON.stringify(canonicalLocator(spec));
+}
+/**
+ * Reduce a spec to only its canonical fields, in a fixed key order, dropping
+ * alias inputs (`css`, `testId`, and the cross-strategy `name` fallback). This is
+ * what makes {@link serializeLocator} stable across equivalent inputs — the raw
+ * `normalizeLocator` result still carries whichever aliases the caller passed.
+ */
+function canonicalLocator(spec) {
+    const n = normalizeLocator(spec);
+    const out = {};
+    switch (n.by) {
+        case "css":
+            out.by = "css";
+            out.selector = n.selector;
+            break;
+        case "role":
+            out.by = "role";
+            out.role = n.role;
+            if (n.name !== undefined)
+                out.name = n.name;
+            break;
+        case "text":
+            out.by = "text";
+            out.text = n.text;
+            break;
+        case "test_id":
+        case "testId":
+            out.by = "test_id";
+            out.test_id = n.test_id;
+            break;
+        case "label":
+            out.by = "label";
+            out.label = n.label;
+            break;
+        case "placeholder":
+            out.by = "placeholder";
+            out.placeholder = n.placeholder;
+            break;
+        case "name":
+            out.by = "name";
+            out.name = n.name;
+            break;
+    }
+    if (n.exact !== undefined)
+        out.exact = n.exact;
+    return out;
+}
+//# sourceMappingURL=locator.js.map

package/dist/locator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locator.js","sourceRoot":"","sources":["../src/locator.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function buildServer(): McpServer;

package/dist/server.js

@@ -8,6 +8,8 @@ import { registerInspectTools } from "./tools/inspect.js";
 import { registerConsoleTools } from "./tools/console.js";
 import { registerNetworkTools } from "./tools/network.js";
 import { registerDomTools } from "./tools/dom.js";
+import { registerFormTools } from "./tools/forms.js";
+import { registerStorageTools } from "./tools/storage.js";
 export function buildServer() {
     const server = new McpServer({
         name: "cdp-mcp",
@@ -22,6 +24,8 @@ export function buildServer() {
     registerConsoleTools(server);
     registerNetworkTools(server);
     registerDomTools(server);
+    registerFormTools(server);
+    registerStorageTools(server);
     // The SDK advertises `tools: { listChanged: true }` as soon as any tool is
     // registered, but never emits the matching notification on its own. Some
     // clients (e.g. GitHub Copilot CLI over SSE) gate their first `tools/list`

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD,MAAM,UAAU,WAAW;IACzB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACzB,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC5B,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAChC,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAC/B,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAEzB,2EAA2E;IAC3E,yEAAyE;IACzE,2EAA2E;IAC3E,4EAA4E;IAC5E,2EAA2E;IAC3E,yEAAyE;IACzE,iEAAiE;IACjE,MAAM,CAAC,MAAM,CAAC,aAAa,GAAG,GAAG,EAAE;QACjC,MAAM,CAAC,mBAAmB,EAAE,CAAC;IAC/B,CAAC,CAAC;IAEF,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE1D,MAAM,UAAU,WAAW;IACzB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACzB,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC5B,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAChC,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAC/B,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACzB,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC1B,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAE7B,2EAA2E;IAC3E,yEAAyE;IACzE,2EAA2E;IAC3E,4EAA4E;IAC5E,2EAA2E;IAC3E,yEAAyE;IACzE,iEAAiE;IACjE,MAAM,CAAC,MAAM,CAAC,aAAa,GAAG,GAAG,EAAE;QACjC,MAAM,CAAC,mBAAmB,EAAE,CAAC;IAC/B,CAAC,CAAC;IAEF,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/session/browser.d.ts

@@ -0,0 +1,29 @@
+export interface LaunchArgs {
+    url?: string;
+    headless?: boolean;
+    userDataDir?: string;
+    args?: string[];
+    chromePath?: string;
+    sandbox?: boolean;
+}
+export interface AttachArgs {
+    port?: number;
+    host?: string;
+    targetFilter?: {
+        type?: string;
+        urlIncludes?: string;
+    };
+}
+export declare function launchChrome(opts?: LaunchArgs): Promise<{
+    targetId: string;
+    url: string;
+}>;
+export declare function attachChrome(opts?: AttachArgs): Promise<{
+    targetId: string;
+    url: string;
+}>;
+export declare function closeSession(): Promise<void>;
+export declare function switchTarget(targetId: string): Promise<{
+    targetId: string;
+    url: string;
+}>;

package/dist/session/browser.js

@@ -20,9 +20,24 @@ export async function launchChrome(opts = {}) {
     // (stale) port → ECONNREFUSED on every connect. Don't pass it; let
     // chrome-launcher own port selection. `runningChrome.port` then reflects
     // the actual port Chrome is listening on. (Codex blocker review on PR #11.)
-    const useSandbox = opts.sandbox === true;
+    // Sandbox decision: an explicit `sandbox` arg from the caller always wins.
+    // When the caller omits it, fall back to the CDP_SANDBOX env (default off);
+    // "true" or "1" enable it (matching the eval runner's EVAL_SANDBOX parsing).
+    // This lets a host with a working sandbox path opt a whole run into
+    // sandbox-on (e.g. the L4 eval runner via EVAL_SANDBOX → CDP_SANDBOX)
+    // without prompt-injecting every launch_chrome call. Unset env → false →
+    // the --no-sandbox automation default (unchanged). Explicit `sandbox: false`
+    // still forces --no-sandbox even if the env is set.
+    const sandboxEnv = process.env.CDP_SANDBOX;
+    const useSandbox = opts.sandbox ?? (sandboxEnv === "true" || sandboxEnv === "1");
     const userArgs = opts.args ?? [];
     const userAlreadyDisabled = userArgs.includes("--no-sandbox");
+    // A caller can request the sandbox AND still pass --no-sandbox in args; the
+    // userArgs spread re-adds it last, so Chromium ends up unsandboxed despite the
+    // request. Warn rather than silently dropping the sandbox.
+    if (useSandbox && userAlreadyDisabled) {
+        log.warn("launch_chrome: sandbox requested but --no-sandbox is in args; the flag wins and the sandbox stays OFF");
+    }
     // Snap-confinement auto-profile. When the effective Chrome path (explicit
     // chromePath, or CHROME_PATH env that chrome-launcher will pick up) is
     // under /snap/ AND the caller didn't already specify userDataDir, derive
@@ -57,7 +72,7 @@ export async function launchChrome(opts = {}) {
     const chrome = await launch(launchOpts);
     sessionState.chrome = chrome;
     sessionState.chromePort = chrome.port;
-    log.info("launched chrome", { port: chrome.port, pid: chrome.pid });
+    log.info("launched chrome", { port: chrome.port, pid: chrome.pid, sandbox: useSandbox });
     // Pick the first page target.
     const targets = await waitForFirstPage(chrome.port);
     const target = targets[0];