cdp-mcp 0.1.2 → 0.2.0

package/dist/tools/session.js

@@ -16,7 +16,7 @@ export function registerSessionTools(server) {
         sandbox: z
             .boolean()
             .optional()
-            .describe("Enable Chromium's sandbox. Default false — we add --no-sandbox. On Ubuntu 23.10+ AppArmor restricts the unprivileged user namespace Chromium's sandbox depends on, so unsandboxed launch is the working default for automation. Pass true only on a host with a working sandbox path (AppArmor userns allowance or SUID chrome_sandbox helper)."),
+            .describe("Enable Chromium's sandbox. When omitted, defaults from the CDP_SANDBOX env ('true' or '1' enable it; default false → we add --no-sandbox). On Ubuntu 23.10+ AppArmor restricts the unprivileged user namespace Chromium's sandbox depends on, so unsandboxed launch is the working default for automation. Pass true only on a host with a working sandbox path (AppArmor userns allowance or SUID chrome_sandbox helper)."),
     }, async (input) => {
         return await launchChrome({
             url: input.url,

package/dist/tools/session.js.map

@@ -1 +1 @@
-{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/tools/session.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,GAAG,MAAM,yBAAyB,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC/F,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD,MAAM,UAAU,oBAAoB,CAAC,MAAiB;IACpD,gBAAgB,CACd,MAAM,EACN,eAAe,EACf,2FAA2F,EAC3F;QACE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4CAA4C,CAAC;QACjF,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,cAAc,CAAC;QACzD,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,aAAa,CAAC;QAC5D,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC;QACnE,WAAW,EAAE,CAAC;aACX,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,+RAA+R,CAChS;QACH,OAAO,EAAE,CAAC;aACP,OAAO,EAAE;aACT,QAAQ,EAAE;aACV,QAAQ,CACP,iVAAiV,CAClV;KACJ,EACD,KAAK,EAAE,KAON,EAAE,EAAE;QACH,OAAO,MAAM,YAAY,CAAC;YACxB,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,WAAW,EAAE,KAAK,CAAC,aAAa;YAChC,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,UAAU,EAAE,KAAK,CAAC,WAAW;YAC7B,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB,CAAC,CAAC;IACL,CAAC,CACF,CAAC;IAEF,gBAAgB,CACd,MAAM,EACN,eAAe,EACf,0GAA0G,EAC1G;QACE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,cAAc,CAAC;QACrE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC3B,aAAa,EAAE,CAAC;aACb,MAAM,CAAC;YACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;YAC3B,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;SACpC,CAAC;aACD,QAAQ,EAAE;KACd,EACD,KAAK,EAAE,KAAiG,EAAE,EAAE;QAC1G,OAAO,MAAM,YAAY,CAAC;YACxB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,YAAY,EAAE,KAAK,CAAC,aAAa;gBAC/B,CAAC,CAAC;oBACE,GAAG,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACvE,GAAG,CAAC,KAAK,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,aAAa,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBAC/F;gBACH,CAAC,CAAC,SAAS;SACd,CAAC,CAAC;IACL,CAAC,CACF,CAAC;IAEF,gBAAgB,CACd,MAAM,EACN,eAAe,EACf,oGAAoG,EACpG,SAAS,EACT,KAAK,IAAI,EAAE;QACT,IAAI,CAAC,UAAU,EAAE;YAAE,OAAO,mBAAmB,CAAC;QAC9C,MAAM,YAAY,EAAE,CAAC;QACrB,OAAO,QAAQ,CAAC;IAClB,CAAC,CACF,CAAC;IAEF,gBAAgB,CACd,MAAM,EACN,cAAc,EACd,+EAA+E,EAC/E,SAAS,EACT,KAAK,IAAI,EAAE;QACT,MAAM,CAAC,GAAG,cAAc,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,UAAW,EAAE,CAAC,CAAC;QACxD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACzB,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,GAAG,EAAE,CAAC,CAAC,GAAG;YACV,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,MAAM,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,eAAe;SACnC,CAAC,CAAC,CAAC;IACN,CAAC,CACF,CAAC;IAEF,gBAAgB,CACd,MAAM,EACN,eAAe,EACf,mFAAmF,EACnF,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC,EAAE,EAC1D,KAAK,EAAE,KAAqB,EAAE,EAAE;QAC9B,MAAM,CAAC,GAAG,cAAc,EAAE,CAAC;QAC3B,IAAI,CAAC,CAAC,eAAe,KAAK,KAAK,CAAC,EAAE;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;QACtF,MAAM,CAAC,GAAG,MAAM,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACvC,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAC5D,CAAC,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/tools/session.ts"],"names":[],"mappings":"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"}

package/dist/tools/source.d.ts

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

package/dist/tools/storage.d.ts

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

package/dist/tools/storage.js

@@ -0,0 +1,296 @@
+import { z } from "zod";
+import { readFile, writeFile, rename, rm } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { requireSession } from "../session/state.js";
+import { ToolError } from "../util/errors.js";
+import { registerJsonTool } from "./_register.js";
+/**
+ * Session-portability tools (issue #12 items 4, 5).
+ *
+ * Cookies go through CDP `Network.*` (NOT `document.cookie`) so HttpOnly
+ * auth/session cookies — the whole reason to resume a session — round-trip.
+ * localStorage is read/written via `Runtime.evaluate` (the `Storage.*` domain
+ * is out of scope per AGENTS.md). The on-disk shape is the de-facto Playwright
+ * `storageState` JSON so a flow can be handed to/from mainstream tooling.
+ *
+ * v1 localStorage scope is the **current page origin** only: localStorage is
+ * origin-partitioned and CDP can only read/write it for a document that is
+ * actually on that origin. Cookies (the load-bearing part for auth resume) are
+ * captured/restored for all origins. Multi-origin localStorage restore would
+ * require navigating to each origin first; origins in the file that don't match
+ * the current page are reported in `origins_skipped` rather than silently lost.
+ *
+ * File read/write mirrors `screenshot path=`: no extra path filter — the
+ * operator gate is the same `--allow-remote`/non-loopback rule (README §SSE).
+ */
+const SENSITIVE_NAME = /(sess|sid|token|auth|csrf|xsrf|jwt|secret|api[-_]?key)/i;
+const sameSiteSchema = z.enum(["Strict", "Lax", "None"]);
+const storageStateSchema = z.object({
+    cookies: z
+        .array(z.object({
+        name: z.string(),
+        value: z.string(),
+        domain: z.string(),
+        path: z.string(),
+        expires: z.number().optional(),
+        httpOnly: z.boolean().optional(),
+        secure: z.boolean().optional(),
+        sameSite: sameSiteSchema.optional(),
+    }))
+        .default([]),
+    origins: z
+        .array(z.object({
+        origin: z.string(),
+        localStorage: z.array(z.object({ name: z.string(), value: z.string() })).default([]),
+    }))
+        .default([]),
+});
+const cookieParamSchema = z.object({
+    name: z.string(),
+    value: z.string(),
+    url: z.string().optional().describe("Cookie URL (provide this OR domain)."),
+    domain: z.string().optional(),
+    path: z.string().optional(),
+    secure: z.boolean().optional(),
+    httpOnly: z.boolean().optional(),
+    sameSite: sameSiteSchema.optional(),
+    expires: z.number().optional().describe("Expiry as seconds since epoch; omit for a session cookie."),
+});
+/**
+ * Write `data` to `dest` at mode 0o600, overwrite-safe and TOCTOU-safe.
+ *
+ * The storage-state file holds plaintext cookie secrets, so the 0o600
+ * postcondition must hold even on a shared, world-writable directory. Two traps:
+ *  - Node's writeFile `mode` only applies when it *creates* the file, so writing
+ *    straight to `dest` would leave an existing 0644 file world-readable.
+ *  - A *predictable* temp path lets an attacker pre-create (or symlink) it at
+ *    0644, so the secret gets written through their file and renamed into place.
+ *
+ * So: create a temp with an **unpredictable** same-directory suffix using
+ * exclusive create (`flag: "wx"` ⇒ O_CREAT|O_EXCL — fails on any pre-existing
+ * file and refuses to follow a symlink), which makes 0o600 a real creation-time
+ * guarantee, then atomically rename it over the destination (same filesystem, so
+ * the secret never exists at the destination path in a half-written/0644 state).
+ * Retry on the astronomically-unlikely name collision.
+ */
+async function writeSecretFileAtomic(dest, data) {
+    let lastErr;
+    for (let attempt = 0; attempt < 5; attempt++) {
+        const tmp = `${dest}.${randomBytes(8).toString("hex")}.tmp`;
+        try {
+            await writeFile(tmp, data, { flag: "wx", mode: 0o600 });
+        }
+        catch (e) {
+            if (e.code === "EEXIST") {
+                lastErr = e;
+                continue; // collision (or planted file/symlink) — try a fresh random name
+            }
+            throw e; // ENOENT (missing parent dir), EACCES, etc.
+        }
+        try {
+            await rename(tmp, dest);
+        }
+        catch (e) {
+            await rm(tmp, { force: true }).catch(() => { });
+            throw e;
+        }
+        return;
+    }
+    throw lastErr;
+}
+export function registerStorageTools(server) {
+    registerJsonTool(server, "export_storage_state", "Save the browser session (all cookies including HttpOnly, plus the current page origin's localStorage) to a JSON file in the de-facto Playwright storageState shape, so a flow can be resumed in a fresh session or handed to other tooling. The file preserves full cookie values (it exists to resume auth) — treat it as a secret. File write is gated by the same operator rule as screenshot path= / --allow-remote.", { path: z.string().describe("Absolute path to write the storageState JSON to.") }, async (input) => {
+        const s = requireSession();
+        const { cookies } = (await s.client.send("Network.getAllCookies"));
+        const probe = await s.client.send("Runtime.evaluate", {
+            expression: READ_ORIGIN_AND_LOCALSTORAGE,
+            returnByValue: true,
+        });
+        const probed = (probe.result?.value ?? { origin: "null", localStorage: [] });
+        const origins = probed.origin && probed.origin !== "null"
+            ? [{ origin: probed.origin, localStorage: probed.localStorage }]
+            : [];
+        const state = { cookies: cookies.map(cdpCookieToState), origins };
+        // The file holds full cookie values (incl. HttpOnly auth/session tokens) —
+        // the description says "treat it as a secret". writeSecretFileAtomic writes
+        // it 0o600 and overwrite-safe (see the helper for the threat model).
+        try {
+            await writeSecretFileAtomic(input.path, JSON.stringify(state, null, 2));
+        }
+        catch (e) {
+            if (e.code === "ENOENT") {
+                throw new ToolError("not_found", `could not write storage-state file (does the parent directory exist?): ${e.message}`);
+            }
+            throw e; // EACCES/EISDIR/etc. surface as internal_error via registerJsonTool
+        }
+        return { saved: input.path, cookies: state.cookies.length, origins: origins.length };
+    });
+    registerJsonTool(server, "load_storage_state", "Restore a session from a Playwright-shaped storageState JSON file: sets all cookies (no navigation needed), then restores localStorage for the entries whose origin matches the current page. Cookies are added on top of the existing jar (additive, not a clean-context replace), so prefer a fresh session for Playwright-equivalent semantics. Origins that don't match the current page are returned in origins_skipped (restoring them would require navigating there first). File read is gated by the same operator rule as screenshot path= / --allow-remote.", { path: z.string().describe("Absolute path to a storageState JSON file (as written by export_storage_state).") }, async (input) => {
+        const s = requireSession();
+        let raw;
+        try {
+            raw = await readFile(input.path, "utf8");
+        }
+        catch (e) {
+            if (e.code === "ENOENT") {
+                throw new ToolError("not_found", `could not read storage-state file: ${e.message}`);
+            }
+            throw e; // EACCES/EISDIR/etc. surface as internal_error rather than masquerading as not_found
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new ToolError("invalid_arg", "storage-state file is not valid JSON");
+        }
+        const result = storageStateSchema.safeParse(parsed);
+        if (!result.success) {
+            throw new ToolError("invalid_arg", `storage-state file is not a valid storageState: ${result.error.message}`);
+        }
+        const state = result.data;
+        if (state.cookies.length > 0) {
+            await s.client.send("Network.setCookies", { cookies: state.cookies.map(stateCookieToCdp) });
+        }
+        const restore = await s.client.send("Runtime.evaluate", {
+            expression: restoreLocalStorageExpr(state.origins),
+            returnByValue: true,
+        });
+        const restored = (restore.result?.value ?? { restored: [], skipped: state.origins.map((o) => o.origin) });
+        return {
+            loaded: input.path,
+            cookies: state.cookies.length,
+            origins_restored: restored.restored,
+            origins_skipped: restored.skipped,
+        };
+    });
+    registerJsonTool(server, "get_cookies", "List cookies (via CDP, so HttpOnly cookies are included) with their flags. For safe printing, the VALUE of likely session/auth cookies is redacted (httpOnly cookies, or names matching sess/sid/token/auth/csrf/jwt/secret/api-key); only value_length is shown for those. Full values are obtainable only through export_storage_state.", {
+        urls: z
+            .array(z.string())
+            .optional()
+            .describe("Restrict to cookies visible to these URLs; omit for all cookies in the browser."),
+    }, async (input) => {
+        const s = requireSession();
+        const res = (input.urls && input.urls.length > 0
+            ? await s.client.send("Network.getCookies", { urls: input.urls })
+            : await s.client.send("Network.getAllCookies"));
+        return { cookies: res.cookies.map(redactForDisplay) };
+    });
+    registerJsonTool(server, "set_cookies", "Set one or more cookies in the browser cookie jar via CDP. Each cookie needs a url OR a domain. For restoring a saved session, prefer load_storage_state; this is the lower-level primitive.", { cookies: z.array(cookieParamSchema).describe("Cookies to set.") }, async (input) => {
+        const s = requireSession();
+        if (input.cookies.length === 0)
+            throw new ToolError("missing_arg", "cookies array is empty");
+        const missing = input.cookies.find((c) => !c.url && !c.domain);
+        if (missing)
+            throw new ToolError("missing_arg", `cookie '${missing.name}' needs a url or domain`);
+        // Normalize the session-cookie sentinel the same way load_storage_state
+        // does, so an exported `expires: -1` piped in here isn't sent as a 1969 expiry.
+        await s.client.send("Network.setCookies", {
+            cookies: input.cookies.map(withSessionExpiryOmitted),
+        });
+        return { set: input.cookies.length };
+    });
+}
+function cdpCookieToState(c) {
+    return {
+        name: c.name,
+        value: c.value,
+        domain: c.domain,
+        path: c.path,
+        // CDP uses -1 (or a missing field) for session cookies; Playwright too.
+        expires: typeof c.expires === "number" ? c.expires : -1,
+        httpOnly: !!c.httpOnly,
+        secure: !!c.secure,
+        // Playwright requires sameSite; CDP may omit it. Lax is the browser default.
+        sameSite: c.sameSite ?? "Lax",
+    };
+}
+/**
+ * CDP's `Network.setCookies` reads `expires` as an absolute epoch-seconds
+ * timestamp, so the session-cookie sentinel (`-1`, which `export_storage_state`
+ * writes) must be dropped rather than forwarded — otherwise the cookie is set
+ * already-expired (1969) and silently rejected. Shared by `load_storage_state`
+ * and `set_cookies` so both restore paths normalize identically.
+ */
+function withSessionExpiryOmitted(cookie) {
+    if (typeof cookie.expires === "number" && cookie.expires >= 0)
+        return cookie;
+    const copy = { ...cookie };
+    delete copy.expires;
+    return copy;
+}
+function stateCookieToCdp(c) {
+    const param = {
+        name: c.name,
+        value: c.value,
+        domain: c.domain,
+        path: c.path,
+        secure: !!c.secure,
+        httpOnly: !!c.httpOnly,
+        expires: c.expires,
+    };
+    if (c.sameSite)
+        param.sameSite = c.sameSite;
+    // -1 / undefined means a session cookie — omit expires entirely.
+    return withSessionExpiryOmitted(param);
+}
+function redactForDisplay(c) {
+    const redacted = !!c.httpOnly || SENSITIVE_NAME.test(c.name);
+    const out = {
+        name: c.name,
+        domain: c.domain,
+        path: c.path,
+        expires: typeof c.expires === "number" ? c.expires : -1,
+        httpOnly: !!c.httpOnly,
+        secure: !!c.secure,
+        sameSite: c.sameSite ?? null,
+        redacted,
+        value_length: (c.value ?? "").length,
+    };
+    if (!redacted)
+        out.value = c.value;
+    return out;
+}
+// ---------------------------------------------------------------------------
+// In-page expressions
+/** Read the current origin and its localStorage as { origin, localStorage:[{name,value}] }. */
+const READ_ORIGIN_AND_LOCALSTORAGE = String.raw `(() => {
+  const items = [];
+  try {
+    for (let i = 0; i < localStorage.length; i++) {
+      const k = localStorage.key(i);
+      if (k === null) continue;
+      const v = localStorage.getItem(k);
+      if (v === null) continue;
+      items.push({ name: k, value: v });
+    }
+  } catch (e) {}
+  return { origin: location.origin, localStorage: items };
+})()`;
+/**
+ * For each origin in the file whose origin matches the current page, write its
+ * localStorage entries; report which origins were restored vs skipped.
+ */
+function restoreLocalStorageExpr(origins) {
+    return String.raw `(() => {
+    const origins = ${JSON.stringify(origins)};
+    const current = location.origin;
+    const restored = [];
+    const skipped = [];
+    for (const o of origins) {
+      if (o.origin !== current) {
+        skipped.push(o.origin);
+        continue;
+      }
+      // If any setItem throws (quota exceeded, storage disabled), report the
+      // origin as skipped rather than misleadingly claiming it was restored.
+      let ok = true;
+      for (const it of o.localStorage) {
+        try { localStorage.setItem(it.name, it.value); } catch (e) { ok = false; }
+      }
+      (ok ? restored : skipped).push(o.origin);
+    }
+    return { restored, skipped };
+  })()`;
+}
+//# sourceMappingURL=storage.js.map

package/dist/tools/storage.js.map

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

package/dist/util/browser-resolve.d.ts

@@ -0,0 +1,19 @@
+export type BrowserChoice = "chromium" | "chrome";
+export interface ResolvedBrowser {
+    /** Absolute path to the Chrome/Chromium executable. */
+    binaryPath: string;
+    /** Which logical browser this binary represents. */
+    choice: BrowserChoice;
+    /** True when the binary is snap-confined (/snap/bin/* on Linux). Triggers
+     *  the user-data-dir workaround in launch_chrome. */
+    snapConfined: boolean;
+    /** Diagnostic — which resolution step produced this. */
+    source: "CDP_TEST_BROWSER_PATH" | "which-chromium" | "playwright-cache" | "chrome-launcher-default";
+}
+export declare function getBrowserChoice(): BrowserChoice;
+export declare function resolveBrowser(choice?: BrowserChoice): ResolvedBrowser;
+/** True when the given binary is the snap-marker returned by step 4. */
+export declare function isChromeLauncherDefault(b: ResolvedBrowser): boolean;
+/** Determine the user-data-dir for snap-confined Chromium. Snap confinement
+ *  rejects /tmp/... paths; only ~/snap/<app>/current/ is writable. */
+export declare function snapUserDataDir(binaryPath: string): string;

package/dist/util/errors.d.ts

@@ -0,0 +1,7 @@
+export declare class ToolError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+export declare const noSession: () => ToolError;
+export declare const notPaused: () => ToolError;
+export declare const alreadySession: () => ToolError;

package/dist/util/format.d.ts

@@ -0,0 +1,20 @@
+import type { Protocol } from "devtools-protocol";
+export declare function truncate(s: string, max?: number): string;
+export declare function previewRemoteObject(obj: Protocol.Runtime.RemoteObject): string;
+export declare function describeRemote(obj: Protocol.Runtime.RemoteObject): {
+    type: string;
+    preview: string;
+    objectId?: string;
+};
+export declare function toolText(text: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function toolJson(value: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};

package/dist/util/log.d.ts

@@ -0,0 +1,6 @@
+export declare const log: {
+    debug: (msg: string, meta?: Record<string, unknown>) => void;
+    info: (msg: string, meta?: Record<string, unknown>) => void;
+    warn: (msg: string, meta?: Record<string, unknown>) => void;
+    error: (msg: string, meta?: Record<string, unknown>) => void;
+};

package/docs/chromium-sandboxing.md

@@ -0,0 +1,197 @@
+# Chromium sandboxing
+
+**Last updated: 2026-05-16**
+
+This project launches Chromium in two different contexts:
+
+- L3 e2e tests and L4 evals launch a real browser through `launch_chrome`.
+- Agents then control that browser through CDP, including `Runtime.evaluate`,
+  `Debugger.*`, DOM interaction, console inspection, and network inspection.
+
+That makes sandboxing a host setup and threat-model decision, not just a
+Chrome flag. This document is the canonical reference for `--no-sandbox`,
+AppArmor, unprivileged user namespaces, snap confinement, and Bubblewrap.
+
+## Current default
+
+`launch_chrome` defaults to `sandbox: false`, which adds `--no-sandbox`.
+
+The default exists because Ubuntu 23.10+ and 24.04 commonly restrict
+unprivileged user namespaces through AppArmor. Playwright-bundled Chromium
+does not ship with a SUID `chrome_sandbox` helper. On those hosts, launching
+Chromium without `--no-sandbox` can fail before the DevTools port opens:
+
+```text
+zygote_host_impl_linux.cc: No usable sandbox!
+```
+
+From `chrome-launcher`, that often surfaces as a startup port poll timeout or
+`ECONNREFUSED`.
+
+Other Linux distributions may allow Chromium's unprivileged user namespace
+sandbox path by default. Validate the actual host before assuming the Ubuntu
+automation default is necessary there.
+
+Use `sandbox: true` only when the host has a working Chromium sandbox path:
+
+- An AppArmor policy that permits the specific Chromium binary to create the
+  unprivileged user namespace it needs.
+- Or a working SUID `chrome_sandbox` helper installed alongside that binary.
+
+## Why the Chromium sandbox still matters
+
+The MCP caller is already highly privileged relative to the page. It can ask
+the server to evaluate JavaScript, drive the DOM, set breakpoints, inspect
+scopes, and read browser-observed network activity. For that caller, the
+Chromium renderer sandbox is not the primary trust boundary.
+
+The Chromium sandbox still matters for hostile page content and browser
+exploitation risk. With the sandbox enabled, Chromium isolates renderer, GPU,
+and utility child processes from the browser process using mechanisms such as
+namespaces, seccomp filters, brokered filesystem access, and per-process
+capability reduction. With `--no-sandbox`, a compromised renderer has a much
+larger blast radius inside the browser process tree.
+
+So the project default is a pragmatic automation default, not a claim that
+`--no-sandbox` is equally safe.
+
+## How the mechanisms relate
+
+These mechanisms solve different problems:
+
+- Chromium sandbox: Chromium's internal process sandbox. It is the boundary
+  between web content renderer processes and the rest of the browser.
+- AppArmor: host-enforced mandatory access control. It can confine Chromium,
+  and on recent Ubuntu systems it can also restrict whether an unprivileged
+  process may create user namespaces.
+- Snap confinement: the packaging sandbox used by snap-installed Chromium.
+  It can hide or remap filesystem locations and has caused DevTools port and
+  `userDataDir` friction in local runs.
+- Bubblewrap (`bwrap`): a small Linux sandboxing tool that starts a process in
+  new namespaces with a controlled filesystem, process, and optional network
+  view.
+
+Bubblewrap is useful defense-in-depth around a browser or eval job. For
+example, it can run the whole MCP server plus browser process tree with only
+the repository and selected temp/profile directories writable. That helps
+prevent accidental or malicious access to unrelated files such as SSH keys,
+cloud credentials, or the rest of the home directory.
+
+Bubblewrap is not a clean substitute for Chromium's own sandbox. If Chromium
+runs with `--no-sandbox` inside Bubblewrap, the entire browser process tree is
+inside an outer container-like boundary, but Chromium's internal renderer
+isolation is still disabled. A renderer compromise may be contained by the
+outer Bubblewrap filesystem or network policy, but it is not contained in the
+same way as Chromium's per-renderer sandbox.
+
+## Recommended posture
+
+Local development:
+
+- Treat the current default, `sandbox: false`, as a host-capability fallback:
+  it keeps work moving when Chromium sandbox setup is the blocker.
+- Prefer `sandbox: true` once the host has a known-good Chromium sandbox path.
+
+CI and L4 eval hosts:
+
+- Keep the default working and deterministic. If `--no-sandbox` is needed for
+  Playwright-bundled Chromium on Ubuntu, document that in the host setup.
+- Consider running the whole job inside an outer sandbox, VM, container, or
+  Bubblewrap profile with a throwaway browser profile and limited writable
+  paths.
+
+Untrusted browsing:
+
+- Prefer Chromium's sandbox on.
+- Use a throwaway `userDataDir`.
+- Add host-level confinement such as AppArmor, a container, VM, or Bubblewrap.
+- Do not treat `bwrap + --no-sandbox` as equivalent to Chromium sandboxing.
+
+This outer containment also pairs with the agent-operator threat (prompt-injected
+page content steering the agent into actions or unscoped filesystem writes); see
+the agent-operator threat model and deployment hardening in
+[SECURITY.md](../SECURITY.md). A containerized outer-sandbox run mode that would
+make this contained posture the default is a direction under consideration.
+
+## Validated hosts
+
+Hosts where `sandbox: true` has been verified working against this project, with the supporting posture:
+
+| Host | OS | Arch | `sandbox: true` | AppArmor profile | Notes |
+|---|---|---|---|---|---|
+| Ubuntu 24.04 arm64 (Parallels VM) | Ubuntu 24.04 | arm64 | ✓ | `/etc/apparmor.d/cdp-mcp-chromium` (named-unconfined, mirrors Ubuntu's stock `chrome` / `msedge` / `brave`) | `kernel.apparmor_restrict_unprivileged_userns = 0` was set as a side effect of enabling Bubblewrap, so the kernel-level userns restriction is already off system-wide. The AppArmor profile gives Playwright Chromium a stable named label (instead of `unconfined`) and grants `userns,` explicitly, so `sandbox: true` keeps working even if a future kernel/package update flips the global knob back to `1`. |
+
+When adding a new host to this table:
+
+1. Run the smoke tests below and capture the values.
+2. If `kernel.apparmor_restrict_unprivileged_userns` is `1` (Ubuntu's stock default) and `sandbox: true` is desired, install a profile under `/etc/apparmor.d/` mirroring Ubuntu's stock `chrome` / `msedge` / `brave` shape:
+   ```apparmor
+   abi <abi/4.0>,
+   include <tunables/global>
+
+   profile cdp-mcp-chromium /path/to/chromium flags=(unconfined) {
+     userns,
+     include if exists <local/cdp-mcp-chromium>
+   }
+   ```
+   Load with `sudo apparmor_parser -r /etc/apparmor.d/cdp-mcp-chromium`. The profile auto-loads at boot from `/etc/apparmor.d/`.
+3. Verify the running browser process is labelled correctly:
+   ```sh
+   cat /proc/<chromium-pid>/attr/current
+   ```
+   Expect the profile name (e.g. `cdp-mcp-chromium (unconfined)`), not `unconfined` alone.
+4. Add a row to the table above.
+
+Other hosts to characterize as they come online: Fedora — Fedora uses SELinux rather than AppArmor and ships userns enabled by default, so `sandbox: true` is expected to work without host-side profile work. The `dnf install bubblewrap` path is also first-class on Fedora.
+
+## Smoke tests
+
+Check whether unprivileged user namespaces are enabled:
+
+```sh
+cat /proc/sys/kernel/unprivileged_userns_clone
+cat /proc/sys/user/max_user_namespaces
+```
+
+Expected working values are usually `1` for
+`kernel.unprivileged_userns_clone` and a nonzero number for
+`user.max_user_namespaces`.
+
+On Ubuntu, AppArmor may still restrict unprivileged user namespaces:
+
+```sh
+sysctl kernel.apparmor_restrict_unprivileged_userns
+```
+
+Minimal Bubblewrap smoke tests:
+
+```sh
+bwrap --unshare-user --uid 0 --gid 0 --ro-bind / / /usr/bin/true
+bwrap --unshare-user --uid 0 --gid 0 --unshare-net --ro-bind / / /usr/bin/true
+```
+
+If the first command fails with `setting up uid map: Permission denied`, the
+host still blocks the user namespace setup Bubblewrap needs.
+
+If the second command fails with `loopback: Failed RTM_NEWADDR: Operation not
+permitted`, the network namespace setup is still blocked.
+
+Project-level browser check:
+
+```sh
+npm run test:e2e
+```
+
+For a direct MCP check, call `launch_chrome` with `sandbox: true` on the host
+you want to validate. If Chromium cannot create a usable sandbox, it will fail
+before exposing its DevTools target.
+
+## Decision summary
+
+- `--no-sandbox` remains the automation default because it keeps Ubuntu
+  Playwright-Chromium runs working.
+- `sandbox: true` is the preferred security posture when the host supports it.
+- AppArmor is the long-term host policy path for allowing Chromium's needed
+  user namespace behavior narrowly.
+- Bubblewrap is an outer containment layer and is valuable defense-in-depth.
+- Bubblewrap does not replace Chromium's internal renderer sandbox.