browxai 0.7.0

package/dist/server.js

@@ -0,0 +1,327 @@
+// MCP server wiring. Tools are registered here; their implementations live in
+// page/* and helper/*. stdout is the MCP channel — all logging goes via util/logging.ts.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { resolveCredentialsProvider } from "./util/credentials.js";
+import { resolveConfig } from "./util/config.js";
+import { resolveWorkspace } from "./util/workspace.js";
+import { DiagnosticsRecorder, ensureDiagnosticsRoot, resolveRetentionDays, sweepRetention, } from "./util/diagnostics.js";
+import { ConfigStore, resolvedToEnv } from "./util/config-store.js";
+import { resolveCapabilities, resolveConfirmHooks } from "./util/capabilities.js";
+import { resolveOriginPolicy, describePolicy } from "./policy/origin.js";
+import { ApprovalStore } from "./policy/confirm.js";
+import { log } from "./util/logging.js";
+import { PACKAGE_VERSION } from "./util/version.js";
+import { buildHost } from "./tools/host-build.js";
+import { registerActionTools } from "./tools/action-tools.js";
+import { registerReadObserveDomTools } from "./tools/read-observe-dom-tools.js";
+import { registerReadObserveExtractTools } from "./tools/read-observe-extract-tools.js";
+import { registerReadObserveVerifyTools } from "./tools/read-observe-verify-tools.js";
+import { registerReadObserveCaptureTools } from "./tools/read-observe-capture-tools.js";
+import { registerReadObserveBufferTools } from "./tools/read-observe-buffer-tools.js";
+import { registerGestureNetworkTools } from "./tools/gesture-network-tools.js";
+import { registerDeepPerfTools } from "./tools/deep-perf-tools.js";
+import { registerDeepCoverageTools } from "./tools/deep-coverage-tools.js";
+import { registerDeepDeterminismTools } from "./tools/deep-determinism-tools.js";
+import { registerCaptureReportMarksTools } from "./tools/capture-report-marks-tools.js";
+import { registerCaptureReportDiagnosticsTools } from "./tools/capture-report-diagnostics-tools.js";
+import { registerCaptureReportUploadTools } from "./tools/capture-report-upload-tools.js";
+import { registerCaptureReportExportTools } from "./tools/capture-report-export-tools.js";
+import { registerCaptureReportElementExportTools } from "./tools/capture-report-element-export-tools.js";
+import { registerCanvasTools } from "./tools/canvas-tools.js";
+import { registerStorageTools } from "./tools/storage-tools.js";
+import { registerFormsRecordingTools } from "./tools/forms-recording-tools.js";
+import { registerSessionPolicyTools } from "./tools/session-policy-tools.js";
+import { registerDeviceEmulationTools } from "./tools/device-emulation-tools.js";
+import { registerLiveEmulationTools } from "./tools/live-emulation-tools.js";
+import { registerConfigApprovalTools } from "./tools/config-approval-tools.js";
+import { registerSecretsCaptchaTools } from "./tools/secrets-captcha-tools.js";
+import { registerInputTools } from "./tools/input-tools.js";
+import { registerExtensionsBatchTools } from "./tools/extensions-batch-tools.js";
+import { wirePluginRuntime } from "./tools/plugin-runtime.js";
+import { buildSessionRegistry } from "./tools/session-registry.js";
+// RFC 0004 P2 / D1 (SECURITY-CRITICAL): importing the tool-metadata bootstrap is a
+// side effect that EAGERLY populates the derived `TOOL_CAPABILITY` / `DEEP_TOOLS`
+// maps. `createServer` calls `resolveCapabilities` BEFORE its own tool
+// registrations run; this import guarantees the maps are already populated at that
+// point (and that the gate's fail-safe never trips for a server-built process),
+// independent of whether the consumer reached us via the package entry.
+import "./tools/tool-metadata.js";
+// Shared input-schema fragments live in a leaf module so the per-family tool
+// modules and this composition root depend on them without an import cycle.
+import { SESSION_ARG, TIMEOUT_ARG, ACTION_OPTS, REF_OR_SELECTOR } from "./tools/schemas.js";
+export const NAME = "browxai";
+// Derived from package.json — see src/util/version.ts. Never hand-bump.
+export const VERSION = PACKAGE_VERSION;
+// Re-exported (imported at the top with the other tool modules) to preserve the
+// existing public surface — the definitions now live in `tools/schemas`.
+export { SESSION_ARG, TIMEOUT_ARG, ACTION_OPTS, REF_OR_SELECTOR };
+/** structured one-liner alongside an element screenshot. Skips
+ *  vision-reading when the agent only needs to confirm "yes the button is there." */
+async function describeTarget(loc, refs, target) {
+    const bits = [];
+    let inputs;
+    if ("ref" in target && target.ref) {
+        inputs = refs.locatorOf(target.ref);
+        if (inputs) {
+            bits.push(inputs.role);
+            if (inputs.name)
+                bits.push(`"${inputs.name}"`);
+            if (inputs.testId)
+                bits.push(`[${inputs.testIdAttr ?? "data-testid"}="${inputs.testId}"]`);
+        }
+        else {
+            bits.push(`ref=${target.ref}`);
+        }
+    }
+    else if ("selector" in target && target.selector) {
+        bits.push(`selector=${target.selector}`);
+    }
+    else if ("coords" in target && target.coords) {
+        bits.push(`coords=${target.coords.x},${target.coords.y}`);
+        return bits.join(" "); // no Locator to probe further for coords targets
+    }
+    try {
+        const box = await loc.boundingBox();
+        if (box)
+            bits.push(`bbox=${Math.round(box.x)},${Math.round(box.y)} ${Math.round(box.width)}×${Math.round(box.height)}`);
+        const visible = await loc.isVisible().catch(() => undefined);
+        if (visible === false)
+            bits.push("not-visible");
+        const enabled = await loc.isEnabled().catch(() => undefined);
+        if (enabled === false)
+            bits.push("disabled");
+    }
+    catch {
+        /* skip — fall back to whatever we have */
+    }
+    return bits.join(" ");
+}
+function asTarget(args, toolName, refs) {
+    const provided = [args.ref, args.selector, args.named, args.coords].filter(Boolean).length;
+    if (provided > 1)
+        throw new Error(`${toolName}: pass exactly one of \`ref\` / \`selector\` / \`named\` / \`coords\``);
+    if (args.ref)
+        return { ref: args.ref };
+    if (args.named) {
+        const resolved = refs.refByNameLookup(args.named);
+        if (!resolved)
+            throw new Error(`${toolName}: name "${args.named}" not bound. Call name_ref({name, ref}) first.`);
+        return { ref: resolved };
+    }
+    if (args.selector) {
+        return args.contextRef
+            ? { selector: args.selector, contextRef: args.contextRef }
+            : { selector: args.selector };
+    }
+    if (args.coords)
+        return { coords: args.coords };
+    throw new Error(`${toolName}: requires one of \`ref\` (from find/snapshot), \`selector\`, \`named\`, or \`coords\``);
+}
+export async function createServer(opts = {}) {
+    // config flows through the browxai-managed ConfigStore (precedence
+    // defaults < env(legacy) < user < project < session). The existing env-driven
+    // resolvers consume the *resolved* chain re-expressed as an env shape, so
+    // precedence is centralised in the store without rewriting each resolver.
+    const workspace = resolveWorkspace();
+    const configStore = new ConfigStore(workspace.root);
+    const resolvedConfig = configStore.resolve();
+    const cfgEnv = resolvedToEnv(resolvedConfig);
+    const config = resolveConfig(cfgEnv);
+    // approvals are session-independent policy state — server-level.
+    const approvals = new ApprovalStore();
+    //  policy: capabilities, confirm-required hooks, origin allow/blocklist.
+    const caps = resolveCapabilities(cfgEnv);
+    const confirmHooks = resolveConfirmHooks(cfgEnv);
+    const originPolicy = resolveOriginPolicy(cfgEnv);
+    const isByob = !!opts.attachCdp;
+    log.info("browxai: policy", {
+        capabilities: [...caps.enabled],
+        confirmHooks: [...confirmHooks],
+        origins: describePolicy(originPolicy),
+    });
+    for (const w of caps.warnings)
+        log.warn(`browxai: ${w}`);
+    if (caps.enabled.has("eval"))
+        log.warn("browxai: eval capability is ENABLED — `eval_js` will execute page-side JS. Return values are page-controlled.");
+    if (caps.enabled.has("network-body"))
+        log.warn("browxai: network-body capability is ENABLED — `network_body` returns full response bodies, which can carry PII / auth tokens. Off by default for a reason.");
+    if (caps.enabled.has("secrets"))
+        log.warn("browxai: secrets capability is ENABLED — `register_secret` accepts sensitive values; once a secret is registered the egress masking layer engages on every sink (ActionResult.network, network_read, network_body, ws_read, console_read, snapshot, find). `screenshot` is a partial sink — see docs/tool-reference.md.");
+    // Credentials provider: resolved once at server start. The provider object
+    // is constructed even when the capability is off so per-deployment config
+    // validation (unknown provider name → warn) happens up front. Per-call
+    // failures (missing CLI binary, missing seed, etc.) surface as structured
+    // refusals on the tool result — never crash startup.
+    const credentialsResolved = resolveCredentialsProvider(cfgEnv);
+    for (const w of credentialsResolved.config.warnings)
+        log.warn(`browxai: ${w}`);
+    if (caps.enabled.has("credentials")) {
+        log.warn(`browxai: credentials capability is ENABLED — \`get_totp\` / \`get_credential\` will shell out to the configured "${credentialsResolved.config.provider}" backend per call. NEVER bundled, NEVER auto-installed — the operator supplies the CLI / seeds out-of-band. \`get_credential\` ADDITIONALLY requires the \`secrets\` capability so the looked-up password is auto-registered into the per-session secrets registry under \`<PASSWORD_<account>>\` and masked across every egress sink (without \`secrets\`, the lookup refuses rather than leak cleartext). Same posture class as \`eval\` / \`network-body\` / \`secrets\`. See docs/threat-model.md.`);
+    }
+    if (caps.enabled.has("extensions"))
+        log.warn("browxai: extensions capability is ENABLED — `extensions_install` loads unpacked Chromium extensions into managed (headed, persistent) sessions. Loaded extensions can READ every page the session visits and make ARBITRARY network requests; treat the extension code itself as in-scope trust. Headed + persistent only — incognito / attached sessions refuse. install/reload/uninstall REBUILD the underlying browser context, invalidating refs + console/network buffers (profile state on disk survives). Same posture class as `eval` / `network-body` / `secrets` — see docs/threat-model.md.");
+    if (caps.enabled.has("stealth"))
+        log.warn("browxai: stealth capability is ENABLED — every session's context loads init-script patches that override `navigator.webdriver` / `navigator.plugins` / `navigator.languages` / `window.chrome` to defeat the common Playwright fingerprint surface. CIRCUMVENTING AUTOMATION DETECTION MAY VIOLATE A SITE'S TERMS OF SERVICE; the operator carries the legal exposure. browxai does NOT bundle a full anti-fingerprinting library — only the four well-known patches above. Same posture class as `eval` / `network-body` / `secrets` / `extensions` — see docs/threat-model.md.");
+    if (caps.enabled.has("device-emulation"))
+        log.warn("browxai: device-emulation capability is ENABLED — `emulate_bluetooth` / `emulate_usb` / `emulate_hid` install init-script wrappers around `navigator.bluetooth.requestDevice` / `navigator.usb.requestDevice` / `navigator.hid.requestDevice` so the page resolves with synthetic device objects the agent staged. THE PAGE WILL BELIEVE IT HAS ACCESS TO PHYSICAL DEVICES THAT DON'T EXIST. v1 covers the picker-clear path only — GATT service emulation (Bluetooth), USB transfer endpoints, and HID input/output reports are stubs (resolve with empty/zero-byte results). Same posture class as `eval` / `network-body` / `secrets` / `extensions` / `stealth` / `captcha` — see docs/threat-model.md.");
+    if (caps.enabled.has("canvas"))
+        log.warn("browxai: canvas capability is ENABLED — `canvas_capture` reads framebuffer / 2D ImageData pixel bytes off `<canvas>` elements (subject to the platform's canvas-taint rules for cross-origin sources); `gesture_chain` dispatches multi-step pointer programs (custom paint strokes, lasso paths); `canvas_world_to_screen` / `canvas_screen_to_world` probe common app-side globals heuristically (Figma / Tldraw / Excalidraw shapes) when no explicit transform is supplied — confirm on a known landmark before relying on the result. `canvas_query` dispatches to canvas-app adapter plugins; the inner plugin tool's capability is enforced via the plugin call-graph gate. browxai is BYO-vision — `canvas_capture` is the pixel source, not a vision call; composition with the host agent's own multimodal vision is the loop. Same posture class as `eval` / `network-body` / `secrets` / `extensions` / `device-emulation` / `diagnostics` — see docs/threat-model.md.");
+    if (caps.enabled.has("captcha"))
+        log.warn("browxai: captcha capability is ENABLED — `solve_captcha` will delegate challenges to the provider configured via BROWX_CAPTCHA_PROVIDER + BROWX_CAPTCHA_API_KEY. SOLVING CAPTCHAS MAY VIOLATE THE TARGET SITE'S TERMS OF SERVICE and (depending on jurisdiction) computer-misuse / unauthorised-access law; the operator carries the legal exposure. browxai does NOT bundle a solver and does NOT auto-purchase credits — the operator chooses a provider, funds the account, configures the server. Same posture class as `eval` / `network-body` / `secrets` / `extensions` / `stealth` — see docs/threat-model.md.");
+    // diagnostics recorder. Constructed eagerly so the dispatch
+    // wrapper can reference it; the `enabled` flag is what gates every
+    // actual side-effect. OFF → zero allocations beyond a gate check on
+    // every tool call.
+    const diagnosticsEnabled = caps.enabled.has("diagnostics");
+    const diagRetentionDays = resolveRetentionDays(cfgEnv);
+    if (diagnosticsEnabled) {
+        log.warn("browxai: diagnostics capability is ENABLED — every MCP tool call is " +
+            `recorded as a JSONL line under $BROWX_WORKSPACE/diagnostics/<sessionId>/<ISO>.jsonl ` +
+            `(retention: ${diagRetentionDays} days; configure via BROWX_DIAGNOSTICS_RETENTION_DAYS). ` +
+            "Args are structurally redacted (large/sensitive payload fields → sha256 + byteLength); " +
+            "the recorder runs DOWNSTREAM of the URL sanitiser + secrets-masking egress " +
+            "chokepoint, so registered secret values never reach the store raw. The agent " +
+            "self-feedback tool `diagnostics_note` ALSO requires this capability; read-side " +
+            "queries (`diagnostics_search`, `diagnostics_report`) ride the `read` capability " +
+            "so a report can be pulled even when no further notes are being filed. Same posture " +
+            "class as `eval` / `network-body` / `secrets` / `extensions` / `stealth` / `captcha` / " +
+            "`device-emulation`. See docs/threat-model.md.");
+        // Create the diagnostics root + run the retention sweep up-front so a
+        // long-idle workspace doesn't keep months of stale JSONL.
+        try {
+            ensureDiagnosticsRoot(workspace.root);
+        }
+        catch {
+            /* best-effort */
+        }
+        try {
+            sweepRetention(workspace.root, diagRetentionDays);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    const diagnostics = new DiagnosticsRecorder({
+        enabled: diagnosticsEnabled,
+        workspaceRoot: workspace.root,
+        retentionDays: diagRetentionDays,
+    });
+    if (resolvedConfig.disableWebSecurity)
+        log.warn("browxai: disableWebSecurity is ENABLED — managed/incognito sessions launch with SOP/CORS OFF (--disable-web-security). Use only against test/dev targets.");
+    if (process.env.BROWX_EXTRACT_STRICT === "1")
+        log.warn("browxai: BROWX_EXTRACT_STRICT=1 — extract() unknown-`x-browx-source`-key warnings are PROMOTED to hard `ok:false` invalid-schema rejections (v0.2.2's partialMisses-only behavior is bypassed). The integer→number coerce and array-`selector`-as-`collection` alias are NOT promoted; only typo-like unknown-key diagnostics are.");
+    if (isByob && !caps.enabled.has("byob-attach")) {
+        log.warn("browxai: BROWX_ATTACH_CDP is set but `byob-attach` capability is disabled. Add `byob-attach` to BROWX_CAPABILITIES to use it.");
+    }
+    // per-session state lives in the SessionRegistry. The "default"
+    // session is created lazily on the first browser-touching tool call — so
+    // list_tools / discovery still don't launch a browser, and every existing
+    // caller that omits `session` keeps working unchanged.
+    // The engine every session this server opens runs on. Defaults to chromium;
+    // firefox + webkit + android are also wired (the launch path drives each via
+    // its adapter). A future-declared engine without an adapter is rejected
+    // (engine-not-yet-supported) — there is no silent fallback to chromium.
+    const serverEngine = opts.browserType ?? "chromium";
+    // The server-level launch mode: BYOB when BROWX_ATTACH_CDP is set, else
+    // persistent. android is ATTACH-ONLY (the user's real Chrome-on-Android over
+    // adb + CDP), so it defaults to "attached" with no BROWX_ATTACH_CDP
+    // (the endpoint is DISCOVERED over adb, not configured). This is the default a
+    // lazily-created session inherits; an explicit open_session can override per id.
+    const serverDefaultMode = serverEngine === "android" || opts.attachCdp ? "attached" : "persistent";
+    const registry = buildSessionRegistry({
+        opts,
+        resolvedConfig,
+        configStore,
+        caps,
+        workspace,
+        serverEngine,
+        serverDefaultMode,
+    });
+    const server = new McpServer({ name: NAME, version: VERSION }, { capabilities: { tools: {} } });
+    // Side-table of handler functions, populated as we register each tool. Lets
+    // the `batch` tool dispatch a whitelist of inner calls without going through
+    // the MCP transport. Each handler accepts the inner tool's args and returns
+    // the same `{ content: [...] }` shape an MCP call would. `ToolResponse` is the
+    // shared seam type (src/tools/host.ts) so extracted tool modules and the
+    // composition root agree on the envelope.
+    const toolHandlers = {};
+    // populated AFTER every core tool registration when the plugin
+    // runtime fires. Declared here so `get_config({scope:"resolved"})` can
+    // reference it via closure (registered before plugin loading runs).
+    let pluginRecords = [];
+    // The composition seam: bundle the shared state + helper closures into one
+    // host and hand it to each per-family tool module. createServer stays the
+    // registry composition root; the closures + host literal live in buildHost.
+    const host = buildHost({
+        server,
+        toolHandlers,
+        registry,
+        config,
+        configStore,
+        resolvedConfig,
+        caps,
+        confirmHooks,
+        originPolicy,
+        approvals,
+        isByob,
+        workspace,
+        diagnostics,
+        credentialsResolved,
+        pluginRecords: () => pluginRecords,
+        startOptions: opts,
+        describeTarget,
+        asTarget,
+    });
+    registerReadObserveDomTools(host);
+    registerReadObserveExtractTools(host);
+    registerReadObserveVerifyTools(host);
+    registerReadObserveCaptureTools(host);
+    registerReadObserveBufferTools(host);
+    registerActionTools(host);
+    registerGestureNetworkTools(host);
+    registerDeepPerfTools(host);
+    registerDeepCoverageTools(host);
+    registerDeepDeterminismTools(host);
+    registerCaptureReportMarksTools(host);
+    registerCaptureReportDiagnosticsTools(host);
+    registerCaptureReportUploadTools(host);
+    registerCaptureReportExportTools(host);
+    registerCaptureReportElementExportTools(host);
+    registerCanvasTools(host);
+    registerStorageTools(host);
+    registerFormsRecordingTools(host);
+    registerSessionPolicyTools(host);
+    registerDeviceEmulationTools(host);
+    registerLiveEmulationTools(host);
+    registerConfigApprovalTools(host);
+    registerSecretsCaptchaTools(host);
+    registerInputTools(host);
+    // The extensions + batch/compound-primitive family registers through the
+    // shared ToolHost seam. It MUST run before the coreToolNames capture below
+    // so its tools count as core (plugin runtime loads last).
+    registerExtensionsBatchTools(host);
+    // Plugin runtime wiring — the LAST registration step, run after every core
+    // `register*Tools(host)` call so the `coreToolNames` snapshot taken inside
+    // counts the full core surface as "core" and plugins load on top of it.
+    // Returns the loaded records; assigning them to the createServer `let`
+    // keeps `get_config` reporting the live enabled-plugin set via the host
+    // getter.
+    pluginRecords = await wirePluginRuntime(host, {
+        server,
+        noteMetrics: host.noteMetrics,
+        noteDiagnostics: host.noteDiagnostics,
+    });
+    return {
+        start: async () => {
+            const transport = new StdioServerTransport();
+            await server.connect(transport);
+            log.info("browxai: MCP server up on stdio");
+        },
+        shutdown: async () => {
+            await registry.closeAll();
+            await server.close().catch(() => undefined);
+        },
+        handlers: toolHandlers,
+    };
+}

package/dist/session/artifacts.d.ts

@@ -0,0 +1,52 @@
+/** Max number of artifacts kept per session. Oldest-write evicted past this. */
+export declare const ARTIFACT_MAX_ENTRIES = 200;
+/** Max total bytes kept per session (50 MiB). Oldest-write evicted to fit. */
+export declare const ARTIFACT_MAX_BYTES: number;
+export type ArtifactEncoding = "utf8" | "base64";
+/** What `artifact_list` returns per entry. */
+export interface ArtifactInfo {
+    name: string;
+    /** size on disk, bytes. */
+    size: number;
+    /** ISO timestamp of last write. */
+    mtime: string;
+}
+/** Per-session artifact registry. One instance per SessionEntry. */
+export declare class ArtifactsRegistry {
+    /** Per-session storage dir: `$BROWX_WORKSPACE/.artifacts/<sessionId>/`. */
+    readonly storageDir: string;
+    constructor(
+    /** Per-session storage dir: `$BROWX_WORKSPACE/.artifacts/<sessionId>/`. */
+    storageDir: string);
+    /** Resolve + workspace-escape-check the on-disk path for a name. The name
+     *  is asserted via `assertSafeName` first (no separators / no `..` — the
+     *  shared validator from storage.ts) PLUS a no-leading-dot guard added
+     *  here so we never write a hidden file into the artifacts dir; the path
+     *  is then re-resolved + checked it stays inside `storageDir` as defence
+     *  in depth. */
+    pathFor(name: string): string;
+    /** Write an artifact. Overwrites an existing entry of the same name.
+     *  Evicts oldest-write entries to stay under the capacity caps. */
+    save(name: string, content: string, encoding?: ArtifactEncoding): ArtifactInfo;
+    /** Read an artifact's bytes back. Throws if the name is unknown or the
+     *  file vanished. */
+    get(name: string, encoding?: ArtifactEncoding): {
+        content: string;
+        size: number;
+        mtime: string;
+        encoding: ArtifactEncoding;
+    };
+    /** Enumerate every artifact in this session (sorted by name asc).
+     *  Read-only; never throws on a single bad entry — skip unreadable. */
+    list(): ArtifactInfo[];
+    /** Best-effort wipe of the entire storage dir. Called on session
+     *  teardown — every artifact written during the session is removed.
+     *  Idempotent; ignores missing-dir. */
+    clear(): void;
+    /** Evict oldest-write entries until both the entry-count and total-byte
+     *  caps are satisfied. Called after every save. */
+    private enforceCaps;
+    /** stat every entry, sorted by mtime ascending (oldest first). */
+    private statsByMtime;
+    private evict;
+}

package/dist/session/artifacts.js

@@ -0,0 +1,177 @@
+// Per-session artifact KV — session-scoped workspace primitives.
+//
+// First-class `save_artifact(name, content)` / `list_artifacts` /
+// `load_artifact(name)` for the "build your own library over time" loop.
+// Before this lane agents were forced to round-trip scripts/files/blobs
+// through `name_ref`/`name_region` — both ref-typed and a poor fit for
+// raw byte/string payloads.
+//
+// Design notes:
+//   - **Per-session.** Each `SessionEntry` owns one registry; entries
+//     don't cross sessions. Storage dir is
+//     `$BROWX_WORKSPACE/.artifacts/<sessionId>/`.
+//   - **Workspace-rooted paths only.** The name is restricted to a safe
+//     character set (no path separators, no leading dots, no `..`) — same
+//     posture as `assertSafeName` in `src/session/storage.ts`. Even with
+//     that, the composed path is re-resolved + workspace-escape-rejected
+//     defensively (defence in depth — `path/posix.join` with the workspace
+//     prefix).
+//   - **Cleared on session close.** Teardown wipes the whole
+//     `<sessionId>/` subdir; sessions that never wrote an artifact leave
+//     no trace.
+//   - **Capacity-bounded.** Max 200 entries AND 50 MiB total. Oldest-write
+//     evicted on overflow (per-name `mtime` ordering — LRU-by-write).
+//   - **Encoding.** `utf8` (default) treats `content` as text; `base64`
+//     decodes binary. Reads return the same encoding the caller wrote
+//     with — round-trip-faithful for both text and binary payloads.
+//   - **Capability split.** `artifact_save` → `action` (writes a file).
+//     `artifact_get` / `artifact_list` → `read`.
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { assertSafeName } from "./storage.js";
+/** Max number of artifacts kept per session. Oldest-write evicted past this. */
+export const ARTIFACT_MAX_ENTRIES = 200;
+/** Max total bytes kept per session (50 MiB). Oldest-write evicted to fit. */
+export const ARTIFACT_MAX_BYTES = 50 * 1024 * 1024;
+/** Per-session artifact registry. One instance per SessionEntry. */
+export class ArtifactsRegistry {
+    storageDir;
+    constructor(
+    /** Per-session storage dir: `$BROWX_WORKSPACE/.artifacts/<sessionId>/`. */
+    storageDir) {
+        this.storageDir = storageDir;
+    }
+    /** Resolve + workspace-escape-check the on-disk path for a name. The name
+     *  is asserted via `assertSafeName` first (no separators / no `..` — the
+     *  shared validator from storage.ts) PLUS a no-leading-dot guard added
+     *  here so we never write a hidden file into the artifacts dir; the path
+     *  is then re-resolved + checked it stays inside `storageDir` as defence
+     *  in depth. */
+    pathFor(name) {
+        assertSafeName("artifact name", name);
+        if (name.startsWith(".")) {
+            throw new Error(`artifact name "${name}" invalid — names cannot start with '.'`);
+        }
+        const target = join(this.storageDir, name);
+        const resolved = resolve(target);
+        const root = resolve(this.storageDir);
+        if (resolved !== root && !resolved.startsWith(root + sep)) {
+            throw new Error(`artifact name "${name}" resolved outside its session storage dir — refusing.`);
+        }
+        return resolved;
+    }
+    /** Write an artifact. Overwrites an existing entry of the same name.
+     *  Evicts oldest-write entries to stay under the capacity caps. */
+    save(name, content, encoding = "utf8") {
+        const dest = this.pathFor(name);
+        // `storageDir` is workspace-rooted by construction — the SessionEntry
+        // factory sets it via `workspace.sub('.artifacts/<id>')` (see server.ts).
+        // `dest` is the asserted-safe-name joined to that storageDir, with the
+        // workspace-escape re-check in `pathFor`.
+        if (!existsSync(this.storageDir))
+            mkdirSync(this.storageDir, { recursive: true });
+        const buf = encoding === "base64" ? Buffer.from(content, "base64") : Buffer.from(content, "utf8");
+        // workspace.sub-rooted by construction (see comment above).
+        writeFileSync(dest, buf);
+        this.enforceCaps();
+        const st = statSync(dest);
+        return { name, size: st.size, mtime: new Date(st.mtimeMs).toISOString() };
+    }
+    /** Read an artifact's bytes back. Throws if the name is unknown or the
+     *  file vanished. */
+    get(name, encoding = "utf8") {
+        const dest = this.pathFor(name);
+        if (!existsSync(dest)) {
+            throw new Error(`artifact_get: no artifact "${name}" in this session — call artifact_save({ name, content }) first.`);
+        }
+        const buf = readFileSync(dest);
+        const st = statSync(dest);
+        return {
+            content: encoding === "base64" ? buf.toString("base64") : buf.toString("utf8"),
+            size: st.size,
+            mtime: new Date(st.mtimeMs).toISOString(),
+            encoding,
+        };
+    }
+    /** Enumerate every artifact in this session (sorted by name asc).
+     *  Read-only; never throws on a single bad entry — skip unreadable. */
+    list() {
+        if (!existsSync(this.storageDir))
+            return [];
+        const out = [];
+        for (const entry of readdirSync(this.storageDir)) {
+            const p = join(this.storageDir, entry);
+            try {
+                const st = statSync(p);
+                if (!st.isFile())
+                    continue;
+                out.push({ name: entry, size: st.size, mtime: new Date(st.mtimeMs).toISOString() });
+            }
+            catch {
+                /* skip unreadable */
+            }
+        }
+        return out.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    /** Best-effort wipe of the entire storage dir. Called on session
+     *  teardown — every artifact written during the session is removed.
+     *  Idempotent; ignores missing-dir. */
+    clear() {
+        try {
+            if (existsSync(this.storageDir))
+                rmSync(this.storageDir, { recursive: true, force: true });
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+    }
+    // ---- capacity enforcement -------------------------------------------------
+    /** Evict oldest-write entries until both the entry-count and total-byte
+     *  caps are satisfied. Called after every save. */
+    enforceCaps() {
+        const entries = this.statsByMtime();
+        // entry-count cap
+        while (entries.length > ARTIFACT_MAX_ENTRIES) {
+            const victim = entries.shift();
+            if (!victim)
+                break;
+            this.evict(victim.path);
+        }
+        // byte cap
+        let totalBytes = entries.reduce((s, e) => s + e.size, 0);
+        while (totalBytes > ARTIFACT_MAX_BYTES) {
+            const victim = entries.shift();
+            if (!victim)
+                break;
+            this.evict(victim.path);
+            totalBytes -= victim.size;
+        }
+    }
+    /** stat every entry, sorted by mtime ascending (oldest first). */
+    statsByMtime() {
+        if (!existsSync(this.storageDir))
+            return [];
+        const out = [];
+        for (const name of readdirSync(this.storageDir)) {
+            const p = join(this.storageDir, name);
+            try {
+                const st = statSync(p);
+                if (!st.isFile())
+                    continue;
+                out.push({ path: p, size: st.size, mtimeMs: st.mtimeMs });
+            }
+            catch {
+                /* skip */
+            }
+        }
+        return out.sort((a, b) => a.mtimeMs - b.mtimeMs);
+    }
+    evict(p) {
+        try {
+            rmSync(p, { force: true });
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}

package/dist/session/byob-attach.d.ts

@@ -0,0 +1,26 @@
+import type { BrowserSession, SessionOptions } from "./types.js";
+/** Android BYOB — discover real Chrome-on-Android over adb + CDP and attach.
+ *  Distinct from the desktop URL-attach path: the endpoint is DISCOVERED
+ *  (adb forward → /json/version → wsUrl), not configured. The forwarded socket is
+ *  loopback by construction (adb forwards to 127.0.0.1), so the same not-owned
+ *  policy applies; close additionally removes the adb forward. Full CDP, so the
+ *  session carries `cdp()` and the substrates pick the CDP path automatically. */
+export declare function openAndroidByobSession(): Promise<BrowserSession>;
+/** Assert the BYOB attach endpoint is present + loopback, returning it as a
+ *  string. The firefox / webkit engine modules call this before surfacing their
+ *  structured attach refusal, preserving the EXACT pre-relocation order (the
+ *  `!attachCdp` throw, then the loopback assertion, then the per-engine refusal).
+ *  Shared so the loopback policy lives in one place. */
+export declare function assertByobAttach(opts: SessionOptions & {
+    attachCdp?: string;
+}): string;
+/** The Chromium CDP-attach (BYOB) lane — the desktop URL-attach path, extracted
+ *  verbatim from the old `openByobSession` chromium body. Asserts the loopback
+ *  endpoint, attaches over CDP, ensures a usable viewport, and builds the
+ *  not-owned `BrowserSession`. The chromium engine module's `makeAdapter` byob
+ *  branch calls this; firefox/webkit/safari surface their own structured attach
+ *  refusals from their own engine modules, and android attaches over adb via
+ *  `openAndroidByobSession` — so no engine-name branch survives here. */
+export declare function attachByobChromium(opts: SessionOptions & {
+    attachCdp?: string;
+}): Promise<BrowserSession>;