browxai 0.7.0

package/dist/tools/session-notification-device-tools.js

@@ -0,0 +1,156 @@
+import { estimateTokens } from "../util/tokens.js";
+import { readPermissionStates, SUPPORTED_PERMISSIONS, } from "../session/permission.js";
+import { propagateSyncDecision as propagateNotificationSyncDecision, } from "../session/notification.js";
+import { SUPPORTED_DEVICE_APIS } from "../session/device-emu.js";
+import { SESSION_ARG } from "./schemas.js";
+/**
+ * Permission-state read + notification policy + device-request read tools:
+ * permission_state / set_notification_policy / device_requests. Split out of
+ * `session-policy-tools` by cohesive family (RFC 0004 P3 / D3 SRP); registered
+ * through the shared `ToolHost` seam in the same source order. The host owns the
+ * closures (register / gate / entry).
+ */
+export function registerSessionNotificationDeviceTools(host) {
+    const { z, register, gateCheck, entryFor } = host;
+    register("permission_state", {
+        capability: "read",
+        description: 'Read the current permission state(s) for an origin via the W3C Permissions API (`navigator.permissions.query` — which reflects the CDP-applied baseline). Returns `{ [permission]: "granted" | "denied" | "prompt" | "unknown" }` per requested name. Defaults the `origin` to the current page\'s origin when omitted. Read-only — does not mutate state. Supported permission names (v1): ' +
+            SUPPORTED_PERMISSIONS.join(", ") +
+            ". Sibling of `set_permission_policy`.",
+        inputSchema: {
+            permissions: z
+                .array(z.string())
+                .min(1)
+                .describe('Canonical permission names to query — see tool description for the supported set. Unknown names map to `"unknown"` in the result.'),
+            origin: z
+                .string()
+                .optional()
+                .describe('Origin to query (e.g. "https://example.com"). Omit to use the current page\'s origin.'),
+            ...SESSION_ARG,
+        },
+    }, async ({ permissions, origin, session }) => {
+        const g = gateCheck("permission_state");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        try {
+            const supported = permissions.filter((p) => SUPPORTED_PERMISSIONS.includes(p));
+            const states = await readPermissionStates(e.session.page().context(), e.session.page(), supported, origin);
+            const out = { ...states };
+            for (const p of permissions) {
+                if (!(p in out))
+                    out[p] = "unknown";
+            }
+            const body = {
+                ok: true,
+                session: e.id,
+                origin: origin ??
+                    (() => {
+                        try {
+                            return new URL(e.session.page().url()).origin;
+                        }
+                        catch {
+                            return null;
+                        }
+                    })(),
+                states: out,
+                tokensEstimate: estimateTokens(JSON.stringify(out)),
+            };
+            return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ok: false, error: err instanceof Error ? err.message : String(err) }, null, 2),
+                    },
+                ],
+            };
+        }
+    });
+    register("set_notification_policy", {
+        capability: "action",
+        description: "Mutate the session's notification policy at runtime. Governs `new Notification(title, opts)` *constructor* calls — the page actually attempting to display a notification. Distinct from `set_permission_policy` (which gates `Notification.requestPermission` and the `Notification.permission` state); the two policies compose. Modes:\n" +
+            '  - "allow"     — DEFAULT (browser default). Constructor proceeds; the OS displays per its own settings. Every call is still captured on `ActionResult.notifications[]` for observability.\n' +
+            '  - "deny"      — Constructor throws `NotAllowedError` (the same exception the browser raises when permission is denied). Use to suppress OS notifications while still observing what the page would have shown.\n' +
+            '  - "raise"     — Constructor throws AND RECORDS; the next ActionResult flips `ok:false` with `failure:{source:"app", hint:"unhandled notification — set notificationPolicy"}`. Useful when notifications should be a hard signal that the action triggered an unexpected user-facing event.\n' +
+            '  - "ask-human" — server blocks on `__browx.confirm(true|false)` (the `await_human({kind:"confirm"})` mechanism), then resolves to allow/deny per the human\'s answer. The constructor returns a stub synchronously (the spec requires a sync return); the real OS notification fires once the human-decision resolves.\n' +
+            "Persists across navigation: the init-script is re-injected on every new document within the session. Returns the resolved policy. Captured calls surface on `ActionResult.notifications[] = [{title, body?, icon?, tag?, timestamp, origin?, handledAs}]`.",
+        inputSchema: {
+            mode: z
+                .enum(["allow", "deny", "raise", "ask-human"])
+                .describe("Policy mode — see tool description."),
+            ...SESSION_ARG,
+        },
+    }, async (args) => {
+        const g = gateCheck("set_notification_policy");
+        if (g)
+            return g;
+        const e = await entryFor(args.session);
+        try {
+            const next = { mode: args.mode };
+            const resolved = e.notification.set(next);
+            // Push the new sync-decision hint to every live page so the
+            // constructor's throw timing tracks the policy without a reload.
+            await propagateNotificationSyncDecision(e.session.page().context(), e.notification).catch(() => undefined);
+            const tokensEstimate = estimateTokens(JSON.stringify(resolved));
+            const body = { ok: true, session: e.id, policy: resolved, tokensEstimate };
+            return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ok: false, error: err instanceof Error ? err.message : String(err) }, null, 2),
+                    },
+                ],
+            };
+        }
+    });
+    register("device_requests", {
+        capability: "device-emulation",
+        description: 'Read-side companion to `emulate_bluetooth` / `emulate_usb` / `emulate_hid`. Returns the buffer of `requestDevice()` calls the page has made on this session — one entry per page-side call, each with `{api, handledAs, returned, filters?, ts}`. Useful for diagnosing "did the page even ask?" when a flow gated on hardware appears stuck. `handledAs`:\n' +
+            '  - `"resolved"`  — catalog non-empty; picker resolved with the synthetic device (Bluetooth/USB) or device list (HID).\n' +
+            '  - `"rejected"` — catalog empty for Bluetooth/USB; picker rejected with `NotFoundError` (user-dismissed shape).\n' +
+            '  - `"empty"`    — catalog empty for HID; picker resolved with `[]` (HID\'s user-dismissed shape).\n' +
+            '  - `"refused"`  — capability `device-emulation` was OFF at the time of the call; the wrapper short-circuited. Recorded so the read surfaces "the page asked for hardware and you didn\'t have the capability on".\n' +
+            "**Gated behind the off-by-default `device-emulation` capability** — a server without the capability can't even read whether the page tried to ask (same posture class as `eval` / `network-body` / `secrets`). Read-only — does not mutate state.",
+        inputSchema: {
+            since: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("epoch ms — return only records with `ts >= since`. Default 0 (return everything in the buffer)."),
+            ...SESSION_ARG,
+        },
+    }, async ({ since, session }) => {
+        const g = gateCheck("device_requests");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        try {
+            const records = e.webDeviceEmulation.since(typeof since === "number" ? since : 0);
+            const body = {
+                ok: true,
+                session: e.id,
+                supportedApis: [...SUPPORTED_DEVICE_APIS],
+                requests: records,
+            };
+            body.tokensEstimate = estimateTokens(JSON.stringify(body));
+            return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ok: false, error: err instanceof Error ? err.message : String(err) }, null, 2),
+                    },
+                ],
+            };
+        }
+    });
+}

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

@@ -0,0 +1,16 @@
+import type { ToolHost } from "./host.js";
+/**
+ * Session lifecycle + per-session policy tools — open / close / list sessions and
+ * the runtime policy mutators a session is driven with: dialog, permission,
+ * file-system-picker, and notification policies, plus the permission-state read
+ * and the device-request read companion.
+ *
+ * RFC 0004 P3 / D3 (SRP): the registrations were split by cohesive family into
+ * three sibling modules (lifecycle / dialog-permission-fs-picker /
+ * notification-device). 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 host owns
+ * the closures (register / gate / entry / registry / workspace); the family
+ * modules own the registrations.
+ */
+export declare function registerSessionPolicyTools(host: ToolHost): void;

package/dist/tools/session-policy-tools.js

@@ -0,0 +1,22 @@
+import { registerSessionLifecycleTools } from "./session-lifecycle-tools.js";
+import { registerSessionDialogPermissionTools } from "./session-dialog-permission-tools.js";
+import { registerSessionNotificationDeviceTools } from "./session-notification-device-tools.js";
+/**
+ * Session lifecycle + per-session policy tools — open / close / list sessions and
+ * the runtime policy mutators a session is driven with: dialog, permission,
+ * file-system-picker, and notification policies, plus the permission-state read
+ * and the device-request read companion.
+ *
+ * RFC 0004 P3 / D3 (SRP): the registrations were split by cohesive family into
+ * three sibling modules (lifecycle / dialog-permission-fs-picker /
+ * notification-device). 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 host owns
+ * the closures (register / gate / entry / registry / workspace); the family
+ * modules own the registrations.
+ */
+export function registerSessionPolicyTools(host) {
+    registerSessionLifecycleTools(host);
+    registerSessionDialogPermissionTools(host);
+    registerSessionNotificationDeviceTools(host);
+}

package/dist/tools/session-registry.d.ts

@@ -0,0 +1,28 @@
+import { type EngineKind } from "../engine/index.js";
+import "../engine/register-engines.js";
+import { SessionRegistry, type SessionMode } from "../session/registry.js";
+import type { CapabilityConfig } from "../util/capabilities.js";
+import type { ConfigStore, ResolvedConfig } from "../util/config-store.js";
+import type { Workspace } from "../util/workspace.js";
+import type { StartOptions } from "../server.js";
+/** The createServer-owned locals the SessionRegistry factory + teardown close
+ *  over. Bundled here so the construction expression moves verbatim — every
+ *  callback body references these exactly as it did inline in `createServer`. */
+export interface SessionRegistryDeps {
+    opts: StartOptions;
+    resolvedConfig: ResolvedConfig;
+    configStore: ConfigStore;
+    caps: CapabilityConfig;
+    workspace: Workspace;
+    serverEngine: EngineKind;
+    serverDefaultMode: SessionMode;
+}
+/**
+ * Build the per-session `SessionRegistry` — the composition root's session
+ * factory + teardown pair. Moved out of `createServer` verbatim: the "default"
+ * session is still created lazily on the first browser-touching tool call, and
+ * every factory/teardown body is byte-identical to the inline version. The
+ * createServer locals each callback references (config, caps, workspace, …)
+ * arrive through `deps`.
+ */
+export declare function buildSessionRegistry(deps: SessionRegistryDeps): SessionRegistry;

package/dist/tools/session-registry.js

@@ -0,0 +1,427 @@
+import { openManagedSession } from "../session/managed.js";
+import { openByobSession } from "../session/byob.js";
+import { requireCdp } from "../engine/index.js";
+import { engineEntry, byobAttachNeedsEndpoint, } from "../engine/registry.js";
+import "../engine/register-engines.js";
+import { openIncognitoSession } from "../session/incognito.js";
+import { resolveDevice } from "../session/device.js";
+import { newEmulationState } from "../session/emulation.js";
+import { SessionRegistry, DEFAULT_SESSION_ID, } from "../session/registry.js";
+import { newExtensionRegistry } from "../session/extensions.js";
+import { WedgeTracker } from "../session/wedge.js";
+import { SessionMetrics } from "../session/metrics.js";
+import { DialogPolicyState } from "../session/dialog.js";
+import { PermissionPolicyState } from "../session/permission.js";
+import { NotificationPolicyState } from "../session/notification.js";
+import { FsPickerPolicyState } from "../session/fs-picker.js";
+import { DeviceEmulationState as WebDeviceEmulationState } from "../session/device-emu.js";
+import { RefRegistry } from "../page/refs.js";
+import { FrameRegistry } from "../page/frames.js";
+import { RouteRegistry } from "../page/routes.js";
+import { WsInteractiveRegistry } from "../page/ws-interactive.js";
+import { WorkersRegistry } from "../page/workers.js";
+import { EmulationRegistry } from "../page/emulation.js";
+import { ClockRegistry } from "../page/clock.js";
+import { SeededRandomRegistry } from "../page/seed-random.js";
+import { PerfTracingState } from "../page/perf.js";
+import { CoverageTrackerState } from "../page/coverage.js";
+import { RegionRegistry } from "../page/regions.js";
+import { DownloadsRegistry } from "../page/downloads.js";
+import { ArtifactsRegistry } from "../session/artifacts.js";
+import { readStorageStateFile, authLoad } from "../session/storage.js";
+import { SecretRegistry } from "../util/secrets.js";
+import { ClipboardBuffer } from "../page/clipboard.js";
+import { ConsoleBuffer } from "../page/console.js";
+import { newHarRecorderState, buildRecordHarOption, applyHarReplay, resolveHarReplayPaths, } from "../page/har.js";
+import { newVideoRecorderState, buildRecordVideoOption, finalizeVideoOnClose, } from "../page/video.js";
+import { BrowxBridge } from "../helper/bridge.js";
+import { Recorder } from "../page/recording.js";
+import { FeedbackMemory } from "../page/learning.js";
+import { log } from "../util/logging.js";
+/**
+ * Build the per-session `SessionRegistry` — the composition root's session
+ * factory + teardown pair. Moved out of `createServer` verbatim: the "default"
+ * session is still created lazily on the first browser-touching tool call, and
+ * every factory/teardown body is byte-identical to the inline version. The
+ * createServer locals each callback references (config, caps, workspace, …)
+ * arrive through `deps`.
+ */
+export function buildSessionRegistry(deps) {
+    const { opts, resolvedConfig, configStore, caps, workspace, serverEngine, serverDefaultMode } = deps;
+    // This server's OWN post-wire deps (caps / configStore / workspace) — threaded
+    // explicitly into `engineEntry(...).postWire(entry, serverPostWireDeps)` per
+    // session, never a module-global. A module-global would let a SECOND server in
+    // the same process (the in-process SDK transport composes one server per
+    // transport) overwrite this server's caps gate + workspace sandbox-root, so its
+    // post-wire could install another server's action-gated wrappers / stealth
+    // scripts on THIS server's sessions. The closure-owned local makes that
+    // impossible: every session this registry opens wires with exactly these deps.
+    const serverPostWireDeps = { caps, configStore, workspace };
+    // The substrate deps the registry needs to resolve a session's snapshot/network
+    // substrates. The registry only ever reads the bundle's `snapshot`/`network`
+    // selectors (the action/capture selectors — the only ones that consult
+    // ctxFor/describeTarget/save — are resolved in host-build's `substratesFor`, which
+    // owns those host locals). snapshot/network read only `e.session`, so the action/
+    // capture deps here are deliberately unreachable on this path; making them throw
+    // documents that the registry must never drive an action/capture substrate.
+    const registrySubstrateDeps = {
+        ctxFor: () => {
+            throw new Error("session-registry: ctxFor must not be reached — the registry resolves only the " +
+                "snapshot/network substrates (action/capture are host-build's concern).");
+        },
+        describeTarget: () => {
+            throw new Error("session-registry: describeTarget must not be reached (capture is host-build's concern).");
+        },
+        save: () => {
+            throw new Error("session-registry: save must not be reached (capture is host-build's concern).");
+        },
+    };
+    return new SessionRegistry(async (id, spec) => {
+        const headless = opts.headless ?? resolvedConfig.headless;
+        const mode = spec?.mode ?? serverDefaultMode;
+        // resolve the gated web-security flag *fresh* per session so a
+        // `set_config({disableWebSecurity})` takes effect on the next
+        // open_session without a server restart. Off by default.
+        const disableWebSecurity = configStore.resolve().disableWebSecurity === true;
+        // resolve device/viewport — spec overrides config-store defaults.
+        const device = resolveDevice({
+            device: spec?.device ?? resolvedConfig.defaultDevice,
+            viewport: spec?.viewport ?? resolvedConfig.defaultViewport,
+        });
+        // Resolve creation-time storageState (inline blob, workspace path, OR
+        // named slot). Mutually exclusive. `attached`/BYOB sessions ignore it
+        // (not-owned: we don't seed someone else's Chrome).
+        let creationStorageState;
+        if (spec?.storageState !== undefined && spec?.authState !== undefined) {
+            throw new Error(`session "${id}": pass exactly one of \`storageState\` or \`authState\` (not both)`);
+        }
+        if (spec?.authState !== undefined) {
+            creationStorageState = authLoad(workspace.root, spec.authState);
+        }
+        else if (typeof spec?.storageState === "string") {
+            creationStorageState = readStorageStateFile(workspace.root, spec.storageState, "open_session");
+        }
+        else if (spec?.storageState) {
+            creationStorageState = spec.storageState;
+        }
+        // Resolve HAR recording config (native context-creation primitive). The
+        // path is workspace-rooted by construction (resolveWorkspacePath rejects
+        // escape) and the parent dir is created up-front. Ignored on attached
+        // (we don't mutate the consumer's Chrome).
+        let creationRecordHar;
+        let creationRecordHarResolved;
+        if (spec?.har) {
+            const built = buildRecordHarOption(workspace.root, id, spec.har);
+            creationRecordHar = built.recordHar;
+            creationRecordHarResolved = { path: built.path, mode: built.mode, content: built.content };
+        }
+        // Resolve replay HAR paths (workspace-escape rejected; missing file
+        // errors loudly so a typo doesn't silently fall back to live network).
+        let creationReplayHars;
+        if (spec?.hars && spec.hars.length) {
+            creationReplayHars = resolveHarReplayPaths(workspace.root, spec.hars, "open_session");
+        }
+        // Resolve video recording config (native context-creation primitive).
+        // The target path is workspace-rooted by construction; the staging dir
+        // (where Playwright auto-names the file) is also under the workspace.
+        // Ignored on attached (we don't mutate the consumer's Chrome).
+        let creationRecordVideo;
+        let creationRecordVideoResolved;
+        if (spec?.recordVideo) {
+            const built = buildRecordVideoOption(workspace.root, id, spec.recordVideo);
+            creationRecordVideo = built.recordVideo;
+            creationRecordVideoResolved = {
+                targetPath: built.targetPath,
+                stagingDir: built.stagingDir,
+                size: built.size,
+            };
+        }
+        let sess;
+        if (mode === "attached") {
+            // android attach is endpoint-DISCOVERED over adb — it does NOT need
+            // BROWX_ATTACH_CDP; the desktop CDP-attach lane still requires it. The
+            // android-specific fact lives in the engine layer (`byobAttachNeedsEndpoint`),
+            // so this precondition stays engine-agnostic (no `=== "android"` literal).
+            if (byobAttachNeedsEndpoint(serverEngine) && !opts.attachCdp) {
+                throw new Error(`session "${id}": mode "attached" requires the server to be started with BROWX_ATTACH_CDP (per-session attach isn't supported yet)`);
+            }
+            if (creationStorageState) {
+                log.warn(`session "${id}": ignoring storageState/authState for attached/BYOB session — ` +
+                    "the consumer's Chrome is not-owned and we don't seed it. Use inject_storage_state " +
+                    "explicitly if you really mean to overwrite the attached browser's state.");
+            }
+            if (creationRecordHar) {
+                log.warn(`session "${id}": ignoring \`har\` recording for attached/BYOB session — ` +
+                    "the consumer's Chrome is not-owned and we don't wire context-creation primitives on it. " +
+                    "Use `start_har` post-attach if you really want HAR on a BYOB session " +
+                    "(it routes via runtime `routeFromHAR`, with the same finalize-on-context-close caveat).");
+                creationRecordHar = undefined;
+                creationRecordHarResolved = undefined;
+            }
+            if (creationRecordVideo) {
+                // Hard refusal: video has no runtime fallback (Playwright doesn't
+                // expose mid-context video start), so a silent ignore would leave
+                // the agent expecting a .webm that never lands. Surface it loudly.
+                throw new Error(`session "${id}": \`recordVideo\` is not supported on attached / BYOB sessions — ` +
+                    "Playwright's `recordVideo` is a context-creation primitive and we don't " +
+                    "wire context-creation primitives on the consumer's Chrome (not-owned). " +
+                    'Open a managed session (open_session({mode:"persistent"}) or {mode:"incognito"}) ' +
+                    "with {recordVideo:{...}} to record.");
+            }
+            // Attached Chrome is not-owned: device emulation is best-effort
+            // (viewport via Emulation in byob.ts); isMobile/touch/UA can't be
+            // retro-applied to an existing context.
+            sess = await openByobSession({
+                attachCdp: opts.attachCdp,
+                headless,
+                browserType: serverEngine,
+            });
+        }
+        else if (mode === "incognito") {
+            sess = await openIncognitoSession({
+                headless,
+                device,
+                disableWebSecurity,
+                storageState: creationStorageState,
+                recordHar: creationRecordHar,
+                recordVideo: creationRecordVideo,
+                browserType: serverEngine,
+            });
+        }
+        else {
+            // persistent: the default session keeps the legacy single `profile`
+            // dir for back-compat; named/explicit profiles get their own dir so
+            // sessions don't share a cookie jar on disk.
+            const profileDir = id === DEFAULT_SESSION_ID && !spec?.profile
+                ? workspace.sub("profile")
+                : workspace.sub(`profiles/${spec?.profile ?? id}`);
+            // first launch — no extensions registered yet (the registry is
+            // mutated by the `extensions_*` tools post-creation, and a rebuild
+            // path materialises the list into launch flags then).
+            sess = await openManagedSession({
+                headless,
+                profileDir,
+                device,
+                disableWebSecurity,
+                storageState: creationStorageState,
+                recordHar: creationRecordHar,
+                recordVideo: creationRecordVideo,
+                browserType: serverEngine,
+            });
+        }
+        // Initialise HAR recorder state. If `recordHar` was wired at context
+        // creation, mark the recorder `active + nativeRecord:true` so
+        // `start_har` / `stop_har` can refuse cleanly (the native path can't be
+        // toggled mid-session — Playwright finalizes it on context.close()).
+        const harState = newHarRecorderState();
+        // The per-engine substrate bundle — the EngineRegistry resolves it once per
+        // session (RFC 0004 D1). The seven selectors (actions/capture/storage/script/
+        // emulation/snapshot/network) are the engine's own concern; here we use the
+        // snapshot/network pair to wire the session's substrates. A `{ session }`
+        // partial is enough for those two (they read only `e.session`); the substrate
+        // deps are this server's own (action/capture deps unreachable on this path).
+        const substrates = engineEntry(sess.engine).makeSubstrates(registrySubstrateDeps);
+        const substrateSeed = { session: sess };
+        // safari is the first non-Playwright engine: it has no Playwright Page, no
+        // Playwright BrowserContext. The few creation-config steps below that need
+        // the per-session creation locals (HAR/video state init, HAR replay) stay in
+        // the factory, keyed on the engine's Playwright-Page capability (`!sess.safari`
+        // — a capability check, not an engine-name branch). The full post-creation
+        // attach set (console / bridge / dialog / permission / notification /
+        // fs-picker / downloads / overlay / stealth / device-emulation / ws-interactive
+        // / workers) has been RELOCATED into the engine's `postWire` (called after the
+        // entry is assembled), so the 17 scattered `!== "safari"` guards collapse into
+        // one engine-agnostic call — byte-identical, only owned by the engine now.
+        const hasPlaywrightPage = !sess.safari;
+        if (creationRecordHarResolved && hasPlaywrightPage) {
+            harState.active = true;
+            harState.nativeRecord = true;
+            harState.path = creationRecordHarResolved.path;
+            harState.mode = creationRecordHarResolved.mode;
+            harState.content = creationRecordHarResolved.content;
+            harState.startedAt = Date.now();
+        }
+        // Initialise video recorder state. If `recordVideo` was wired at
+        // context creation, mark the recorder active so `stop_video` /
+        // `get_video` can refer to the reserved target path. The .webm is
+        // finalized when the context closes (Playwright constraint) —
+        // teardown calls `page.video().saveAs(targetPath)`.
+        const videoState = newVideoRecorderState();
+        if (creationRecordVideoResolved && hasPlaywrightPage) {
+            videoState.active = true;
+            videoState.targetPath = creationRecordVideoResolved.targetPath;
+            videoState.stagingDir = creationRecordVideoResolved.stagingDir;
+            videoState.size = creationRecordVideoResolved.size;
+            videoState.startedAt = Date.now();
+        }
+        // Apply HAR replay file(s) post-create. `routeFromHAR` is wired with
+        // `notFound:"fallback"` so a request not in the archive falls through
+        // to live network — the safer default. Replay is honoured on every
+        // session mode (incl. attached: the consumer's Chrome receives the
+        // route handler scoped to its context; warning emitted up-stream).
+        if (creationReplayHars && creationReplayHars.length && hasPlaywrightPage) {
+            await applyHarReplay(sess.page().context(), creationReplayHars);
+        }
+        // per-session console buffer. The page/BiDi attach is the engine's job —
+        // it runs in `postWire` (Playwright: `console.attach(page)`; Safari: the
+        // BiDi `log.entryAdded` bridge), so the buffer is built here and wired below.
+        const consoleBuf = new ConsoleBuffer();
+        // The network/WS substrate is selected by engine capability via the bundle:
+        // chromium (CDP present) gets the verbatim CDP NetworkBuffer/WsBuffer/tap;
+        // firefox/webkit get the Playwright context-event buffers; safari the no-op.
+        // The session-wide rings attach once here; the action window mints its
+        // per-action tap from the substrate and `network_body` fetches through it —
+        // so the network tools + the envelope's network slice run on every engine.
+        const networkSub = substrates.network(substrateSeed);
+        await networkSub.attach();
+        const networkBuf = networkSub.http;
+        const wsBuf = networkSub.ws;
+        // per-session secrets registry. Empty until `register_secret` is
+        // called; the egress sinks below all reference this same instance so
+        // a later register-call lights up masking globally for the session.
+        const secretsReg = new SecretRegistry();
+        consoleBuf.setSecrets(secretsReg);
+        networkSub.setSecrets(secretsReg);
+        const br = new BrowxBridge();
+        // dialog / permission / notification / fs-picker policy STATES are built
+        // here from the spec (the string parsing happened at the open_session tool
+        // layer); their per-context ATTACH lives in the engine's `postWire`.
+        const dialogState = new DialogPolicyState(spec?.dialogPolicy ?? { mode: "raise" });
+        const permissionState = new PermissionPolicyState(spec?.permissionPolicy ?? { mode: "raise" });
+        const notificationState = new NotificationPolicyState(spec?.notificationPolicy ?? { mode: "allow" });
+        const fsPickerState = new FsPickerPolicyState(spec?.fsPickerPolicy ?? { mode: "raise" });
+        // Per-session download capture. Storage dir is workspace-rooted +
+        // per-session — kept off the public profile dir so cleaning up captured
+        // artefacts is a single rmdir without touching the profile. The
+        // registry is off by default; the `downloads_capture` MCP tool toggles
+        // it. The context listener attach lives in the engine's `postWire`.
+        const downloadsDir = workspace.sub(`.downloads/${id}`);
+        const downloadsReg = new DownloadsRegistry(downloadsDir);
+        // Per-session artifact KV. Storage dir is workspace-rooted +
+        // per-session; the dir itself is created lazily on first save, and
+        // wiped on session teardown (see `teardown` below). Capacity-bounded
+        // — 200 entries / 50 MiB, oldest-write evicted.
+        const artifactsDir = workspace.sub(`.artifacts/${id}`);
+        const artifactsReg = new ArtifactsRegistry(artifactsDir);
+        // Fresh per-primitive device-emulation state (locale, timezone,
+        // geolocation, colour scheme, reduced motion, user-agent, permissions).
+        // Re-applied on every new page in this context so a mid-session-opened
+        // tab inherits the overrides — the page-event re-apply attach lives in the
+        // engine's `postWire`.
+        const deviceEmulation = newEmulationState();
+        // Per-session Web Bluetooth / WebUSB / WebHID synthetic-device catalogs
+        // (capability `device-emulation`). The init-script wrappers install in
+        // `postWire`; the catalog is off by default until the emulate_* tools
+        // populate it.
+        const webDeviceEmulation = new WebDeviceEmulationState(caps.enabled.has("device-emulation"));
+        const entry = {
+            id,
+            mode,
+            session: sess,
+            refs: new RefRegistry(),
+            // Engine-agnostic snapshot/a11y substrate, resolved from the engine's
+            // bundle (chromium → the verbatim CDP substrate; firefox/webkit → the
+            // page-side walker; safari → the WebDriver-Classic DOM-walk). Selected by
+            // the engine's capability, never an engine-name check. Captured once here
+            // so the hot snapshot/find path is a direct delegate, no per-call allocation.
+            snapshotSubstrate: substrates.snapshot(substrateSeed),
+            // Engine-agnostic network substrate (also from the bundle). `network` / `ws`
+            // below ARE this substrate's session-wide rings; the action window mints its
+            // per-action tap from it. Captured once here so the hot envelope path is a
+            // captured-handle delegate.
+            networkSubstrate: networkSub,
+            frames: new FrameRegistry(),
+            console: consoleBuf,
+            network: networkBuf,
+            ws: wsBuf,
+            bridge: br,
+            recorder: new Recorder(),
+            feedback: new FeedbackMemory(),
+            clipboard: new ClipboardBuffer(),
+            routes: new RouteRegistry(),
+            // The page-side WS-interactive + workers wrappers install EAGERLY — but
+            // that install is a Playwright-Page concern, so it has moved into the
+            // engine's `postWire` (capability-gated on `action` / `read`). Here we
+            // build the empty registries; `postWire` installs the page wrappers before
+            // the session is handed to a tool call (byte-identical eager-install timing).
+            wsInteractive: new WsInteractiveRegistry(),
+            workers: new WorkersRegistry(),
+            regions: new RegionRegistry(),
+            emulation: new EmulationRegistry(),
+            clock: new ClockRegistry(),
+            seededRandom: new SeededRandomRegistry(),
+            perf: new PerfTracingState(),
+            coverage: new CoverageTrackerState(),
+            wedge: new WedgeTracker(),
+            metrics: new SessionMetrics(),
+            dialog: dialogState,
+            permission: permissionState,
+            notification: notificationState,
+            fsPicker: fsPickerState,
+            deviceEmulation,
+            webDeviceEmulation,
+            har: harState,
+            video: videoState,
+            secrets: secretsReg,
+            extensions: newExtensionRegistry(),
+            downloads: downloadsReg,
+            artifacts: artifactsReg,
+            ...(mode === "persistent" ? { launchProfile: spec?.profile ?? id } : {}),
+            openedAt: Date.now(),
+            lastActivityAt: Date.now(),
+        };
+        // Post-creation wiring — the engine owns its own bookkeeping (RFC 0004 D1).
+        // The four Playwright engines attach the full console/bridge/policy/download/
+        // stealth/device-emulation/ws-interactive/workers set + await it; safari
+        // attaches only its BiDi console bridge; a no-Page engine attaches nothing.
+        // This is the one call the 17 scattered `!== "safari"` guards collapsed into.
+        // The per-server deps are passed explicitly (never a module-global) so a
+        // second server in this process can never wire THIS session with its caps or
+        // sandbox root.
+        await engineEntry(sess.engine).postWire(entry, serverPostWireDeps);
+        return entry;
+    }, async (e) => {
+        // Stop any in-flight perf trace BEFORE closing CDP — otherwise the
+        // attached Chrome (BYOB) keeps the trace buffer pinned. Best-effort:
+        // a stuck Tracing.end won't block teardown (perf state bounds the wait).
+        // Keyed on the Playwright-Page capability (`!e.session.safari`), not an
+        // engine-name branch — Safari has no CDP, so `requireCdp` would refuse.
+        const teardownHasCdp = !e.session.safari;
+        if (teardownHasCdp)
+            await e.perf.closeIfRunning(requireCdp(e.session)).catch(() => undefined);
+        // also release any in-flight Profiler/CSS coverage on
+        // the attached target so a BYOB Chrome doesn't keep coverage state
+        // pinned past detach.
+        if (teardownHasCdp)
+            await e.coverage.closeIfRunning(requireCdp(e.session)).catch(() => undefined);
+        // workers registry CDP listeners. Detach before CDP closes
+        // so we don't race the parent session shutdown.
+        try {
+            e.workers.dispose();
+        }
+        catch {
+            /* best-effort */
+        }
+        await e.bridge.detach().catch(() => undefined);
+        // Capture page reference BEFORE close — `page.video()` resolves the
+        // Video handle, but the actual .webm is only flushed by the underlying
+        // context.close() that `e.session.close()` triggers. `video.saveAs()`
+        // (called inside finalizeVideoOnClose) blocks until the page is closed
+        // AND the recording is fully written, so the order is: grab page →
+        // close context → saveAs to deterministic target path.
+        const videoPage = e.video.active ? e.session.page() : undefined;
+        await e.session.close().catch(() => undefined);
+        if (videoPage) {
+            await finalizeVideoOnClose(videoPage, e.video).catch(() => undefined);
+        }
+        // Clear session-scoped artifacts on teardown. Best-effort: a stuck
+        // rm won't block teardown. Sessions that never wrote an artifact
+        // never create the dir, so this is a no-op for them.
+        try {
+            e.artifacts.clear();
+        }
+        catch {
+            /* best-effort */
+        }
+    });
+}