browxai 0.7.0

package/dist/session/playwright-post-wire.js

@@ -0,0 +1,148 @@
+// The Playwright post-creation wiring (RFC 0004 D1 + D5). The four Playwright
+// engines (chromium / firefox / webkit / android) register `playwrightPostWire`
+// as their `EngineEntry.postWire`; safari registers its own minimal BiDi-console
+// post-wire (safari.engine.ts). This is where the 17 scattered
+// `sess.engine !== "safari"` guards in session-registry.ts collapse into ONE call
+// — the engine that needs the Playwright bookkeeping owns it, the engine that
+// does not (safari, and the synthetic in-memory engine) simply omits it.
+//
+// Every attach below is byte-identical to its pre-relocation form and runs in the
+// EXACT same source order (console → bridge → dialog → permission → notification →
+// fs-picker → downloads → overlay → stealth → device-emulation → ws-interactive →
+// workers). The post-creation attaches are side-effects on the Playwright context;
+// running them once the SessionEntry is assembled (rather than inline during
+// construction) is observably identical because no navigation — and thus no
+// console/network/dialog event — fires during session creation.
+//
+// Host deps (caps / configStore / workspace) are threaded in per server: the
+// composition root (`buildSessionRegistry`) owns them and passes its OWN set as the
+// `deps` argument to `playwrightPostWire(entry, deps)`. They are NOT a module-global
+// — a module-global would let a second `createServer()` in the same process (the
+// in-process SDK transport composes one server per transport) overwrite the first
+// server's caps gate / workspace sandbox-root, so server A could start installing
+// server B's action-gated wrappers + stealth scripts on A's OWN sessions. Threading
+// explicitly keeps each server's post-wire bound to its own boundary. The
+// per-session policy states + bridge are read off the SessionEntry.
+import { log } from "../util/logging.js";
+import { attachDialogPolicy } from "./dialog.js";
+import { attachPermissionPolicy, applyCdpBaseline as applyPermissionCdpBaseline, } from "./permission.js";
+import { attachNotificationPolicy } from "./notification.js";
+import { attachFsPickerPolicy } from "./fs-picker.js";
+import { attachDeviceEmulation } from "./device-emu.js";
+import { reapplyAll as reapplyEmulation } from "./emulation.js";
+import { attachDownloadCapture } from "../page/downloads.js";
+import { applyOverlayHide } from "../helper/overlay-hide.js";
+import { applyStealth } from "../helper/stealth.js";
+/** Attach the full Playwright post-creation bookkeeping to a freshly-built
+ *  SessionEntry, using the per-server `deps` (caps / configStore / workspace) the
+ *  composition root threads in. Returns the promise the session factory awaits, so
+ *  every context attach completes before the session is handed to a tool call —
+ *  byte-identical to the pre-relocation inline awaits. */
+export async function playwrightPostWire(entry, deps) {
+    const { caps, configStore, workspace } = deps;
+    const sess = entry.session;
+    const ctx = sess.page().context();
+    const br = entry.bridge;
+    // console — attach to the current + future pages. (Safari's console arrives
+    // over BiDi in its own post-wire; every Playwright engine attaches here.)
+    entry.console.attach(sess.page());
+    // browser bridge — the page-side __browx signalling channel.
+    await br.attach(ctx);
+    // dialog policy — install per-page on current + future pages.
+    attachDialogPolicy(ctx, entry.dialog);
+    // permission policy — install per-context binding + init-script wrappers, plus
+    // the CDP baseline (Browser.setPermission per supported name). The ask-human
+    // handler routes through the bridge — `__browx.confirm(true|false)` from
+    // page-side DevTools releases the wait. Best-effort: attach failures still leave
+    // the CDP baseline below in place.
+    await attachPermissionPolicy(ctx, entry.permission, async (permission, origin) => {
+        log.info(`permission ask-human: ${permission}${origin ? ` (${origin})` : ""} → call __browx.confirm(true|false) in DevTools to respond`);
+        try {
+            const sig = await br.awaitSignal("respond", 300_000);
+            const data = sig.data;
+            if (data && data.kind === "confirm" && data.value === true)
+                return "allow";
+            return "deny";
+        }
+        catch {
+            return "deny";
+        }
+    });
+    await applyPermissionCdpBaseline(ctx, entry.permission).catch(() => undefined);
+    // notification-construction policy — per-context wrapper + binding around
+    // `new Notification(...)`. Default `allow` preserves browser default.
+    await attachNotificationPolicy(ctx, entry.notification, async (n) => {
+        log.info(`notification ask-human: ${JSON.stringify({ title: n.title, origin: n.origin })} → call __browx.confirm(true|false) in DevTools to respond`);
+        try {
+            const sig = await br.awaitSignal("respond", 300_000);
+            const data = sig.data;
+            if (data && data.kind === "confirm" && data.value === true)
+                return "allow";
+            return "deny";
+        }
+        catch {
+            return "deny";
+        }
+    });
+    // File System Access picker policy — per-context binding + init-script stubs.
+    // The server-side write target for `createWritable()` is workspace-rooted and
+    // validated against `workspace.root` at `fs_picker_respond` time.
+    await attachFsPickerPolicy(ctx, entry.fsPicker, workspace.root, async (api, suggestedName) => {
+        log.info(`fs-picker ask-human: ${api}${suggestedName ? ` (${suggestedName})` : ""} → call __browx.respond({files:[…]}) in DevTools (or fs_picker_respond) to answer`);
+        try {
+            const sig = await br.awaitSignal("respond", 300_000);
+            const data = sig.data;
+            if (data &&
+                data.kind === "fs_picker_respond" &&
+                Array.isArray(data.value?.files)) {
+                return data.value.files;
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }).catch(() => undefined);
+    // Per-session download capture — always attach the context listener; when
+    // capture is off it just discards Playwright's temp file.
+    attachDownloadCapture(ctx, entry.downloads);
+    // resolve overlay selectors fresh per session so a
+    // `set_config({hideOverlaySelectors})` applies without a server restart.
+    await applyOverlayHide(ctx, configStore.resolve().hideOverlaySelectors);
+    // Per-context stealth init-script patches (capability `stealth`). Off by
+    // default; when on, overrides navigator.webdriver / plugins / languages /
+    // window.chrome on every page before page scripts run.
+    if (caps.enabled.has("stealth")) {
+        await applyStealth(ctx).catch((err) => {
+            log.warn(`stealth: failed to apply init script — ${err instanceof Error ? err.message : String(err)}`);
+        });
+    }
+    // Per-session device-emulation: attach the synthetic Web Bluetooth/USB/HID
+    // catalogs + the per-page reapply of locale/timezone/UA overrides.
+    await attachDeviceEmulation(ctx, entry.webDeviceEmulation).catch(() => undefined);
+    ctx.on("page", (newPage) => {
+        // Best-effort: a new tab fires here. Create its own CDP session to route
+        // locale/timezone/UA overrides. Errors swallowed — re-apply never breaks a
+        // navigation.
+        (async () => {
+            try {
+                const newCdp = await sess.page().context().newCDPSession(newPage);
+                await reapplyEmulation(sess.page().context(), newPage, newCdp, entry.deviceEmulation);
+            }
+            catch {
+                /* best-effort */
+            }
+        })().catch(() => undefined);
+    });
+    // ws-interactive — install the page-side WS wrapper EAGERLY (capability-gated
+    // on `action`) so a page that constructs `new WebSocket(...)` during initial
+    // document parse hits the wrapped constructor.
+    if (caps.enabled.has("action")) {
+        await entry.wsInteractive.install(sess.page()).catch(() => undefined);
+    }
+    // workers — same eager-install posture (capability-gated on `read`): the
+    // page-side Worker-constructor wrapper must be live before any document parse.
+    if (caps.enabled.has("read")) {
+        await entry.workers.installPageWrapper(sess.page()).catch(() => undefined);
+    }
+}

package/dist/session/policy-buffer.d.ts

@@ -0,0 +1,21 @@
+/** A bounded, append-only record ring with a per-record timestamp. The single
+ *  source of the buffer+cap discipline the five policy classes shared.
+ *
+ *  `cap` defaults to 200 (every policy's historical default). `tsOf` extracts the
+ *  per-record timestamp; it defaults to reading a `ts: number` field, so a record
+ *  shaped `{ ts }` needs no extractor, and a record shaped `{ timestamp }` passes
+ *  `(r) => r.timestamp`. */
+export declare class PolicyRecordBuffer<TRecord> {
+    private readonly buffer;
+    private readonly cap;
+    private readonly tsOf;
+    constructor(cap?: number, tsOf?: (rec: TRecord) => number);
+    /** Append a record; drop the oldest once the ring exceeds `cap`. The one place
+     *  the bound lives. */
+    record(rec: TRecord): void;
+    /** Slice records with timestamp `>= since`. Used by the action-window. */
+    since(since: number): TRecord[];
+    /** True if any record in `[since, now]` satisfies `pred`. Each policy passes
+     *  its own "raised" test — e.g. `(r) => r.handledAs === "raised"`. */
+    matchedSince(since: number, pred: (rec: TRecord) => boolean): boolean;
+}

package/dist/session/policy-buffer.js

@@ -0,0 +1,47 @@
+// RFC 0004 P3 / D4 (DRY). The bounded, timestamp-ordered record ring the five
+// page-policy classes (`DialogPolicyState`, `PermissionPolicyState`,
+// `NotificationPolicyState`, `FsPickerPolicyState`, `DeviceEmulationState`) each
+// hand-rolled verbatim — a `buffer: T[]` + a hard `cap` + `record` / `since` /
+// a predicate-windowed `matchedSince`. Five copies of one bound is five places
+// the cap or the timestamp comparison could drift; this is the single home.
+//
+// The bound is load-bearing (L7 — a chatty page must not grow the ring without
+// limit), so collapsing it here makes the cap one tested value instead of five.
+//
+// Timestamp accessor: four of the five records carry `ts`; `NotificationRecord`
+// carries `timestamp`. Rather than rename a field that is exposed on the wire
+// (`ActionResult` / the policy report), the buffer takes a `tsOf` extractor so
+// each policy keeps its own record shape verbatim — byte-identical behaviour,
+// one shared bound.
+/** A bounded, append-only record ring with a per-record timestamp. The single
+ *  source of the buffer+cap discipline the five policy classes shared.
+ *
+ *  `cap` defaults to 200 (every policy's historical default). `tsOf` extracts the
+ *  per-record timestamp; it defaults to reading a `ts: number` field, so a record
+ *  shaped `{ ts }` needs no extractor, and a record shaped `{ timestamp }` passes
+ *  `(r) => r.timestamp`. */
+export class PolicyRecordBuffer {
+    buffer = [];
+    cap;
+    tsOf;
+    constructor(cap = 200, tsOf) {
+        this.cap = cap;
+        this.tsOf = tsOf ?? ((rec) => rec.ts);
+    }
+    /** Append a record; drop the oldest once the ring exceeds `cap`. The one place
+     *  the bound lives. */
+    record(rec) {
+        this.buffer.push(rec);
+        if (this.buffer.length > this.cap)
+            this.buffer.shift();
+    }
+    /** Slice records with timestamp `>= since`. Used by the action-window. */
+    since(since) {
+        return this.buffer.filter((r) => this.tsOf(r) >= since);
+    }
+    /** True if any record in `[since, now]` satisfies `pred`. Each policy passes
+     *  its own "raised" test — e.g. `(r) => r.handledAs === "raised"`. */
+    matchedSince(since, pred) {
+        return this.buffer.some((r) => this.tsOf(r) >= since && pred(r));
+    }
+}

package/dist/session/profile-snapshot.d.ts

@@ -0,0 +1,11 @@
+export interface ProfileSnapshotResult {
+    ok: boolean;
+    action: "snapshot" | "restore";
+    profile: string;
+    snapshot: string;
+}
+/** Copy a profile directory into a named snapshot (overwrites an existing
+ *  snapshot of the same name). */
+export declare function snapshotProfile(workspaceRoot: string, profile: string | undefined, snapshot: string): ProfileSnapshotResult;
+/** Restore a named snapshot back over a profile directory. */
+export declare function restoreProfile(workspaceRoot: string, profile: string | undefined, snapshot: string): ProfileSnapshotResult;

package/dist/session/profile-snapshot.js

@@ -0,0 +1,53 @@
+// Profile snapshot / restore — capability `human`.
+//
+// A destructive authenticated-SPA test mutates the persistent profile (an
+// accidental timeline edit, a half-finished form, dirty local state). Repeat
+// runs then start from a polluted baseline. This copies a session's profile
+// directory to/from a named snapshot under the workspace, so a test can
+// checkpoint a clean state and restore it between runs.
+//
+// Copying a profile dir while Chromium has it open yields a corrupt copy
+// (locked SQLite, in-flight writes) — the caller MUST close sessions first;
+// the server tool enforces that guard.
+import { cpSync, existsSync } from "node:fs";
+import { join } from "node:path";
+// mnemonic / profile names — no path separators or traversal.
+const SAFE_NAME = /^[A-Za-z0-9._-]+$/;
+function checkName(kind, name) {
+    if (!SAFE_NAME.test(name)) {
+        throw new Error(`${kind} "${name}" invalid — use only letters, digits, '.', '_', '-' (no path separators)`);
+    }
+}
+/** The on-disk dir for a session profile. `default`/undefined → `<root>/profile`
+ *  (the legacy single-profile path); a name → `<root>/profiles/<name>`. */
+function profileDir(workspaceRoot, profile) {
+    if (!profile || profile === "default")
+        return join(workspaceRoot, "profile");
+    checkName("profile", profile);
+    return join(workspaceRoot, "profiles", profile);
+}
+function snapshotDir(workspaceRoot, snapshot) {
+    checkName("snapshot", snapshot);
+    return join(workspaceRoot, "profile-snapshots", snapshot);
+}
+/** Copy a profile directory into a named snapshot (overwrites an existing
+ *  snapshot of the same name). */
+export function snapshotProfile(workspaceRoot, profile, snapshot) {
+    const src = profileDir(workspaceRoot, profile);
+    const dest = snapshotDir(workspaceRoot, snapshot);
+    if (!existsSync(src)) {
+        throw new Error(`profile_snapshot: no profile directory at "${src}" — open a persistent session with this profile first`);
+    }
+    cpSync(src, dest, { recursive: true, force: true });
+    return { ok: true, action: "snapshot", profile: profile ?? "default", snapshot };
+}
+/** Restore a named snapshot back over a profile directory. */
+export function restoreProfile(workspaceRoot, profile, snapshot) {
+    const src = snapshotDir(workspaceRoot, snapshot);
+    const dest = profileDir(workspaceRoot, profile);
+    if (!existsSync(src)) {
+        throw new Error(`profile_restore: no snapshot "${snapshot}" — take one with profile_snapshot first`);
+    }
+    cpSync(src, dest, { recursive: true, force: true });
+    return { ok: true, action: "restore", profile: profile ?? "default", snapshot };
+}

package/dist/session/registry.d.ts

@@ -0,0 +1,365 @@
+import type { BrowserSession } from "./types.js";
+import type { RefRegistry } from "../page/refs.js";
+import type { SnapshotSubstrate } from "../page/snapshot-substrate.js";
+import type { FrameRegistry } from "../page/frames.js";
+import type { ConsoleBuffer } from "../page/console.js";
+import type { SessionNetworkRing, SessionWsRing } from "../page/network.js";
+import type { NetworkSubstrate } from "../page/network-substrate.js";
+import type { WsInteractiveRegistry } from "../page/ws-interactive.js";
+import type { WorkersRegistry } from "../page/workers.js";
+import type { BrowxBridge } from "../helper/bridge.js";
+import type { Recorder } from "../page/recording.js";
+import type { FeedbackMemory } from "../page/learning.js";
+import type { ClipboardBuffer } from "../page/clipboard.js";
+import type { RouteRegistry } from "../page/routes.js";
+import type { RegionRegistry } from "../page/regions.js";
+import type { EmulationRegistry } from "../page/emulation.js";
+import type { ClockRegistry } from "../page/clock.js";
+import type { SeededRandomRegistry } from "../page/seed-random.js";
+import type { PerfTracingState } from "../page/perf.js";
+import type { CoverageTrackerState } from "../page/coverage.js";
+import type { WedgeTracker } from "./wedge.js";
+import type { SessionMetrics } from "./metrics.js";
+import type { DialogPolicy, DialogPolicyState } from "./dialog.js";
+import type { PermissionPolicy, PermissionPolicyState } from "./permission.js";
+import type { NotificationPolicy, NotificationPolicyState } from "./notification.js";
+import type { FsPickerPolicy, FsPickerPolicyState } from "./fs-picker.js";
+import type { EmulationState as DeviceEmulationState } from "./emulation.js";
+import type { DeviceEmulationState as WebDeviceEmulationState } from "./device-emu.js";
+import type { SecretRegistry } from "../util/secrets.js";
+import type { HarRecorderState, HarStartConfig } from "../page/har.js";
+import type { VideoRecorderState, VideoStartConfig } from "../page/video.js";
+import type { ExtensionRegistry } from "./extensions.js";
+import type { DownloadsRegistry } from "../page/downloads.js";
+import type { ArtifactsRegistry } from "./artifacts.js";
+export type SessionMode = "persistent" | "incognito" | "attached";
+/**
+ * RFC 0004 P3 / D3 (ISP). The per-session state is segregated into the role
+ * bundles its consumers actually use — engine-core, observation, network, the
+ * four page-policy buffers, live + deep emulation, capture/artifact, and the
+ * cross-cutting feature concerns — instead of one 40-field record every tool
+ * depends on whole. `SessionEntry` stays the composed WHOLE (the intersection of
+ * the bundles, declared at the bottom), so no field moves at runtime and the
+ * factory keeps building one object; a consumer that reads only `e.refs` /
+ * `e.dialog` can depend on `SessionObserveRole` / `SessionPolicyRole` and stop
+ * recompiling when an unrelated feature field changes. Per 0004-03 §3.
+ */
+/** Engine-core identity + lifecycle. The fields every consumer that touches the
+ *  live browser handle reads. */
+export interface SessionCore {
+    id: string;
+    mode: SessionMode;
+    session: BrowserSession;
+    openedAt: number;
+    /** epoch ms of the last `get()` for this id — drives idle-age
+     *  reaping (`close_sessions({ idleMs })`) at multi-agent scale. */
+    lastActivityAt: number;
+    /** Profile-name component used at launch (persistent mode only). Recorded
+     *  so the rebuild path used by `extensions_*` can recompute the same
+     *  profileDir without re-deriving the spec. Undefined for incognito /
+     *  attached sessions. */
+    launchProfile?: string;
+}
+/** Observation role — the snapshot/find/frames/console reads. */
+export interface SessionObserveRole {
+    refs: RefRegistry;
+    /** Engine-agnostic snapshot/a11y tree source. Chromium gets the
+     *  verbatim CDP substrate (Accessibility.getFullAXTree + DOM-walk); firefox /
+     *  webkit get the page-side Playwright walker. The snapshot / find / extract /
+     *  text_search / set-of-marks tools and the action-window pre/post deltas mint
+     *  refs through this seam instead of reaching a raw CDPSession — so they run on
+     *  any engine, not only chromium. Selected once at session creation
+     *  (`snapshotSubstrateFor`) so the hot path is a captured-handle delegate. */
+    snapshotSubstrate: SnapshotSubstrate;
+    /** Engine-agnostic network tap + ActionResult-network-slice source.
+     *  Chromium gets the verbatim CDP substrate (NetworkBuffer / WsBuffer /
+     *  NetworkTap / fetchResponseBody); firefox / webkit get the Playwright context-
+     *  event substrate. The session-wide rings below (`network` / `ws`) ARE this
+     *  substrate's rings; the action window mints its per-action tap from it and
+     *  `network_body` fetches through it — so the network tools + the envelope's
+     *  network slice run on any engine. Selected once at session creation
+     *  (`networkSubstrateFor`) so the hot path is a captured-handle delegate. */
+    networkSubstrate: NetworkSubstrate;
+    /** per-session frame ID assignment. `frames_list` mints/looks up
+     *  stable `fN` IDs from this registry; snapshot/find/action consult it to
+     *  resolve a `frame` arg back to a Playwright `Frame` handle. */
+    frames: FrameRegistry;
+    console: ConsoleBuffer;
+}
+/** Network role — the session-wide rings + the engine-selected network substrate
+ *  and the interactive-WS / workers / route registries. */
+export interface SessionNetworkRole {
+    /** session-wide HTTP request ring (`networkSubstrate.http`). */
+    network: SessionNetworkRing;
+    /** session-wide WebSocket/SSE frame ring (`networkSubstrate.ws`). */
+    ws: SessionWsRing;
+    /** per-session interactive-WS registry (capability `action`). Lazy:
+     *  the page-side wrapper is only installed on first `ws_send` /
+     *  `ws_intercept`. Holds the active interceptor patterns server-side
+     *  so `unintercept` / `list` answer locally without a page round-trip. */
+    wsInteractive: WsInteractiveRegistry;
+    /** per-session worker visibility (Web Workers + Service Workers).
+     *  Holds the page-side `__browxWorkers` wrapper state + the CDP-side SW
+     *  attachments. Lazy in the same shape as `wsInteractive` — eagerly
+     *  installed at session creation when `read` is on so workers opened by
+     *  the initial document are seen; otherwise the wrapper installs on first
+     *  `workers_list` / `worker_message_send` / `sw_intercept_fetch` call. */
+    workers: WorkersRegistry;
+    /** per-session network route interceptions (capability `action`). */
+    routes: RouteRegistry;
+}
+/** Feature role — the cross-cutting per-session services a handler reaches for
+ *  one feature at a time (the helper bridge, the recorder, learning feedback,
+ *  the clipboard model, and the named-region store). */
+export interface SessionFeatureRole {
+    bridge: BrowxBridge;
+    recorder: Recorder;
+    feedback: FeedbackMemory;
+    /** per-session clipboard model (capability `clipboard`). Isolated so
+     *  concurrent sessions don't clobber each other through the shared OS
+     *  clipboard; the OS clipboard is touched only transactionally. */
+    clipboard: ClipboardBuffer;
+    /** per-session named visual regions (capability `human`). */
+    regions: RegionRegistry;
+}
+/** Live-emulation role — the runtime knobs that re-apply on navigation
+ *  (network/CPU throttling, virtual clock, seeded randomness). */
+export interface SessionEmulationRole {
+    /** per-session network + CPU emulation overrides (capability `action`).
+     *  Caches active state and re-applies on main-frame navigation. */
+    emulation: EmulationRegistry;
+    /** per-session virtual-time clock controller (capability `action`).
+     *  Wraps CDP `Emulation.setVirtualTimePolicy` for deterministic
+     *  date-sensitive testing; re-applies on main-frame navigation. */
+    clock: ClockRegistry;
+    /** per-session seeded `Math.random` override (capability `action`). Init
+     *  script wraps Mulberry32 so date / pick-randomly / id-gen flake repros
+     *  are deterministic. Per-session; `crypto.randomUUID` /
+     *  `crypto.getRandomValues` NOT touched in MVP. */
+    seededRandom: SeededRandomRegistry;
+}
+/** Deep role — the CDP-deep tracing/coverage state the `perf_*` / `coverage_*`
+ *  tools drive (Chromium-only). */
+export interface SessionDeepRole {
+    /** per-session CDP performance tracing state (capability `action`). One
+     *  trace lifecycle at a time per session; `perf_start` while a trace is
+     *  already running cleanly restarts (see src/page/perf.ts). */
+    perf: PerfTracingState;
+    /** per-session CDP precise-coverage tracker (capability split — `coverage_start`
+     *  is `action`, `coverage_stop` is `read`). Pairs JS Profiler + CSS rule
+     *  usage trackers into one lifecycle. Internally used by `perf_audit`. */
+    coverage: CoverageTrackerState;
+}
+/** Health role — the per-session anti-wedge + metrics bookkeeping the dispatch
+ *  wrapper accumulates. */
+export interface SessionHealthRole {
+    /** Per-session consecutive anti-wedge-timeout counter; drives the
+     *  `sessionWedged` signal once the session times out repeatedly. */
+    wedge: WedgeTracker;
+    /** Per-session cumulative tool-call metrics (counts, latency,
+     *  tokensEstimate sum, capability denials, errors). Accumulated by the
+     *  dispatch wrapper in `server.ts`; surfaced via the `session_metrics`
+     *  tool. Read-only from the agent's side — no per-call disk writes. */
+    metrics: SessionMetrics;
+}
+/** Policy role — the four page-policy buffers (dialog / permission / notification
+ *  / fs-picker) a handler reads or mutates together. */
+export interface SessionPolicyRole {
+    /** per-session dialog policy + per-page handler bookkeeping. Survives
+     *  navigation: the `context.on('page')` install re-attaches the handler on
+     *  every new page (capability `action` — no separate capability). */
+    dialog: DialogPolicyState;
+    /** per-session permission policy + per-context binding/init-script
+     *  bookkeeping. Sibling of `dialog`: governs camera/microphone/geolocation/
+     *  clipboard/notification/sensor permission requests fired from the page.
+     *  Default `raise` (deterministic anti-deadlock). Mutable at runtime via
+     *  `set_permission_policy`; persists across navigation (init-script is
+     *  re-injected on every new document). Capability `action`. */
+    permission: PermissionPolicyState;
+    /** per-session notification policy + per-context binding/init-script
+     *  bookkeeping. Sibling of `permission`: governs `new Notification(...)`
+     *  *constructor* calls (the page actually attempting to notify the human).
+     *  Distinct from `permission.notifications` — that gates the W3C permission
+     *  check (`Notification.requestPermission` + `Notification.permission`),
+     *  this gates the constructor surface. The two policies compose. Default
+     *  `allow` (browser default — most apps expect the constructor to succeed).
+     *  Mutable at runtime via `set_notification_policy`; persists across
+     *  navigation. Capability `action`. */
+    notification: NotificationPolicyState;
+    /** per-session File System Access picker policy + per-context binding /
+     *  init-script bookkeeping. Sibling of `dialog` / `permission`: governs
+     *  `showOpenFilePicker` / `showSaveFilePicker` / `showDirectoryPicker`
+     *  calls fired from the page. Default `raise` (deterministic anti-
+     *  deadlock — without a policy, headless sessions deadlock on the picker
+     *  dialog that has no driver). Mutable at runtime via
+     *  `set_fs_picker_policy`; persists across navigation (init-script is
+     *  re-injected on every new document). Capability `action` for the
+     *  policy mutators; `file-io` for `fs_picker_respond`. */
+    fsPicker: FsPickerPolicyState;
+}
+/** Device-emulation role — the per-primitive live-emulation state + the synthetic
+ *  Web Bluetooth/USB/HID device catalogs. */
+export interface SessionDeviceRole {
+    /** Per-primitive runtime device-emulation state (locale, timezone,
+     *  geolocation, colour scheme, reduced motion, user-agent, permissions).
+     *  Mutated by the 7 `set_*` / `grant_permissions` tools and re-applied
+     *  when a new page opens in the context. Distinct from `emulation`
+     *  (which holds network/cpu throttling state). */
+    deviceEmulation: DeviceEmulationState;
+    /** Per-session Web Bluetooth / WebUSB / WebHID device-catalog state. Off
+     *  by default — empty catalogs until `emulate_bluetooth` / `emulate_usb`
+     *  / `emulate_hid` populate them. Capability `device-emulation`. When
+     *  the capability is off, the page-side wrappers still install (so the
+     *  default user-dismissed-picker shape is delivered without a deadlock
+     *  on headless), but the check binding short-circuits to `refused`. */
+    webDeviceEmulation: WebDeviceEmulationState;
+}
+/** Capture role — the artifact-egress + sensitive-data state: HAR / video
+ *  recorders, the secrets registry, loaded extensions, and the download /
+ *  artifact stores. */
+export interface SessionCaptureRole {
+    /** Per-session HAR recorder state (HTTP Archive record/replay). Drives the
+     *  `start_har`/`stop_har` tools and tracks any HAR wired at session creation
+     *  via `open_session({har})`. Capability `action` (writes a file). The HAR
+     *  file is finalized by Playwright on `context.close()` — the recorder state
+     *  carries the reserved path until then. */
+    har: HarRecorderState;
+    /** Per-session video recorder state. Drives the `stop_video` / `get_video`
+     *  tools and tracks any video wired at session creation via
+     *  `open_session({recordVideo})`. Same finalize-on-close caveat as HAR:
+     *  Playwright writes the .webm only when the context closes; the
+     *  registry's teardown calls `page.video().saveAs(targetPath)` for a
+     *  deterministic output filename. Capability `file-io` (writes a file). */
+    video: VideoRecorderState;
+    /** per-session sensitive-data registry (capability `secrets`). Off by
+     *  default — empty until `register_secret` is called. When non-empty, every
+     *  egress sink masks occurrences of the real value back to `<NAME>` before
+     *  emitting; `fill`/`press` materialise `<NAME>` to the real value at
+     *  dispatch. The registry is per-session so concurrent sessions don't share
+     *  an auth-flow's secrets. */
+    secrets: SecretRegistry;
+    /** per-session loaded Chrome extensions (capability `extensions`). Empty
+     *  by default; mutated by `extensions_install` / `extensions_reload` /
+     *  `extensions_uninstall`. The list also drives the launch flags
+     *  (`--load-extension`, `--disable-extensions-except`) when the underlying
+     *  browser context is (re)built — extensions are a launch-time concern in
+     *  Chromium. Persistent (headed) sessions only — `incognito` / `attached`
+     *  reject the mutators with a structured error. */
+    extensions: ExtensionRegistry;
+    /** per-session download-capture registry (capability `file-io`). Off by
+     *  default — every Playwright `download` event is intercepted and discarded
+     *  until `downloads_capture({on:true})` toggles capture on. When on, the
+     *  artifact is persisted to `$BROWX_WORKSPACE/.downloads/<sessionId>/` and
+     *  surfaced on `ActionResult.downloads[]`. Same posture as `upload_file`'s
+     *  workspace-rooted-paths model — the reverse direction. */
+    downloads: DownloadsRegistry;
+    /** per-session artifact KV (capabilities `action` for save, `read` for
+     *  get/list). Workspace-rooted at `$BROWX_WORKSPACE/.artifacts/<sessionId>/`.
+     *  Capacity-bounded (200 entries / 50 MiB; oldest-write evicted past the
+     *  cap). The on-disk dir is wiped on session teardown — sessions that
+     *  never wrote an artifact leave no trace. */
+    artifacts: ArtifactsRegistry;
+}
+/** Per-session state. Everything here was a server-singleton pre-multi-session;
+ *  one of these exists per live session id. Composed (RFC 0004 P3 / D3) as the
+ *  INTERSECTION of the role bundles above — no field moved at runtime; a consumer
+ *  may depend on the narrow role it reads (e.g. `SessionPolicyRole`) instead of
+ *  the whole record. The factory in server.ts still builds one object. */
+export interface SessionEntry extends SessionCore, SessionObserveRole, SessionNetworkRole, SessionFeatureRole, SessionEmulationRole, SessionDeepRole, SessionHealthRole, SessionPolicyRole, SessionDeviceRole, SessionCaptureRole {
+}
+export declare const DEFAULT_SESSION_ID = "default";
+/** Per-session creation spec, supplied by `open_session` (or undefined for the
+ *  lazily-created default, which falls back to the server's launch mode). */
+export interface OpenSpec {
+    mode?: SessionMode;
+    /** Persistent mode only: named profile dir under the workspace. */
+    profile?: string;
+    /** Playwright device-preset name (e.g. "iPhone 14"). */
+    device?: string;
+    /** explicit viewport; overrides a preset's viewport. */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** initial dialog policy for this session (default `{mode:"raise"}`).
+     *  Mutable at runtime via `set_dialog_policy`; see src/session/dialog.ts. */
+    dialogPolicy?: DialogPolicy;
+    /** initial permission policy for this session (default `{mode:"raise"}`).
+     *  Mutable at runtime via `set_permission_policy`; see
+     *  src/session/permission.ts. */
+    permissionPolicy?: PermissionPolicy;
+    /** initial notification policy for this session (default `{mode:"allow"}`).
+     *  Governs `new Notification(...)` constructor calls (distinct from the
+     *  permission check, which lives in `permissionPolicy.notifications`).
+     *  Mutable at runtime via `set_notification_policy`; see
+     *  src/session/notification.ts. */
+    notificationPolicy?: NotificationPolicy;
+    /** initial File System Access picker policy for this session (default
+     *  `{mode:"raise"}`). Mutable at runtime via `set_fs_picker_policy`;
+     *  see src/session/fs-picker.ts. */
+    fsPickerPolicy?: FsPickerPolicy;
+    /** Seed the new context's storage state at creation (bulk layer).
+     *  Either an inline blob (as returned by `dump_storage_state`) or a
+     *  workspace-rooted JSON path. Mutually exclusive with `authState`.
+     *  See `src/session/storage.ts` for the per-mode semantics
+     *  (incognito: native primitive; managed: post-create + clears profile;
+     *   attached: ignored). */
+    storageState?: import("./storage.js").StorageStateBlob | string;
+    /** Seed the new context's storage state at creation from a named slot
+     *  (`$BROWX_WORKSPACE/.auth-states/<name>.json`, written by `auth_save`).
+     *  Mutually exclusive with `storageState`. */
+    authState?: string;
+    /** Enable HAR recording at context creation (native Playwright `recordHar`).
+     *  The HAR is finalized when the session closes. For mid-session start/stop
+     *  use the `start_har`/`stop_har` tools instead — they wire HAR via
+     *  `routeFromHAR(update:true)` on the running context. */
+    har?: HarStartConfig;
+    /** Enable video recording at context creation via Playwright's native
+     *  `recordVideo` context option. The .webm is finalized when the session
+     *  closes. There is no runtime `start_video` tool (Playwright doesn't
+     *  expose a mid-context start) — wire it here at session creation. The
+     *  target path is workspace-rooted (default
+     *  `<workspace>/videos/<session-id>-<ISO>.webm`); on `close_session` the
+     *  registry calls `page.video().saveAs(targetPath)` for a deterministic
+     *  filename. Honoured on `persistent` + `incognito`; refused on
+     *  `attached` (not-owned). */
+    recordVideo?: VideoStartConfig;
+    /** Workspace-rooted HAR file path(s) to REPLAY against this session. Each
+     *  file is wired post-create with `context.routeFromHAR(file,
+     *  {notFound:"fallback"})` — requests in the archive are served from it,
+     *  anything missing falls through to the live network. */
+    hars?: string[];
+}
+export declare class SessionRegistry {
+    private factory;
+    private teardown;
+    private entries;
+    /** In-flight creations, so two concurrent first-calls for the same id don't
+     *  each launch a browser. */
+    private creating;
+    constructor(factory: (id: string, spec?: OpenSpec) => Promise<SessionEntry>, teardown: (e: SessionEntry) => Promise<void>);
+    /** Resolve (or lazily create) the entry for `id`. Concurrency-safe. The
+     *  `spec` is only consulted on creation — once an entry exists it's returned
+     *  as-is regardless of spec. */
+    get(id?: string, spec?: OpenSpec): Promise<SessionEntry>;
+    has(id: string): boolean;
+    /** Non-creating peek — returns undefined if not yet open. */
+    peek(id: string): SessionEntry | undefined;
+    list(): SessionEntry[];
+    /** Tear down + remove one session. Returns false if it wasn't open. */
+    close(id: string): Promise<boolean>;
+    /**
+     * bulk teardown. Selects live sessions by `prefix` (id starts-with),
+     * `all`, and/or `idleMs` (no `get()` in the last N ms). Filters AND together
+     * when multiple are given; at least one selector is required. Returns the
+     * closed ids (in selection order). The team-lead reap primitive — at
+     * multi-agent scale a wedged/killed agent strands sessions.
+     */
+    closeMatching(sel: {
+        prefix?: string;
+        all?: boolean;
+        idleMs?: number;
+    }): Promise<string[]>;
+    /** Tear down everything (server shutdown). */
+    closeAll(): Promise<void>;
+}