browxai 0.7.0

package/dist/tools/storage-cache-idb-tools.js

@@ -0,0 +1,347 @@
+import { withDeadline } from "../util/deadline.js";
+import { confirmByobAction } from "../policy/confirm.js";
+import { SESSION_ARG } from "./schemas.js";
+/**
+ * Cache API + IndexedDB tools: caches_* (list_storages / list / get / put / delete
+ * / clear / delete_storage) and idb_* (list_databases / list_stores / get / put /
+ * delete / clear). Split out of `storage-tools` by cohesive family (RFC 0004 P3 /
+ * D3 SRP); registered through the shared `ToolHost` seam in the same source order.
+ */
+export function registerStorageCacheIdbTools(host) {
+    const { z, register, gateCheck, entryFor, okText, errText, confirmCtxFor, denyContent, storageFor, cfgActionTimeout, } = host;
+    // ---- Cache API -------------------------------------------------------------
+    register("caches_list_storages", {
+        capability: "read",
+        description: "List every cache storage visible to the current page's origin (`caches.keys()`). Cache API is ORIGIN-SCOPED — the session must be navigated to the target origin first; about:blank rejects with a navigation hint. Returns `{names:[...], origin}`. Read-only.",
+        inputSchema: { ...SESSION_ARG },
+    }, async ({ session }) => {
+        const g = gateCheck("caches_list_storages");
+        if (g)
+            return g;
+        try {
+            const e = await entryFor(session);
+            const r = await withDeadline(storageFor(e).cachesListStorages("caches_list_storages"), cfgActionTimeout(), "caches_list_storages");
+            return okText({ ok: true, count: r.names.length, ...r });
+        }
+        catch (err) {
+            return errText("caches_list_storages", err);
+        }
+    });
+    register("caches_list", {
+        capability: "read",
+        description: "List entries in one cache. Returns `{entries:[{url, method}], origin, cacheName}`. Optional `urlPattern` is a case-sensitive substring filter on each entry's URL (no regex — adopters wanting richer filtering can post-filter the result). Origin-scoped — navigate first. Read-only.",
+        inputSchema: {
+            cacheName: z.string().describe("Cache storage name."),
+            urlPattern: z
+                .string()
+                .optional()
+                .describe("Optional substring filter on each entry's `request.url`."),
+            ...SESSION_ARG,
+        },
+    }, async ({ cacheName, urlPattern, session }) => {
+        const g = gateCheck("caches_list");
+        if (g)
+            return g;
+        try {
+            const e = await entryFor(session);
+            const r = await withDeadline(storageFor(e).cachesList({ cacheName, urlPattern }, "caches_list"), cfgActionTimeout(), "caches_list");
+            return okText({ ok: true, count: r.entries.length, ...r });
+        }
+        catch (err) {
+            return errText("caches_list", err);
+        }
+    });
+    register("caches_get", {
+        capability: "read",
+        description: 'Read the response body of a single cache entry. Text-like content types (`text/*`, `application/json|javascript|xml|x-www-form-urlencoded`, or anything with a `charset=`) arrive as `{kind:"text", text}`. Everything else arrives as `{kind:"binary", contentBase64, byteLength}`. `{found:false}` if no entry matches the URL. Origin-scoped — navigate first. Read-only.',
+        inputSchema: {
+            cacheName: z.string().describe("Cache storage name."),
+            url: z.string().describe("Entry URL key."),
+            ...SESSION_ARG,
+        },
+    }, async ({ cacheName, url, session }) => {
+        const g = gateCheck("caches_get");
+        if (g)
+            return g;
+        try {
+            const e = await entryFor(session);
+            const r = await withDeadline(storageFor(e).cachesGet({ cacheName, url }, "caches_get"), cfgActionTimeout(), "caches_get");
+            return okText({ ok: true, ...r });
+        }
+        catch (err) {
+            return errText("caches_get", err);
+        }
+    });
+    register("caches_put", {
+        capability: "action",
+        description: "Put one entry in a cache. `response.body` is a UTF-8 string (default); for binary content pass `response.contentBase64` instead — exactly one of the two. Optional `response.status` (default 200) and `response.headers` build the `Response`. Auto-opens (= creates) the named cache storage if it doesn't exist. Origin-scoped — navigate first.",
+        inputSchema: {
+            cacheName: z.string().describe("Cache storage name (auto-created)."),
+            url: z.string().describe("Entry URL key."),
+            response: z
+                .object({
+                status: z.number().optional().describe("HTTP status (default 200)."),
+                headers: z.record(z.string()).optional().describe("Response headers."),
+                body: z
+                    .string()
+                    .optional()
+                    .describe("UTF-8 string body. Mutually exclusive with `contentBase64`."),
+                contentBase64: z
+                    .string()
+                    .optional()
+                    .describe("Base64-encoded binary body. Mutually exclusive with `body`."),
+            })
+                .describe("Response shape — body+headers+status."),
+            ...SESSION_ARG,
+        },
+    }, async ({ cacheName, url, response, session }) => {
+        const g = gateCheck("caches_put");
+        if (g)
+            return g;
+        try {
+            const e = await entryFor(session);
+            const c = await confirmByobAction("caches_put", confirmCtxFor(e));
+            if (!c.ok)
+                return denyContent("caches_put", c);
+            const r = await withDeadline(storageFor(e).cachesPut({ cacheName, url, response }, "caches_put"), cfgActionTimeout(), "caches_put");
+            return okText({ ...r });
+        }
+        catch (err) {
+            return errText("caches_put", err);
+        }
+    });
+    register("caches_delete", {
+        capability: "action",
+        description: "Delete one entry from a cache. Returns `existed:true` when a record was present (idempotent — repeat calls return `existed:false`). Origin-scoped — navigate first.",
+        inputSchema: {
+            cacheName: z.string().describe("Cache storage name."),
+            url: z.string().describe("Entry URL key."),
+            ...SESSION_ARG,
+        },
+    }, async ({ cacheName, url, session }) => {
+        const g = gateCheck("caches_delete");
+        if (g)
+            return g;
+        try {
+            const e = await entryFor(session);
+            const c = await confirmByobAction("caches_delete", confirmCtxFor(e));
+            if (!c.ok)
+                return denyContent("caches_delete", c);
+            const r = await withDeadline(storageFor(e).cachesDelete({ cacheName, url }, "caches_delete"), cfgActionTimeout(), "caches_delete");
+            return okText({ ...r });
+        }
+        catch (err) {
+            return errText("caches_delete", err);
+        }
+    });
+    register("caches_clear", {
+        capability: "action",
+        description: "Clear every entry in a cache (the cache storage itself remains — use `caches_delete_storage` to drop the whole storage). Returns `cleared:N` (the count removed). Origin-scoped — navigate first.",
+        inputSchema: {
+            cacheName: z.string().describe("Cache storage name."),
+            ...SESSION_ARG,
+        },
+    }, async ({ cacheName, session }) => {
+        const g = gateCheck("caches_clear");
+        if (g)
+            return g;
+        try {
+            const e = await entryFor(session);
+            const c = await confirmByobAction("caches_clear", confirmCtxFor(e));
+            if (!c.ok)
+                return denyContent("caches_clear", c);
+            const r = await withDeadline(storageFor(e).cachesClear({ cacheName }, "caches_clear"), cfgActionTimeout(), "caches_clear");
+            return okText({ ...r });
+        }
+        catch (err) {
+            return errText("caches_clear", err);
+        }
+    });
+    register("caches_delete_storage", {
+        capability: "action",
+        description: "Delete a cache storage entirely (`caches.delete(name)`). Returns `existed:true` when the storage was present (idempotent). To clear entries while keeping the storage, use `caches_clear`. Origin-scoped — navigate first.",
+        inputSchema: {
+            cacheName: z.string().describe("Cache storage name to delete."),
+            ...SESSION_ARG,
+        },
+    }, async ({ cacheName, session }) => {
+        const g = gateCheck("caches_delete_storage");
+        if (g)
+            return g;
+        try {
+            const e = await entryFor(session);
+            const c = await confirmByobAction("caches_delete_storage", confirmCtxFor(e));
+            if (!c.ok)
+                return denyContent("caches_delete_storage", c);
+            const r = await withDeadline(storageFor(e).cachesDeleteStorage({ cacheName }, "caches_delete_storage"), cfgActionTimeout(), "caches_delete_storage");
+            return okText({ ...r });
+        }
+        catch (err) {
+            return errText("caches_delete_storage", err);
+        }
+    });
+    // ---- IndexedDB ------------------------------------------------------------
+    register("idb_list_databases", {
+        capability: "read",
+        description: "Enumerate every IndexedDB database visible to the current page's origin (`indexedDB.databases()`). Returns `{databases:[{name, version}], origin, supported}`. `supported:false` on engines that don't expose `indexedDB.databases()` (older non-Chromium browsers) — the storage is still readable per-database via `idb_list_stores({dbName})`, you just have to know the names. IndexedDB is ORIGIN-SCOPED — navigate first. Read-only.",
+        inputSchema: { ...SESSION_ARG },
+    }, async ({ session }) => {
+        const g = gateCheck("idb_list_databases");
+        if (g)
+            return g;
+        try {
+            const e = await entryFor(session);
+            const r = await withDeadline(storageFor(e).idbListDatabases("idb_list_databases"), cfgActionTimeout(), "idb_list_databases");
+            return okText({ ok: true, count: r.databases.length, ...r });
+        }
+        catch (err) {
+            return errText("idb_list_databases", err);
+        }
+    });
+    register("idb_list_stores", {
+        capability: "read",
+        description: "List the object-store names inside a database. Read-only — does NOT trigger an upgrade transaction, so it will only see stores that already exist. Returns `{stores:[...], dbName, version, origin}`. Origin-scoped — navigate first.",
+        inputSchema: {
+            dbName: z.string().describe("Database name."),
+            ...SESSION_ARG,
+        },
+    }, async ({ dbName, session }) => {
+        const g = gateCheck("idb_list_stores");
+        if (g)
+            return g;
+        try {
+            const e = await entryFor(session);
+            const r = await withDeadline(storageFor(e).idbListStores({ dbName }, "idb_list_stores"), cfgActionTimeout(), "idb_list_stores");
+            return okText({ ok: true, count: r.stores.length, ...r });
+        }
+        catch (err) {
+            return errText("idb_list_stores", err);
+        }
+    });
+    register("idb_get", {
+        capability: "read",
+        description: "Get the value at a key in an object store. Returns `{found:true, value}` or `{found:false}`. KEY SHAPES: IDB natively accepts strings, numbers, dates, and arrays as keys — all four shapes round-trip through JSON cleanly (Dates as ISO strings; pass the ISO string back in on subsequent calls). VALUE SHAPES: IDB stores structured-clonable values (Blob/ArrayBuffer/Map/Set/Date), but this tool returns over MCP's JSON-only transport — non-JSON-serialisable values surface as a structured error (the platform value is preserved IN the store; it just can't ride the wire). For binary payloads, store them base64-encoded at the app level. **JSON-string fidelity**: if the app under test stored a value via `JSON.stringify(obj)` (a localStorage-habit common in older code), `idb_get` returns the raw JSON STRING verbatim — IDB faithfully preserves shape, and browxai does NOT auto-detect-and-parse stringified values because some apps legitimately store JSON strings as strings. Call-site responsibility: `JSON.parse` if you expect an object. The companion `idb_put` warning surfaces the opposite footgun (an MCP client double-encoding the input). Origin-scoped — navigate first. Read-only.",
+        inputSchema: {
+            dbName: z.string().describe("Database name."),
+            storeName: z.string().describe("Object store name (must exist)."),
+            key: z
+                .union([z.string(), z.number(), z.array(z.union([z.string(), z.number()]))])
+                .describe("Primary key — string, number, or array of strings/numbers."),
+            ...SESSION_ARG,
+        },
+    }, async ({ dbName, storeName, key, session }) => {
+        const g = gateCheck("idb_get");
+        if (g)
+            return g;
+        try {
+            const e = await entryFor(session);
+            const r = await withDeadline(storageFor(e).idbGet({ dbName, storeName, key }, "idb_get"), cfgActionTimeout(), "idb_get");
+            return okText({ ok: true, ...r });
+        }
+        catch (err) {
+            return errText("idb_get", err);
+        }
+    });
+    register("idb_put", {
+        capability: "action",
+        description: "Put a value at a key in an object store. The object store MUST already exist — this tool does not create stores (store creation requires an IDB upgrade transaction, which is the app's schema concern). `value` is anything JSON-serialisable; non-JSON inputs reject at MCP-validation time. If the store uses an in-line keyPath, `key` is ignored (the keyPath read off `value` is authoritative); otherwise `key` becomes the out-of-line primary key. Origin-scoped — navigate first.",
+        inputSchema: {
+            dbName: z.string().describe("Database name (must exist)."),
+            storeName: z.string().describe("Object store name (must exist)."),
+            key: z
+                .union([z.string(), z.number(), z.array(z.union([z.string(), z.number()]))])
+                .describe("Primary key — string, number, or array. Ignored if the store uses an in-line keyPath."),
+            value: z.unknown().describe("JSON-serialisable value to store."),
+            ...SESSION_ARG,
+        },
+    }, async ({ dbName, storeName, key, value, session }) => {
+        const g = gateCheck("idb_put");
+        if (g)
+            return g;
+        try {
+            const e = await entryFor(session);
+            const c = await confirmByobAction("idb_put", confirmCtxFor(e));
+            if (!c.ok)
+                return denyContent("idb_put", c);
+            // Defensive: if `value` reaches the handler as a JSON-shaped string
+            // (some MCP clients double-encode complex args), the page-side path
+            // faithfully stores a string — adopter wrote an object, IDB holds
+            // a string, app reads back a string. Surface the case as a warning
+            // without auto-parsing (some apps legitimately store JSON strings).
+            const warnings = [];
+            if (typeof value === "string" && value.length > 1) {
+                const first = value[0];
+                if (first === "{" || first === "[") {
+                    try {
+                        const parsed = JSON.parse(value);
+                        if (parsed !== null && typeof parsed === "object") {
+                            warnings.push("idb_put: `value` arrived as a JSON-encoded STRING (e.g. `'{\"k\":1}'`). " +
+                                "browxai stored it verbatim as a string — IDB now holds a string, not the parsed object. " +
+                                "Most MCP clients pass structured args directly; if yours double-encodes complex values, " +
+                                "JSON.parse them client-side before calling idb_put. Use idb_get to confirm what was written.");
+                        }
+                    }
+                    catch {
+                        /* not JSON; plain string — no warning */
+                    }
+                }
+            }
+            const r = await withDeadline(storageFor(e).idbPut({ dbName, storeName, key, value }, "idb_put"), cfgActionTimeout(), "idb_put");
+            return okText({ ...r, ...(warnings.length > 0 ? { warnings } : {}) });
+        }
+        catch (err) {
+            return errText("idb_put", err);
+        }
+    });
+    register("idb_delete", {
+        capability: "action",
+        description: "Delete the value at a key in an object store. Idempotent — returns the same shape whether or not a record was there. Origin-scoped — navigate first.",
+        inputSchema: {
+            dbName: z.string().describe("Database name."),
+            storeName: z.string().describe("Object store name."),
+            key: z
+                .union([z.string(), z.number(), z.array(z.union([z.string(), z.number()]))])
+                .describe("Primary key to delete."),
+            ...SESSION_ARG,
+        },
+    }, async ({ dbName, storeName, key, session }) => {
+        const g = gateCheck("idb_delete");
+        if (g)
+            return g;
+        try {
+            const e = await entryFor(session);
+            const c = await confirmByobAction("idb_delete", confirmCtxFor(e));
+            if (!c.ok)
+                return denyContent("idb_delete", c);
+            const r = await withDeadline(storageFor(e).idbDelete({ dbName, storeName, key }, "idb_delete"), cfgActionTimeout(), "idb_delete");
+            return okText({ ...r });
+        }
+        catch (err) {
+            return errText("idb_delete", err);
+        }
+    });
+    register("idb_clear", {
+        capability: "action",
+        description: "Clear every record from an object store (the store itself remains). Origin-scoped — navigate first.",
+        inputSchema: {
+            dbName: z.string().describe("Database name."),
+            storeName: z.string().describe("Object store name."),
+            ...SESSION_ARG,
+        },
+    }, async ({ dbName, storeName, session }) => {
+        const g = gateCheck("idb_clear");
+        if (g)
+            return g;
+        try {
+            const e = await entryFor(session);
+            const c = await confirmByobAction("idb_clear", confirmCtxFor(e));
+            if (!c.ok)
+                return denyContent("idb_clear", c);
+            const r = await withDeadline(storageFor(e).idbClear({ dbName, storeName }, "idb_clear"), cfgActionTimeout(), "idb_clear");
+            return okText({ ...r });
+        }
+        catch (err) {
+            return errText("idb_clear", err);
+        }
+    });
+}

package/dist/tools/storage-state-cookies-tools.d.ts

@@ -0,0 +1,8 @@
+import type { RegisterHost, GateHost, SessionHost, ConfigHost, EnvelopeHost, StorageHost, ActionHost, ServerServicesHost } from "./host.js";
+/**
+ * Storage-state + cookies tools: dump_storage_state / inject_storage_state and the
+ * cookies CRUD family (cookies_get / cookies_list / cookies_set / cookies_delete /
+ * cookies_clear). Split out of `storage-tools` by cohesive family (RFC 0004 P3 /
+ * D3 SRP); registered through the shared `ToolHost` seam in the same source order.
+ */
+export declare function registerStorageStateCookiesTools(host: RegisterHost & GateHost & SessionHost & ConfigHost & EnvelopeHost & StorageHost & ActionHost & ServerServicesHost): void;

package/dist/tools/storage-state-cookies-tools.js

@@ -0,0 +1,223 @@
+import { withDeadline } from "../util/deadline.js";
+import { confirmByobAction } from "../policy/confirm.js";
+import { dumpStorageState, injectStorageState, readStorageStateFile, cookiesGet, cookiesDelete, cookiesClear, } from "../session/storage.js";
+import { SESSION_ARG } from "./schemas.js";
+/**
+ * Storage-state + cookies tools: dump_storage_state / inject_storage_state and the
+ * cookies CRUD family (cookies_get / cookies_list / cookies_set / cookies_delete /
+ * cookies_clear). Split out of `storage-tools` by cohesive family (RFC 0004 P3 /
+ * D3 SRP); registered through the shared `ToolHost` seam in the same source order.
+ */
+export function registerStorageStateCookiesTools(host) {
+    const { z, register, gateCheck, entryFor, okText, errText, confirmCtxFor, denyContent, storageFor, workspace, cfgActionTimeout, } = host;
+    // ---- layer 1 ----------------------------------------------------------------
+    register("dump_storage_state", {
+        capability: "read",
+        description: "Storage-state bulk dump — capture the session's current storage state (cookies + per-origin localStorage), the blob format Playwright's `BrowserContext.storageState()` returns. ALWAYS returns the blob; with `path`, also writes JSON to a workspace-rooted file (path-traversal rejected — must resolve under $BROWX_WORKSPACE). Use this to checkpoint an authed state for later replay via `inject_storage_state` / `auth_save`. Read-only. SECURITY NOTE: cookie *values* may carry credentials — treat the dump as sensitive (a future egress-masking pass lands separately).",
+        inputSchema: {
+            path: z
+                .string()
+                .optional()
+                .describe("Optional workspace-rooted JSON file to write the state to (in addition to returning it inline). Rejected if it escapes $BROWX_WORKSPACE."),
+            ...SESSION_ARG,
+        },
+    }, async ({ path, session }) => {
+        const g = gateCheck("dump_storage_state");
+        if (g)
+            return g;
+        try {
+            const e = await entryFor(session);
+            const r = await withDeadline(dumpStorageState(e.session.page().context(), workspace.root, { path }), cfgActionTimeout(), "dump_storage_state");
+            return okText({
+                ok: true,
+                cookies: r.state.cookies.length,
+                origins: r.state.origins.length,
+                ...(r.path ? { path: r.path, bytes: r.bytes } : {}),
+                state: r.state,
+            });
+        }
+        catch (err) {
+            return errText("dump_storage_state", err);
+        }
+    });
+    register("inject_storage_state", {
+        capability: "action",
+        description: "Storage-state bulk inject — apply a bulk storage state to the current session's context. `state` accepts either an inline blob OR a workspace-rooted JSON path (escape rejected). `mode:\"replace\"` (default) uses Playwright's `setStorageState` which CLEARS the context's existing cookies/localStorage/IndexedDB first — clean swap semantics. `mode:\"merge\"` adds cookies via `addCookies` without clearing AND best-effort merges localStorage for the currently-loaded origin only (other origins in the blob are skipped and returned in `originsSkipped` — localStorage is page-bound, not context-bound). For per-session seeding at CREATION, prefer `open_session({ storageState | authState })` — that's the Playwright-native primitive on incognito mode.",
+        inputSchema: {
+            state: z.union([
+                z.string().describe("Workspace-rooted JSON path to a state file (escape rejected)."),
+                z
+                    .object({ cookies: z.array(z.any()), origins: z.array(z.any()) })
+                    .passthrough()
+                    .describe("Inline state blob (the shape `dump_storage_state` returns)."),
+            ]),
+            mode: z
+                .enum(["replace", "merge"])
+                .optional()
+                .describe("`replace` (default) clears existing state then applies; `merge` adds without clearing (localStorage merge limited to current origin)."),
+            ...SESSION_ARG,
+        },
+    }, async ({ state, mode, session }) => {
+        const g = gateCheck("inject_storage_state");
+        if (g)
+            return g;
+        try {
+            const e = await entryFor(session);
+            const c = await confirmByobAction("inject_storage_state", confirmCtxFor(e));
+            if (!c.ok)
+                return denyContent("inject_storage_state", c);
+            const blob = typeof state === "string"
+                ? readStorageStateFile(workspace.root, state, "inject_storage_state")
+                : state;
+            const r = await withDeadline(injectStorageState(e.session.page().context(), e.session.page(), blob, { mode }), cfgActionTimeout(), "inject_storage_state");
+            return okText({ ok: true, ...r });
+        }
+        catch (err) {
+            return errText("inject_storage_state", err);
+        }
+    });
+    // ---- layer 2: cookies CRUD -------------------------------------------------
+    register("cookies_get", {
+        capability: "read",
+        description: "Read a single cookie by name. Optional `url` narrows the cookie jar (only cookies that would be sent on a request to that URL). Returns the full Playwright cookie object or `null`. Read-only.",
+        inputSchema: {
+            name: z.string().describe("Cookie name."),
+            url: z
+                .string()
+                .optional()
+                .describe("Optional URL — restricts to cookies that match this URL's domain/path/secure-context."),
+            ...SESSION_ARG,
+        },
+    }, async ({ name, url, session }) => {
+        const g = gateCheck("cookies_get");
+        if (g)
+            return g;
+        try {
+            const e = await entryFor(session);
+            const r = await withDeadline(cookiesGet(e.session.page().context(), { name, url }), cfgActionTimeout(), "cookies_get");
+            return okText({ ok: true, cookie: r });
+        }
+        catch (err) {
+            return errText("cookies_get", err);
+        }
+    });
+    register("cookies_list", {
+        capability: "read",
+        description: "List cookies in the session's jar. `urls` filters to cookies that would be sent on requests to those URLs (Playwright's native filter). Returns the full Playwright cookie array. Read-only.",
+        inputSchema: {
+            urls: z
+                .array(z.string())
+                .optional()
+                .describe("Optional URL list — restricts the result to cookies matching these URLs."),
+            ...SESSION_ARG,
+        },
+    }, async ({ urls, session }) => {
+        const g = gateCheck("cookies_list");
+        if (g)
+            return g;
+        try {
+            const e = await entryFor(session);
+            const r = await withDeadline(storageFor(e).cookiesList({ urls }), cfgActionTimeout(), "cookies_list");
+            return okText({ ok: true, count: r.length, cookies: r });
+        }
+        catch (err) {
+            return errText("cookies_list", err);
+        }
+    });
+    register("cookies_set", {
+        capability: "action",
+        description: 'Set a single cookie. Playwright\'s `addCookies` requires either `url` (recommended — derives domain/path/secure for you) OR both `domain` AND `path` explicitly; one of those two forms must be supplied or the call is rejected. Optional `expires` (Unix seconds), `httpOnly`, `secure`, `sameSite` (`"Strict"|"Lax"|"None"`). Idempotent w.r.t. (name, domain, path).',
+        inputSchema: {
+            name: z.string().describe("Cookie name."),
+            value: z.string().describe("Cookie value."),
+            url: z
+                .string()
+                .optional()
+                .describe("Recommended: source URL. Derives domain/path/secure. Mutually exclusive with explicit `domain`+`path`."),
+            domain: z.string().optional().describe("Explicit cookie domain. Requires `path` too."),
+            path: z
+                .string()
+                .optional()
+                .describe('Explicit cookie path (e.g. "/"). Requires `domain` too.'),
+            expires: z.number().optional().describe("Unix time in seconds. Omit for a session cookie."),
+            httpOnly: z.boolean().optional(),
+            secure: z.boolean().optional(),
+            sameSite: z.enum(["Strict", "Lax", "None"]).optional(),
+            ...SESSION_ARG,
+        },
+    }, async ({ name, value, url, domain, path, expires, httpOnly, secure, sameSite, session }) => {
+        const g = gateCheck("cookies_set");
+        if (g)
+            return g;
+        try {
+            const e = await entryFor(session);
+            const c = await confirmByobAction("cookies_set", confirmCtxFor(e));
+            if (!c.ok)
+                return denyContent("cookies_set", c);
+            const r = await withDeadline(storageFor(e).cookiesSet({
+                name,
+                value,
+                url,
+                domain,
+                path,
+                expires,
+                httpOnly,
+                secure,
+                sameSite,
+            }), cfgActionTimeout(), "cookies_set");
+            return okText({ ok: r.ok, name: r.name });
+        }
+        catch (err) {
+            return errText("cookies_set", err);
+        }
+    });
+    register("cookies_delete", {
+        capability: "action",
+        description: "Delete cookies by name, optionally narrowed by `url` (derives domain/path) or explicit `domain`/`path`. Returns `{ok:true}` even if no cookie matched (idempotent — distinguish presence via `cookies_get` first if needed).",
+        inputSchema: {
+            name: z.string().describe("Cookie name."),
+            url: z.string().optional().describe("Optional URL — narrows by derived domain/path."),
+            domain: z
+                .string()
+                .optional()
+                .describe("Explicit domain narrowing (overrides url-derived)."),
+            path: z.string().optional().describe("Explicit path narrowing (overrides url-derived)."),
+            ...SESSION_ARG,
+        },
+    }, async ({ name, url, domain, path, session }) => {
+        const g = gateCheck("cookies_delete");
+        if (g)
+            return g;
+        try {
+            const e = await entryFor(session);
+            const c = await confirmByobAction("cookies_delete", confirmCtxFor(e));
+            if (!c.ok)
+                return denyContent("cookies_delete", c);
+            const r = await withDeadline(cookiesDelete(e.session.page().context(), { name, url, domain, path }), cfgActionTimeout(), "cookies_delete");
+            return okText({ ok: r.ok, name });
+        }
+        catch (err) {
+            return errText("cookies_delete", err);
+        }
+    });
+    register("cookies_clear", {
+        capability: "action",
+        description: 'Wipe ALL cookies in the session\'s jar. Destructive across every domain in this context. localStorage and sessionStorage are untouched (use `*_clear` for those, or `inject_storage_state({state, mode:"replace"})` to reset everything via a bulk swap).',
+        inputSchema: { ...SESSION_ARG },
+    }, async ({ session }) => {
+        const g = gateCheck("cookies_clear");
+        if (g)
+            return g;
+        try {
+            const e = await entryFor(session);
+            const c = await confirmByobAction("cookies_clear", confirmCtxFor(e));
+            if (!c.ok)
+                return denyContent("cookies_clear", c);
+            const r = await withDeadline(cookiesClear(e.session.page().context()), cfgActionTimeout(), "cookies_clear");
+            return okText({ ok: r.ok });
+        }
+        catch (err) {
+            return errText("cookies_clear", err);
+        }
+    });
+}

package/dist/tools/storage-tools.d.ts

@@ -0,0 +1,17 @@
+import type { ToolHost } from "./host.js";
+/**
+ * Storage-state tools — the three-layer storage surface plus the file-backed
+ * artifact / HAR / video families. Layer 1 bulk dump/inject, layer 2 granular
+ * cookies + web-storage + Cache API + IndexedDB CRUD, layer 3 named auth-state
+ * slots, and the session artifact KV / HAR record / video record tools.
+ *
+ * RFC 0004 P3 / D3 (SRP): the registrations were split by cohesive family into
+ * four sibling modules (state+cookies / web-storage+auth / cache+idb /
+ * artifact+har+video). This module stays the single entry point `server.ts` +
+ * `tool-metadata.ts` call, and invokes each family in the EXACT prior source order
+ * so the registered-name set + the derived maps stay byte-identical (the
+ * web-storage `for` loop over localStorage/sessionStorage is kept verbatim inside
+ * its family module). The host owns the closures (gate, confirm, storage port,
+ * workspace); the family modules own the registrations.
+ */
+export declare function registerStorageTools(host: ToolHost): void;

package/dist/tools/storage-tools.js

@@ -0,0 +1,25 @@
+import { registerStorageStateCookiesTools } from "./storage-state-cookies-tools.js";
+import { registerStorageWebAuthTools } from "./storage-web-auth-tools.js";
+import { registerStorageCacheIdbTools } from "./storage-cache-idb-tools.js";
+import { registerStorageArtifactHarVideoTools } from "./storage-artifact-har-video-tools.js";
+/**
+ * Storage-state tools — the three-layer storage surface plus the file-backed
+ * artifact / HAR / video families. Layer 1 bulk dump/inject, layer 2 granular
+ * cookies + web-storage + Cache API + IndexedDB CRUD, layer 3 named auth-state
+ * slots, and the session artifact KV / HAR record / video record tools.
+ *
+ * RFC 0004 P3 / D3 (SRP): the registrations were split by cohesive family into
+ * four sibling modules (state+cookies / web-storage+auth / cache+idb /
+ * artifact+har+video). This module stays the single entry point `server.ts` +
+ * `tool-metadata.ts` call, and invokes each family in the EXACT prior source order
+ * so the registered-name set + the derived maps stay byte-identical (the
+ * web-storage `for` loop over localStorage/sessionStorage is kept verbatim inside
+ * its family module). The host owns the closures (gate, confirm, storage port,
+ * workspace); the family modules own the registrations.
+ */
+export function registerStorageTools(host) {
+    registerStorageStateCookiesTools(host);
+    registerStorageWebAuthTools(host);
+    registerStorageCacheIdbTools(host);
+    registerStorageArtifactHarVideoTools(host);
+}

package/dist/tools/storage-web-auth-tools.d.ts

@@ -0,0 +1,10 @@
+import type { RegisterHost, GateHost, SessionHost, ConfigHost, EnvelopeHost, StorageHost, ActionHost, ServerServicesHost } from "./host.js";
+/**
+ * Web-storage + named-auth-state tools: the localStorage / sessionStorage CRUD
+ * family (registered via a `for` loop over both kinds) plus auth_save / auth_load /
+ * auth_list / auth_delete. Split out of `storage-tools` by cohesive family (RFC
+ * 0004 P3 / D3 SRP); registered through the shared `ToolHost` seam in the same
+ * source order — the web-storage loop is kept verbatim so the 10 registered names
+ * land in the same order.
+ */
+export declare function registerStorageWebAuthTools(host: RegisterHost & GateHost & SessionHost & ConfigHost & EnvelopeHost & StorageHost & ActionHost & ServerServicesHost): void;