browxai 0.7.0

package/dist/session/idb-storage.d.ts

@@ -0,0 +1,86 @@
+import type { Page } from "playwright-core";
+/** Enumerate every database visible to the current origin. Uses
+ *  `indexedDB.databases()` — supported by Chromium-family browsers
+ *  (the target platform). On engines without it, returns an empty list
+ *  with a `supported:false` flag rather than throwing. */
+export declare function idbListDatabases(page: Page, tool: string): Promise<{
+    databases: Array<{
+        name: string;
+        version: number;
+    }>;
+    origin: string;
+    supported: boolean;
+}>;
+/** List the object-store names inside a database (read-only — does NOT
+ *  trigger an upgrade). */
+export declare function idbListStores(page: Page, args: {
+    dbName: string;
+}, tool: string): Promise<{
+    stores: string[];
+    dbName: string;
+    version: number;
+    origin: string;
+}>;
+/** Get the value at a key. Returns `{found:false}` if absent. Non-JSON
+ *  values surface as a structured error rather than a silent `undefined`. */
+type IdbGetResult = {
+    found: false;
+    dbName: string;
+    storeName: string;
+    key: unknown;
+    origin: string;
+} | {
+    found: true;
+    dbName: string;
+    storeName: string;
+    key: unknown;
+    value: unknown;
+    origin: string;
+};
+export declare function idbGet(page: Page, args: {
+    dbName: string;
+    storeName: string;
+    key: unknown;
+}, tool: string): Promise<IdbGetResult>;
+/** Put a value at a key. The object store must already exist — this
+ *  function does NOT create stores (store creation requires an upgrade
+ *  transaction, which adopters who own the schema should do themselves).
+ *
+ *  Values are JSON-cloned at the page boundary; non-serialisable inputs
+ *  reject at MCP-validation time (Zod tree). */
+export declare function idbPut(page: Page, args: {
+    dbName: string;
+    storeName: string;
+    key: unknown;
+    value: unknown;
+}, tool: string): Promise<{
+    ok: true;
+    dbName: string;
+    storeName: string;
+    key: unknown;
+    origin: string;
+}>;
+/** Delete the value at a key. Idempotent — returns the same shape
+ *  whether or not a record existed. */
+export declare function idbDelete(page: Page, args: {
+    dbName: string;
+    storeName: string;
+    key: unknown;
+}, tool: string): Promise<{
+    ok: true;
+    dbName: string;
+    storeName: string;
+    key: unknown;
+    origin: string;
+}>;
+/** Clear every record from an object store (the store itself remains). */
+export declare function idbClear(page: Page, args: {
+    dbName: string;
+    storeName: string;
+}, tool: string): Promise<{
+    ok: true;
+    dbName: string;
+    storeName: string;
+    origin: string;
+}>;
+export {};

package/dist/session/idb-storage.js

@@ -0,0 +1,229 @@
+// IndexedDB CRUD —  storage-state surface extension.
+//
+// Sibling of cookies / localStorage / sessionStorage / Cache API CRUD.
+// Drives the W3C IndexedDB API via `page.evaluate` — the same posture as
+// the web-storage helpers (origin-scoped; the session MUST be navigated
+// to the target origin first; about:blank rejected).
+//
+// What's actually stored: each IDB database has named object stores, each
+// holding records keyed by a primary key. The CRUD surface here treats
+// values as JSON-serialisable — IDB itself can store structured-clonable
+// values (Blob/ArrayBuffer/Date/Map/Set), but we go through `JSON.stringify`
+// at the page boundary because the MCP transport is JSON-only. Non-JSON
+// values (cyclic refs / functions / DOM nodes) are reported as a structured
+// error rather than silently dropped — see `idbGet` /  `idbPut` below.
+//
+// Keys go through JSON too — IDB accepts strings, numbers, dates, and
+// arrays as keys. Strings + numbers + array-of-strings/numbers all
+// round-trip cleanly through JSON; Date keys are stringified to ISO and
+// re-parsed on the way back in. Documented in the tool descriptions.
+//
+// Capability split (server.ts):
+//   - reads  (`idb_list_databases`, `idb_list_stores`, `idb_get`) → `read`
+//   - writes (`idb_put`, `idb_delete`, `idb_clear`)               → `action`
+//
+// Tracker-ID hygiene: zero. Each entry is identified by its
+// `(dbName, storeName, key)` triple — the platform's native key.
+const IDB_API = "indexedDB";
+function idbOriginGuard(page, tool) {
+    let url;
+    try {
+        url = page.url();
+    }
+    catch {
+        url = "";
+    }
+    if (!url || url === "about:blank") {
+        throw new Error(`${tool}: IndexedDB is origin-scoped and the page is at "${url || "(unknown)"}". ` +
+            `Navigate the session to the target origin first.`);
+    }
+}
+// --- reads -----------------------------------------------------------------
+/** Enumerate every database visible to the current origin. Uses
+ *  `indexedDB.databases()` — supported by Chromium-family browsers
+ *  (the target platform). On engines without it, returns an empty list
+ *  with a `supported:false` flag rather than throwing. */
+export async function idbListDatabases(page, tool) {
+    idbOriginGuard(page, tool);
+    const expr = `(async () => { ` +
+        `if (typeof ${IDB_API} === "undefined" || typeof ${IDB_API}.databases !== "function") ` +
+        `  return { databases: [], origin: location.origin, supported: false }; ` +
+        `var dbs = await ${IDB_API}.databases(); ` +
+        `return { databases: dbs.map(function (d) { return { name: d.name || "", version: d.version || 0 }; }), ` +
+        `         origin: location.origin, supported: true }; })()`;
+    return await page.evaluate(expr);
+}
+/** List the object-store names inside a database (read-only — does NOT
+ *  trigger an upgrade). */
+export async function idbListStores(page, args, tool) {
+    if (!args.dbName)
+        throw new Error(`${tool}: \`dbName\` is required`);
+    idbOriginGuard(page, tool);
+    const expr = `(async () => { ` +
+        `var db = await new Promise(function (resolve, reject) { ` +
+        `  var req = ${IDB_API}.open(${JSON.stringify(args.dbName)}); ` +
+        `  req.onsuccess = function () { resolve(req.result); }; ` +
+        `  req.onerror = function () { reject(req.error); }; ` +
+        `  req.onblocked = function () { reject(new Error("idb_list_stores: open blocked — close other connections to \\"" + ${JSON.stringify(args.dbName)} + "\\" first")); }; ` +
+        `}); ` +
+        `var names = Array.prototype.slice.call(db.objectStoreNames); ` +
+        `var version = db.version; ` +
+        `db.close(); ` +
+        `return { stores: names, dbName: ${JSON.stringify(args.dbName)}, version: version, origin: location.origin }; })()`;
+    return await page.evaluate(expr);
+}
+export async function idbGet(page, args, tool) {
+    if (!args.dbName)
+        throw new Error(`${tool}: \`dbName\` is required`);
+    if (!args.storeName)
+        throw new Error(`${tool}: \`storeName\` is required`);
+    if (args.key === undefined || args.key === null)
+        throw new Error(`${tool}: \`key\` is required`);
+    idbOriginGuard(page, tool);
+    const expr = `(async () => { ` +
+        `var key = ${JSON.stringify(args.key)}; ` +
+        `var db = await new Promise(function (resolve, reject) { ` +
+        `  var req = ${IDB_API}.open(${JSON.stringify(args.dbName)}); ` +
+        `  req.onsuccess = function () { resolve(req.result); }; ` +
+        `  req.onerror = function () { reject(req.error); }; ` +
+        `  req.onblocked = function () { reject(new Error("${tool}: open blocked")); }; ` +
+        `}); ` +
+        `if (!db.objectStoreNames.contains(${JSON.stringify(args.storeName)})) { ` +
+        `  db.close(); ` +
+        `  throw new Error("${tool}: object store \\"" + ${JSON.stringify(args.storeName)} + "\\" does not exist in db \\"" + ${JSON.stringify(args.dbName)} + "\\""); ` +
+        `} ` +
+        `var tx = db.transaction(${JSON.stringify(args.storeName)}, "readonly"); ` +
+        `var store = tx.objectStore(${JSON.stringify(args.storeName)}); ` +
+        `var value = await new Promise(function (resolve, reject) { ` +
+        `  var req = store.get(key); ` +
+        `  req.onsuccess = function () { resolve(req.result); }; ` +
+        `  req.onerror = function () { reject(req.error); }; ` +
+        `}); ` +
+        `db.close(); ` +
+        `if (value === undefined) return { found: false, dbName: ${JSON.stringify(args.dbName)}, storeName: ${JSON.stringify(args.storeName)}, key: key, origin: location.origin }; ` +
+        `var jsonable; ` +
+        `try { jsonable = JSON.parse(JSON.stringify(value)); } catch (e) { ` +
+        `  throw new Error("${tool}: value at (\\"" + ${JSON.stringify(args.dbName)} + "\\", \\"" + ${JSON.stringify(args.storeName)} + "\\") is not JSON-serialisable (" + (e && e.message || e) + ") — agentic browser surface returns JSON over MCP; the platform value is preserved IN the IDB store but cannot be returned over this transport"); ` +
+        `} ` +
+        `return { found: true, dbName: ${JSON.stringify(args.dbName)}, storeName: ${JSON.stringify(args.storeName)}, key: key, value: jsonable, origin: location.origin }; })()`;
+    return await page.evaluate(expr);
+}
+/** Put a value at a key. The object store must already exist — this
+ *  function does NOT create stores (store creation requires an upgrade
+ *  transaction, which adopters who own the schema should do themselves).
+ *
+ *  Values are JSON-cloned at the page boundary; non-serialisable inputs
+ *  reject at MCP-validation time (Zod tree). */
+export async function idbPut(page, args, tool) {
+    if (!args.dbName)
+        throw new Error(`${tool}: \`dbName\` is required`);
+    if (!args.storeName)
+        throw new Error(`${tool}: \`storeName\` is required`);
+    if (args.key === undefined || args.key === null)
+        throw new Error(`${tool}: \`key\` is required`);
+    if (args.value === undefined)
+        throw new Error(`${tool}: \`value\` is required`);
+    idbOriginGuard(page, tool);
+    const expr = `(async () => { ` +
+        `var key = ${JSON.stringify(args.key)}; ` +
+        `var value = ${JSON.stringify(args.value)}; ` +
+        `var db = await new Promise(function (resolve, reject) { ` +
+        `  var req = ${IDB_API}.open(${JSON.stringify(args.dbName)}); ` +
+        `  req.onsuccess = function () { resolve(req.result); }; ` +
+        `  req.onerror = function () { reject(req.error); }; ` +
+        `  req.onblocked = function () { reject(new Error("${tool}: open blocked")); }; ` +
+        `}); ` +
+        `if (!db.objectStoreNames.contains(${JSON.stringify(args.storeName)})) { ` +
+        `  db.close(); ` +
+        `  throw new Error("${tool}: object store \\"" + ${JSON.stringify(args.storeName)} + "\\" does not exist in db \\"" + ${JSON.stringify(args.dbName)} + "\\" — store creation requires an upgrade transaction; create the store from app code first"); ` +
+        `} ` +
+        `var tx = db.transaction(${JSON.stringify(args.storeName)}, "readwrite"); ` +
+        `var store = tx.objectStore(${JSON.stringify(args.storeName)}); ` +
+        `await new Promise(function (resolve, reject) { ` +
+        `  var req; ` +
+        `  if (store.keyPath !== null) { req = store.put(value); } ` +
+        `  else { req = store.put(value, key); } ` +
+        `  req.onsuccess = function () { resolve(undefined); }; ` +
+        `  req.onerror = function () { reject(req.error); }; ` +
+        `}); ` +
+        `await new Promise(function (resolve, reject) { ` +
+        `  tx.oncomplete = function () { resolve(undefined); }; ` +
+        `  tx.onerror = function () { reject(tx.error); }; ` +
+        `  tx.onabort = function () { reject(tx.error || new Error("${tool}: transaction aborted")); }; ` +
+        `}); ` +
+        `db.close(); ` +
+        `return { ok: true, dbName: ${JSON.stringify(args.dbName)}, storeName: ${JSON.stringify(args.storeName)}, key: key, origin: location.origin }; })()`;
+    return await page.evaluate(expr);
+}
+/** Delete the value at a key. Idempotent — returns the same shape
+ *  whether or not a record existed. */
+export async function idbDelete(page, args, tool) {
+    if (!args.dbName)
+        throw new Error(`${tool}: \`dbName\` is required`);
+    if (!args.storeName)
+        throw new Error(`${tool}: \`storeName\` is required`);
+    if (args.key === undefined || args.key === null)
+        throw new Error(`${tool}: \`key\` is required`);
+    idbOriginGuard(page, tool);
+    const expr = `(async () => { ` +
+        `var key = ${JSON.stringify(args.key)}; ` +
+        `var db = await new Promise(function (resolve, reject) { ` +
+        `  var req = ${IDB_API}.open(${JSON.stringify(args.dbName)}); ` +
+        `  req.onsuccess = function () { resolve(req.result); }; ` +
+        `  req.onerror = function () { reject(req.error); }; ` +
+        `  req.onblocked = function () { reject(new Error("${tool}: open blocked")); }; ` +
+        `}); ` +
+        `if (!db.objectStoreNames.contains(${JSON.stringify(args.storeName)})) { ` +
+        `  db.close(); ` +
+        `  throw new Error("${tool}: object store \\"" + ${JSON.stringify(args.storeName)} + "\\" does not exist in db \\"" + ${JSON.stringify(args.dbName)} + "\\""); ` +
+        `} ` +
+        `var tx = db.transaction(${JSON.stringify(args.storeName)}, "readwrite"); ` +
+        `var store = tx.objectStore(${JSON.stringify(args.storeName)}); ` +
+        `await new Promise(function (resolve, reject) { ` +
+        `  var req = store.delete(key); ` +
+        `  req.onsuccess = function () { resolve(undefined); }; ` +
+        `  req.onerror = function () { reject(req.error); }; ` +
+        `}); ` +
+        `await new Promise(function (resolve, reject) { ` +
+        `  tx.oncomplete = function () { resolve(undefined); }; ` +
+        `  tx.onerror = function () { reject(tx.error); }; ` +
+        `  tx.onabort = function () { reject(tx.error || new Error("${tool}: transaction aborted")); }; ` +
+        `}); ` +
+        `db.close(); ` +
+        `return { ok: true, dbName: ${JSON.stringify(args.dbName)}, storeName: ${JSON.stringify(args.storeName)}, key: key, origin: location.origin }; })()`;
+    return await page.evaluate(expr);
+}
+/** Clear every record from an object store (the store itself remains). */
+export async function idbClear(page, args, tool) {
+    if (!args.dbName)
+        throw new Error(`${tool}: \`dbName\` is required`);
+    if (!args.storeName)
+        throw new Error(`${tool}: \`storeName\` is required`);
+    idbOriginGuard(page, tool);
+    const expr = `(async () => { ` +
+        `var db = await new Promise(function (resolve, reject) { ` +
+        `  var req = ${IDB_API}.open(${JSON.stringify(args.dbName)}); ` +
+        `  req.onsuccess = function () { resolve(req.result); }; ` +
+        `  req.onerror = function () { reject(req.error); }; ` +
+        `  req.onblocked = function () { reject(new Error("${tool}: open blocked")); }; ` +
+        `}); ` +
+        `if (!db.objectStoreNames.contains(${JSON.stringify(args.storeName)})) { ` +
+        `  db.close(); ` +
+        `  throw new Error("${tool}: object store \\"" + ${JSON.stringify(args.storeName)} + "\\" does not exist in db \\"" + ${JSON.stringify(args.dbName)} + "\\""); ` +
+        `} ` +
+        `var tx = db.transaction(${JSON.stringify(args.storeName)}, "readwrite"); ` +
+        `var store = tx.objectStore(${JSON.stringify(args.storeName)}); ` +
+        `await new Promise(function (resolve, reject) { ` +
+        `  var req = store.clear(); ` +
+        `  req.onsuccess = function () { resolve(undefined); }; ` +
+        `  req.onerror = function () { reject(req.error); }; ` +
+        `}); ` +
+        `await new Promise(function (resolve, reject) { ` +
+        `  tx.oncomplete = function () { resolve(undefined); }; ` +
+        `  tx.onerror = function () { reject(tx.error); }; ` +
+        `  tx.onabort = function () { reject(tx.error || new Error("${tool}: transaction aborted")); }; ` +
+        `}); ` +
+        `db.close(); ` +
+        `return { ok: true, dbName: ${JSON.stringify(args.dbName)}, storeName: ${JSON.stringify(args.storeName)}, origin: location.origin }; })()`;
+    return await page.evaluate(expr);
+}

package/dist/session/incognito.d.ts

@@ -0,0 +1,3 @@
+import "../engine/register-engines.js";
+import type { BrowserSession, SessionOptions } from "./types.js";
+export declare function openIncognitoSession(opts?: SessionOptions): Promise<BrowserSession>;

package/dist/session/incognito.js

@@ -0,0 +1,20 @@
+// Incognito launch. A fresh browser process + an *ephemeral* BrowserContext: no
+// profile dir, nothing persisted to disk, everything (cookies, storage, cache)
+// discarded on close. Same safe-by-default flags as managed (no
+// `--disable-web-security`, sandbox on). Use for one-off agentic driving where you
+// explicitly do NOT want a profile trace.
+//
+// The no-trace consumer-repo contract is unaffected — there was never any
+// consumer-cwd write; incognito additionally leaves no Chrome profile behind.
+//
+// Post-RFC-0004-P1 this factory keeps only its MODE concern: it resolves the
+// engine and hands off to the EngineRegistry, whose `makeAdapter` owns the
+// per-engine ephemeral-launch body (the `engine === "…"` chain that used to live
+// here is now data-driven, one registration per engine). The per-engine launch +
+// session construction is byte-identical — only relocated into the engine modules.
+import { engineEntry } from "../engine/registry.js";
+import "../engine/register-engines.js";
+export async function openIncognitoSession(opts = {}) {
+    const engine = opts.browserType ?? "chromium";
+    return engineEntry(engine).makeAdapter({ ...opts, launchMode: "incognito" });
+}

package/dist/session/launch-options.d.ts

@@ -0,0 +1,41 @@
+import type { Browser, BrowserContext, BrowserContextOptions, CDPSession, Page } from "playwright-core";
+import type { EngineKind } from "../engine/index.js";
+import type { BrowserSession, SessionOptions } from "./types.js";
+/** Resolve the managed-launch profile dir + the shared context options, building
+ *  the `--disable-web-security` + extension launch args exactly as the managed
+ *  factory did. The chromium-only `args` splice (insecure + extension flags) is
+ *  returned separately so the chromium engine can fold it into its
+ *  launchPersistent options without firefox/webkit ever seeing Chromium `--` flags. */
+export declare function buildManagedLaunch(engine: EngineKind, opts: SessionOptions): {
+    profileDir: string;
+    options: BrowserContextOptions & {
+        headless: boolean;
+        acceptDownloads: boolean;
+    };
+    chromiumArgs: string[];
+};
+/** Apply a managed session's post-launch storageState seeding (the persistent-mode
+ *  clear-then-seed path) and build the `BrowserSession` object — verbatim from the
+ *  managed factory's tail. */
+export declare function finalizeManagedSession(engine: EngineKind, opts: SessionOptions, profileDir: string, handles: {
+    context: BrowserContext;
+    page: Page;
+    cdp?: CDPSession;
+}): Promise<BrowserSession>;
+/** Build the incognito ephemeral launch options — the `--disable-web-security`
+ *  splice, exactly as the incognito factory did (chromium-only). */
+export declare function buildIncognitoLaunchOptions(engine: EngineKind, opts: SessionOptions): {
+    headless: boolean;
+    args?: string[];
+};
+/** Build the incognito ephemeral context options — verbatim from the incognito
+ *  factory (device, downloads, storageState, recordHar, recordVideo). */
+export declare function buildIncognitoContextOptions(opts: SessionOptions): BrowserContextOptions;
+/** Build the incognito `BrowserSession` object — verbatim from the incognito
+ *  factory's tail (note the `mode: "managed"` coarse axis + the browser close). */
+export declare function finalizeIncognitoSession(engine: EngineKind, handles: {
+    browser?: Browser;
+    context: BrowserContext;
+    page: Page;
+    cdp?: CDPSession;
+}): BrowserSession;

package/dist/session/launch-options.js

@@ -0,0 +1,200 @@
+// Shared launch-option building + session finalization for the Playwright-backed
+// engines (chromium / firefox / webkit). Extracted VERBATIM from the per-engine
+// branches of managed.ts / incognito.ts so the per-engine `EngineEntry.makeAdapter`
+// (in adapters/<engine>.engine.ts) builds the exact same options + session object
+// the old `if (engine === "…")` chains did — byte-identical, only relocated.
+//
+// The engine-specific divergences that DON'T collapse (firefox channel resolution,
+// the chromium-only `args` splice, the disable-web-security warning text) stay in
+// the engine modules; what lives here is the shared shape every Playwright engine
+// builds identically.
+import { log } from "../util/logging.js";
+import { resolveWorkspace } from "../util/workspace.js";
+/** Resolve the managed-launch profile dir + the shared context options, building
+ *  the `--disable-web-security` + extension launch args exactly as the managed
+ *  factory did. The chromium-only `args` splice (insecure + extension flags) is
+ *  returned separately so the chromium engine can fold it into its
+ *  launchPersistent options without firefox/webkit ever seeing Chromium `--` flags. */
+export function buildManagedLaunch(engine, opts) {
+    const workspace = resolveWorkspace();
+    const profileDir = opts.profileDir ?? workspace.sub("profile");
+    // opt-in web-security-off. Off by default (safe-by-default is the
+    //  non-negotiable); when the gated `disableWebSecurity` config flag
+    // is set, lower it here with a loud per-launch warning. The `--disable-*`
+    // flag form is Chromium-only — on Firefox SOP-off would ride
+    // `firefoxUserPrefs` instead, which the Juggler lane doesn't wire today, so
+    // we surface that rather than silently ignore the flag.
+    const insecureArgs = [];
+    if (opts.disableWebSecurity) {
+        if (engine !== "chromium") {
+            log.warn(`⚠  session.managed: disableWebSecurity is not wired on the ${engine} engine — ` +
+                "the --disable-web-security flag form is Chromium-only. Launching with SOP/CORS ON. " +
+                "Use a chromium session if you need web-security-off.");
+        }
+        else {
+            insecureArgs.push("--disable-web-security", "--disable-site-isolation-trials");
+            log.warn("⚠  session.managed: disableWebSecurity is ON — launching with --disable-web-security. " +
+                "SOP/CORS is OFF for the whole browser session. Use only against test/dev targets.");
+        }
+    }
+    // Optional Chromium extension launch flags. Empty/unset → no flags.
+    // Extensions are a LAUNCH-time concern in Chromium; the `extensions`-capability
+    // tools mutate this list and rebuild the context. Headed-only (the tool layer
+    // refuses on `headless:true` sessions, so by the time we reach this point the
+    // launch is already headed) and persistent-only (`incognito` / `attached` are
+    // refused upstream). The extension tools are engine-gated (Firefox has no
+    // Playwright extension API), so this list is empty on the firefox path.
+    const extensionArgs = [];
+    if (opts.extensionPaths && opts.extensionPaths.length > 0) {
+        const joined = opts.extensionPaths.join(",");
+        extensionArgs.push(`--disable-extensions-except=${joined}`, `--load-extension=${joined}`);
+        log.info("session.managed: loading extensions", {
+            count: opts.extensionPaths.length,
+            paths: opts.extensionPaths,
+        });
+    }
+    const chromiumArgs = [...insecureArgs, ...extensionArgs];
+    log.info("session.managed: launching", { profileDir, headless: !!opts.headless, engine });
+    // Launch options common to both engines. Chromium-only `args` are spliced in
+    // for the chromium path only (Firefox rejects Chromium `--` flags).
+    const options = {
+        headless: !!opts.headless,
+        // device/viewport emulation applied at context creation.
+        ...(opts.device ?? {}),
+        // Accept downloads at the context level — the per-session
+        // `DownloadsRegistry` (off-by-default) intercepts them via the
+        // `context.on("download")` event. Without `acceptDownloads:true`
+        // Playwright never emits that event, so the off-by-default registry
+        // can never opt in either.
+        acceptDownloads: true,
+        // HAR recording at context creation (native Playwright primitive).
+        // Finalized on context.close(). No-op when unset.
+        ...(opts.recordHar ? { recordHar: opts.recordHar } : {}),
+        // Video recording at context creation (native Playwright primitive).
+        // Finalized on context.close(). The dir is workspace-rooted by
+        // construction; the registry's teardown calls
+        // `page.video().saveAs(targetPath)` for a deterministic filename.
+        ...(opts.recordVideo ? { recordVideo: opts.recordVideo } : {}),
+    };
+    return { profileDir, options, chromiumArgs };
+}
+/** Apply a managed session's post-launch storageState seeding (the persistent-mode
+ *  clear-then-seed path) and build the `BrowserSession` object — verbatim from the
+ *  managed factory's tail. */
+export async function finalizeManagedSession(engine, opts, profileDir, handles) {
+    const { context, page } = handles;
+    const cdpHandle = handles.cdp;
+    // Persistent contexts don't take `storageState` at creation (their state
+    // lives on disk). When a caller asks for it on a managed session we apply
+    // it post-create via `setStorageState` — which CLEARS the profile's
+    // existing cookies/localStorage/IndexedDB first. Loud-warn so the override
+    // is visible.
+    if (opts.storageState) {
+        log.warn("session.managed: applying storageState to a persistent profile — " +
+            "this CLEARS existing cookies/localStorage/IndexedDB on the profile " +
+            `at "${profileDir}" before seeding. Use incognito mode for a fresh ` +
+            "context without touching a persistent profile.");
+        await context.setStorageState(opts.storageState);
+    }
+    let closed = false;
+    return {
+        mode: "managed",
+        ownsBrowser: true,
+        engine,
+        page: () => page,
+        // chromium mints a CDP session; firefox has none (`cdp` stays optional and
+        // absent — consumers route through `requireCdp`, which refuses cleanly).
+        ...(cdpHandle ? { cdp: () => cdpHandle } : {}),
+        close: async () => {
+            if (closed)
+                return;
+            closed = true;
+            log.info("session.managed: closing");
+            if (cdpHandle)
+                await cdpHandle.detach().catch(() => undefined);
+            await context.close().catch(() => undefined);
+        },
+    };
+}
+/** Build the incognito ephemeral launch options — the `--disable-web-security`
+ *  splice, exactly as the incognito factory did (chromium-only). */
+export function buildIncognitoLaunchOptions(engine, opts) {
+    log.info("session.incognito: launching ephemeral browser", {
+        headless: !!opts.headless,
+        engine,
+    });
+    // opt-in web-security-off (off by default; loud per-launch warning). The
+    // --disable-* flag form is Chromium-only; on the firefox engine we warn
+    // rather than silently apply a flag Firefox doesn't accept.
+    const insecureArgs = [];
+    if (opts.disableWebSecurity) {
+        if (engine !== "chromium") {
+            log.warn(`⚠  session.incognito: disableWebSecurity is not wired on the ${engine} engine — ` +
+                "the --disable-web-security flag form is Chromium-only. Launching with SOP/CORS ON.");
+        }
+        else {
+            insecureArgs.push("--disable-web-security", "--disable-site-isolation-trials");
+            log.warn("⚠  session.incognito: disableWebSecurity is ON — launching with --disable-web-security. " +
+                "SOP/CORS is OFF for the whole browser session. Use only against test/dev targets.");
+        }
+    }
+    return {
+        headless: !!opts.headless,
+        // No lowered-security flags unless the gated flag is explicitly on. The
+        // firefox/webkit ephemeral launches never carry Chromium `--` args (their
+        // adapters take only `{ headless }`), so the splice is chromium-only by
+        // construction — the engine module passes only what its adapter accepts.
+        ...(insecureArgs.length ? { args: insecureArgs } : {}),
+    };
+}
+/** Build the incognito ephemeral context options — verbatim from the incognito
+ *  factory (device, downloads, storageState, recordHar, recordVideo). */
+export function buildIncognitoContextOptions(opts) {
+    return {
+        ...(opts.device ?? {}),
+        // Accept downloads at the context level so the per-session
+        // `DownloadsRegistry` (off-by-default) can intercept them on demand.
+        // The registry discards artefacts when capture is off — `acceptDownloads`
+        // being true is purely the prerequisite for Playwright to emit the
+        // `download` event that the registry's listener hangs off.
+        acceptDownloads: true,
+        // Seed the ephemeral context with a storage state if one was supplied
+        // (the Playwright-native primitive for "open a fresh browser already
+        // logged in as X"). No-op when unset.
+        ...(opts.storageState ? { storageState: opts.storageState } : {}),
+        // HAR recording at context creation (native Playwright primitive).
+        // Finalized on context.close(). No-op when unset.
+        ...(opts.recordHar ? { recordHar: opts.recordHar } : {}),
+        // Video recording at context creation (native Playwright primitive).
+        // Finalized on context.close(). The dir is workspace-rooted by
+        // construction; the registry's teardown calls
+        // `page.video().saveAs(targetPath)` for a deterministic filename.
+        ...(opts.recordVideo ? { recordVideo: opts.recordVideo } : {}),
+    };
+}
+/** Build the incognito `BrowserSession` object — verbatim from the incognito
+ *  factory's tail (note the `mode: "managed"` coarse axis + the browser close). */
+export function finalizeIncognitoSession(engine, handles) {
+    const { browser, context, page } = handles;
+    const cdpHandle = handles.cdp;
+    let closed = false;
+    return {
+        mode: "managed", // BrowserSession.mode is the coarse owned/not-owned axis;
+        // the fine-grained "incognito" label lives on SessionEntry.mode. We own it.
+        ownsBrowser: true,
+        engine,
+        page: () => page,
+        // chromium mints a CDP session; firefox has none (`cdp` stays absent).
+        ...(cdpHandle ? { cdp: () => cdpHandle } : {}),
+        close: async () => {
+            if (closed)
+                return;
+            closed = true;
+            log.info("session.incognito: closing (ephemeral context + browser discarded)");
+            if (cdpHandle)
+                await cdpHandle.detach().catch(() => undefined);
+            await context.close().catch(() => undefined);
+            await browser?.close().catch(() => undefined);
+        },
+    };
+}

package/dist/session/managed.d.ts

@@ -0,0 +1,3 @@
+import "../engine/register-engines.js";
+import type { BrowserSession, SessionOptions } from "./types.js";
+export declare function openManagedSession(opts?: SessionOptions): Promise<BrowserSession>;

package/dist/session/managed.js

@@ -0,0 +1,16 @@
+// Managed-profile launch. Normal Chrome flags, sandbox on, profile dir rooted at
+// $BROWX_WORKSPACE/profile/. Never `cwd`, never the human's daily-driver profile,
+// never lowered-security flags.
+//
+// Post-RFC-0004-P1 this factory keeps only its MODE concern: it resolves the
+// engine and hands off to the EngineRegistry, whose `makeAdapter` owns the
+// per-engine managed-launch body (the `engine === "…"` chain that used to live
+// here is now data-driven, one registration per engine). The per-engine launch
+// + session construction is byte-identical — only relocated into the engine
+// modules (see src/engine/adapters/*.engine.ts + src/session/launch-options.ts).
+import { engineEntry } from "../engine/registry.js";
+import "../engine/register-engines.js";
+export async function openManagedSession(opts = {}) {
+    const engine = opts.browserType ?? "chromium";
+    return engineEntry(engine).makeAdapter({ ...opts, launchMode: "managed" });
+}

package/dist/session/metrics.d.ts

@@ -0,0 +1,45 @@
+/** Per-tool counter row. */
+export interface ToolCounter {
+    /** Total dispatches against this tool name in this session. */
+    count: number;
+    /** Sum of wall-clock dispatch latency in milliseconds. */
+    durationMs: number;
+    /** Dispatches whose first JSON result was shaped `{ok: false, ...}` and was
+     *  NOT a capability denial. Capability denials are tracked separately on the
+     *  session-wide `capabilityDenials` scalar (one source of truth). */
+    errors: number;
+}
+/** Outcome classifier passed from the dispatch wrapper. */
+export type DispatchOutcome = "ok" | "error" | "denied";
+export declare class SessionMetrics {
+    /** Wall-clock instant the session was created. Mirrored on the rolled-up
+     *  result so the consumer can derive duration without a second tool call. */
+    readonly startedAt: number;
+    /** Per-tool counters. Lazily created on first dispatch of each tool. */
+    private byTool;
+    /** Sum of `tokensEstimate` across every dispatched call. The field is on the
+     *  result envelope (set by every tool that wraps a body via the standard
+     *  helper); we read it back here so a session-wide token budget is one
+     *  lookup rather than re-walking each tool's transcript. */
+    private tokensSum;
+    /** Count of capability-denied dispatches across the whole session — the
+     *  config-shape signal, see module header. */
+    private denials;
+    constructor(startedAt?: number);
+    /** Record one dispatch. `durationMs` is the wall-clock latency the wrapper
+     *  measured; `tokensEstimate` is the `tokensEstimate` field from the result
+     *  envelope (or `undefined` if the result didn't carry one — e.g. an image-
+     *  only response). Outcome `denied` means the gate refused before dispatch. */
+    record(tool: string, outcome: DispatchOutcome, durationMs: number, tokensEstimate?: number): void;
+    /** Snapshot the current rollup. The returned object is plain JSON — safe to
+     *  serialise straight onto the `session_metrics` tool envelope. */
+    snapshot(now?: number): {
+        callsByTool: Record<string, number>;
+        durationMsByTool: Record<string, number>;
+        errorsByTool: Record<string, number>;
+        tokensEstimateSum: number;
+        capabilityDenials: number;
+        sessionStartedAt: string;
+        sessionDurationMs: number;
+    };
+}