browxai 0.7.0

package/dist/session/extensions.js

@@ -0,0 +1,237 @@
+// Per-session Chrome extension management (capability `extensions`).
+//
+// Chrome extensions in Playwright/Chromium are a LAUNCH-TIME concern: they
+// only attach to a context that was started with `--load-extension=<paths>`
+// (and `--disable-extensions-except=<paths>` to keep the rest of the user's
+// extensions off in a managed profile). There is no Playwright API to add /
+// remove an extension on a live context.
+//
+// Consequences this module's contract makes load-bearing:
+//
+//   1. Headed-only. Chromium has historically required a head for extensions;
+//      `--headless=new` improved coverage but service-worker MV3 backgrounds
+//      remain fragile. We refuse install on a session whose context was
+//      launched with `headless:true`.
+//
+//   2. Persistent (managed) sessions only. Incognito mode does not load
+//      extensions in Chromium (they require an "allowed in incognito"
+//      per-extension flag that the Playwright launch API cannot toggle), and
+//      attached/BYOB sessions are not-owned (the human's Chrome already has
+//      its own extension set; we don't mutate it).
+//
+//   3. install/reload/uninstall mutate the session's extension list and then
+//      REBUILD the underlying browser context. This is a destructive
+//      operation: the page navigates to about:blank, open refs invalidate,
+//      console/network buffers reset. Profile state on disk (cookies,
+//      localStorage, IndexedDB) survives — it lives in the profile dir.
+//      Callers must treat install/reload/uninstall as "session restart with
+//      new extension set", not as Playwright-style hot reload.
+//
+//   4. `trigger` invokes an extension's keyboard command or browser-action
+//      popup via the Chrome DevTools Protocol. Best-effort — many extensions
+//      lack a browser-action surface, and command bindings are
+//      keyboard-shortcut-only on the user's profile.
+//
+// The 5 tool primitives live in src/server.ts; this module supplies the pure
+// helpers (manifest parsing, registry mutation, launch-arg construction) and
+// the rebuild seam.
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, resolve, sep } from "node:path";
+export function newExtensionRegistry() {
+    return { loaded: [] };
+}
+/**
+ * Resolve a caller-supplied `path` to an absolute workspace-rooted directory
+ * containing an MV3 (or MV2) manifest. Rejects:
+ *   - empty / whitespace
+ *   - traversal segments (`..`) that escape the workspace
+ *   - absolute paths pointing outside the workspace
+ *   - non-existent paths
+ *   - paths that are files (not a directory)
+ *   - directories missing `manifest.json`
+ *
+ * Returns the resolved absolute path. Throws `Error` with a structured message
+ * on any rejection — the tool handler converts that to the `ok:false` envelope.
+ */
+export function resolveExtensionPath(workspaceRoot, p, tool) {
+    const raw = (p ?? "").trim();
+    if (!raw) {
+        throw new Error(`${tool}: \`path\` is required (workspace-rooted directory containing manifest.json)`);
+    }
+    // Resolve under the workspace root. An absolute path outside the workspace
+    // is detected by the post-resolve prefix check below — `resolve()` on an
+    // absolute path ignores the workspace base, so we don't need a separate
+    // branch for it.
+    const resolved = isAbsolute(raw) ? resolve(raw) : resolve(workspaceRoot, raw);
+    if (resolved !== workspaceRoot && !resolved.startsWith(workspaceRoot + sep)) {
+        throw new Error(`${tool}: \`path\` must resolve inside $BROWX_WORKSPACE — got "${p}" (resolved to "${resolved}"). ` +
+            `Stage the unpacked extension directory under the workspace.`);
+    }
+    if (!existsSync(resolved)) {
+        throw new Error(`${tool}: extension directory not found at "${resolved}"`);
+    }
+    let st;
+    try {
+        st = statSync(resolved);
+    }
+    catch (err) {
+        throw new Error(`${tool}: cannot stat "${resolved}" (${err instanceof Error ? err.message : String(err)})`);
+    }
+    if (!st.isDirectory()) {
+        throw new Error(`${tool}: "${resolved}" is not a directory. Unpacked extensions are directories containing manifest.json (a .crx file must be unpacked first).`);
+    }
+    if (!existsSync(join(resolved, "manifest.json"))) {
+        throw new Error(`${tool}: no manifest.json found in "${resolved}". Pass the unpacked extension directory, not a parent.`);
+    }
+    return resolved;
+}
+export function readManifest(extPath, tool) {
+    const manifestPath = join(extPath, "manifest.json");
+    let raw;
+    try {
+        raw = readFileSync(manifestPath, "utf8");
+    }
+    catch (err) {
+        throw new Error(`${tool}: cannot read manifest.json at "${manifestPath}" (${err instanceof Error ? err.message : String(err)})`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`${tool}: manifest.json at "${manifestPath}" is not valid JSON (${err instanceof Error ? err.message : String(err)})`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`${tool}: manifest.json at "${manifestPath}" must be a JSON object`);
+    }
+    const obj = parsed;
+    const name = typeof obj.name === "string" ? obj.name : "(unnamed)";
+    const version = typeof obj.version === "string" ? obj.version : "0.0.0";
+    const mv = typeof obj.manifest_version === "number" ? obj.manifest_version : 0;
+    return { name, version, manifestVersion: mv };
+}
+/**
+ * Compute a deterministic, stable id for an unpacked extension keyed off its
+ * absolute path. Chrome's real algorithm hashes the path with SHA-256 and
+ * maps the first 16 bytes onto the alphabet `a-p` (32 chars). We approximate
+ * with a 32-char alpha hash that's deterministic across runs given the same
+ * path; the *exact* Chrome id is not required for our use cases (list /
+ * reload / uninstall / trigger all key off the path or our own id mapping).
+ *
+ * The hash uses Node's built-in `node:crypto` — no extra dep.
+ */
+export function extensionIdFromPath(absPath) {
+    // Avoid importing crypto at the module top; lazy-require keeps the module
+    // tree-shakeable and the helpers cheap to import in tests.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { createHash } = require("node:crypto");
+    const digest = createHash("sha256").update(absPath).digest();
+    const ALPHABET = "abcdefghijklmnop"; // matches Chrome's encoding alphabet
+    let out = "";
+    for (let i = 0; i < 16; i++) {
+        const byte = digest[i] ?? 0;
+        out += ALPHABET[(byte >> 4) & 0x0f];
+        out += ALPHABET[byte & 0x0f];
+    }
+    return out;
+}
+/** Build the Chromium launch arguments for a given set of enabled extensions.
+ *  Empty list → empty args (no extension flags). Returns a frozen array. */
+export function buildLaunchArgs(loaded) {
+    const paths = loaded.filter((e) => e.enabled).map((e) => e.path);
+    if (paths.length === 0)
+        return [];
+    const joined = paths.join(",");
+    return [`--disable-extensions-except=${joined}`, `--load-extension=${joined}`];
+}
+/**
+ * Pure refusal predicate — returns null when the session can host extensions,
+ * else a structured rejection. Mirrors the gate pattern in server.ts but is
+ * pure (testable without launching Chrome).
+ */
+export function refuseIfUnsupported(input) {
+    if (input.mode === "attached") {
+        return {
+            ok: false,
+            error: `${input.tool}: extension management is refused on attached/BYOB sessions`,
+            hint: "The human's Chrome (attached over CDP) already has its own extension set installed by the human. " +
+                "browxai is not-owned on attached sessions — we don't install or uninstall extensions there. " +
+                "Use a managed (persistent) session if you need to drive an extension via browxai.",
+        };
+    }
+    if (input.mode === "incognito") {
+        return {
+            ok: false,
+            error: `${input.tool}: extension management is refused on incognito sessions`,
+            hint: "Chromium does not load unpacked extensions in incognito launches (the per-extension 'allowed in incognito' " +
+                "flag is not togglable from the Playwright launch API). Open a `persistent` (managed) session and install " +
+                "the extension there.",
+        };
+    }
+    if (input.headless) {
+        return {
+            ok: false,
+            error: `${input.tool}: extension management requires a headed session (headless:false)`,
+            hint: "Chromium extension loading via --load-extension is reliable only in headed mode. " +
+                "Set `headless:false` via set_config({scope, patch:{headless:false}}) or BROWX_HEADLESS=0, " +
+                "then open_session a fresh session. The current session's headless flag is fixed at launch.",
+        };
+    }
+    return null;
+}
+/**
+ * In-place mutation helper for the install operation. Pure — given the
+ * current registry and a resolved + parsed install request, returns the new
+ * registry. Throws on duplicate path. The tool layer is responsible for the
+ * rebuild step that materialises the change.
+ */
+export function applyInstall(reg, install, tool) {
+    if (reg.loaded.some((e) => e.path === install.path)) {
+        throw new Error(`${tool}: extension at "${install.path}" is already loaded; call extensions_reload to re-parse its manifest`);
+    }
+    const id = extensionIdFromPath(install.path);
+    if (reg.loaded.some((e) => e.id === id)) {
+        throw new Error(`${tool}: extension id collision for "${install.path}" (id "${id}") — this should not happen; report it.`);
+    }
+    const next = {
+        id,
+        name: install.name,
+        version: install.version,
+        path: install.path,
+        enabled: true,
+    };
+    return { id, loaded: [...reg.loaded, next] };
+}
+/**
+ * Pure helper for uninstall — returns the next loaded list, throws when the
+ * id isn't loaded.
+ */
+export function applyUninstall(reg, id, tool) {
+    const idx = reg.loaded.findIndex((e) => e.id === id);
+    if (idx < 0) {
+        throw new Error(`${tool}: no extension with id "${id}" is loaded in this session (call extensions_list to see ids)`);
+    }
+    const removed = reg.loaded[idx];
+    return { loaded: reg.loaded.filter((_, i) => i !== idx), removed };
+}
+/**
+ * Pure helper for reload — re-parses the manifest at the loaded path and
+ * returns the next loaded list with updated name/version. The browser-context
+ * rebuild is what actually re-injects content scripts; this helper just keeps
+ * the registry consistent.
+ */
+export function applyReload(reg, id, parsed, tool) {
+    const idx = reg.loaded.findIndex((e) => e.id === id);
+    if (idx < 0) {
+        throw new Error(`${tool}: no extension with id "${id}" is loaded in this session`);
+    }
+    const prev = reg.loaded[idx];
+    const next = {
+        ...prev,
+        name: parsed.name,
+        version: parsed.version,
+    };
+    const loaded = reg.loaded.slice();
+    loaded[idx] = next;
+    return { loaded, entry: next };
+}

package/dist/session/fs-picker.d.ts

@@ -0,0 +1,144 @@
+import type { BrowserContext } from "playwright-core";
+export type FsPickerMode = "allow" | "deny" | "raise" | "ask-human";
+/** The three File System Access API entry points browxai governs. v1 set.
+ *  Re-exported in `fs_picker_policy` tool docs + tool-reference.md. */
+export declare const SUPPORTED_FS_PICKER_APIS: readonly ["showOpenFilePicker", "showSaveFilePicker", "showDirectoryPicker"];
+export type FsPickerApi = (typeof SUPPORTED_FS_PICKER_APIS)[number];
+/** Public, runtime-mutable policy shape. Top-level `mode` is the default;
+ *  the per-API map wins when present. */
+export interface FsPickerPolicy {
+    mode: FsPickerMode;
+    perAPI?: Partial<Record<FsPickerApi, FsPickerMode>>;
+}
+/** Agent-supplied file payload for `fs_picker_respond`. Either inline
+ *  `{contents, name}` (base64 bytes the page reads via `getFile()`; for
+ *  save-pickers the page writes nowhere) or a workspace-rooted `{path}`
+ *  (for open-pickers: bytes are read once at respond-time; for save-pickers:
+ *  the destination for `createWritable()`-driven writes; for directory-
+ *  pickers: the dir name surfaces as `.name` and the rest is a stub). */
+export interface FsPickerFile {
+    /** Workspace-rooted file (or dir) path. Mutually exclusive with `contents`. */
+    path?: string;
+    /** base64 file content. Mutually exclusive with `path`. Pass `name` to set
+     *  the filename the page sees. Read-only on the page side (the page can
+     *  call `getFile()` to obtain a `File`; `createWritable()` is a no-op stub). */
+    contents?: string;
+    /** Filename presented to the page when `contents` is used. Default
+     *  `"browxai-virtual"`. Ignored when `path` is used (basename of `path`
+     *  is taken). */
+    name?: string;
+    /** MIME type for the synthetic `File` exposed to the page. Default
+     *  `"application/octet-stream"`. */
+    mimeType?: string;
+}
+/** One captured picker call, exposed on `ActionResult.fsPickerRequests[]`. */
+export interface FsPickerRecord {
+    api: FsPickerApi;
+    /** `suggestedName` from `showSaveFilePicker` options (undefined for open /
+     *  directory). Captured so the agent can see what filename the page
+     *  proposed. */
+    suggestedName?: string;
+    /** What the server actually did. `"raised"` means the stub threw AND
+     *  the policy was `raise`, so the action will be marked failed. */
+    handledAs: "allowed" | "denied" | "raised" | "asked-human";
+    /** epoch ms — used by the action-window slice. */
+    ts: number;
+}
+/** Hint emitted on `ActionResult.failure.hint` when `raise` mode fired.
+ *  Stable, agent-facing string — referenced in docs/tool-reference.md. */
+export declare const UNHANDLED_FS_PICKER_HINT: string;
+/** Mutable per-session state. The page-side stubs read `current(api)` on
+ *  every call, so a `set_fs_picker_policy` call takes effect on the very
+ *  next picker without page reload. */
+export declare class FsPickerPolicyState {
+    private policy;
+    /** Bounded record ring (shared `PolicyRecordBuffer` — the hard cap so a chatty
+     *  page can't grow this without bound; the per-action slice is the only
+     *  consumer, older records are noise). */
+    private readonly records;
+    /** Per-API response queue. `fs_picker_respond` pushes; the binding
+     *  dequeues on the next matching picker call. Per-API so a queued
+     *  open-file response doesn't satisfy a save-file picker (different
+     *  semantics, different agent intent). */
+    private responses;
+    /** Contexts we've already installed the init-script + binding on.
+     *  Idempotent install guard — BYOB reconnect / context rebuild MUST not
+     *  double-wire. */
+    private wired;
+    constructor(initial?: FsPickerPolicy, cap?: number);
+    /** Resolved policy snapshot. */
+    current(): FsPickerPolicy;
+    /** Effective mode for one API — per-API map wins, else top-level. */
+    modeFor(api: FsPickerApi): FsPickerMode;
+    set(next: FsPickerPolicy): FsPickerPolicy;
+    /** Append a request record. Caps the buffer at `cap`. */
+    record(rec: FsPickerRecord): void;
+    /** Slice records with `ts >= since`. Used by the action-window. */
+    since(since: number): FsPickerRecord[];
+    /** True if any record in `[since, now]` was handled in `raise` mode.
+     *  When true, the action-window flips the result to `ok:false`. */
+    raisedSince(since: number): boolean;
+    /** Queue an agent-supplied response for the next picker of `api`.
+     *  Pushed by `fs_picker_respond`; consumed by the binding on the next
+     *  matching call. */
+    pushResponse(api: FsPickerApi, files: FsPickerFile[]): void;
+    /** Dequeue the next agent-supplied response for `api`. Returns
+     *  `undefined` when the queue is empty (the binding falls back to a
+     *  best-effort empty file list so the page still gets a usable
+     *  shape — not deadlocking is the contract). */
+    dequeueResponse(api: FsPickerApi): FsPickerFile[] | undefined;
+    /** Has this context already been wired? Idempotent install guard. */
+    hasContext(c: BrowserContext): boolean;
+    /** Mark a context as wired. */
+    markContext(c: BrowserContext): void;
+}
+/** Parse the spec's compact string form for the top-level mode, or accept
+ *  the object form. Idempotent. */
+export declare function parseFsPickerPolicyArg(v: string | FsPickerPolicy | undefined): FsPickerPolicy;
+/** Resolve + validate a workspace-rooted file path. Mirrors the workspace-
+ *  escape rejection in `src/page/upload.ts`. Exported for tests; used by
+ *  the binding install + by `fs_picker_respond`. */
+export declare function resolveWorkspaceFsPath(workspaceRoot: string, path: string): string;
+/** Bridge callback type for `ask-human` mode. The server-side binding wires
+ *  this to await-human; the page-side stub consults it before deciding
+ *  whether to call through. Returns either the agent-supplied file list (the
+ *  human approved + the agent staged a response) or `null` (denied). */
+export type FsPickerAskHandler = (api: FsPickerApi, suggestedName: string | undefined) => Promise<FsPickerFile[] | null>;
+/** Init script that replaces the page-side File System Access entry points
+ *  with stubs that route through the per-session policy. Stringified so it
+ *  can be passed to `addInitScript` and `page.evaluate`. Keep browser-only
+ *  JS — no TS-only syntax. Re-injected on `framenavigated` (idempotent:
+ *  guards on `window.__browx_fs_picker_installed`).
+ *
+ *  The stubs consult `window.__browx_fs_picker_check({api, suggestedName})`
+ *  (an exposeBinding callable from page context) — it returns one of:
+ *    - `{decision:"allow", files:[{handleId, name, mimeType, contents?}]}`:
+ *      the agent staged file(s); the stub builds synthetic
+ *      `FileSystemFileHandle` / `FileSystemDirectoryHandle` objects whose
+ *      `getFile()` returns a synthetic `File` and `createWritable()` returns
+ *      a synthetic writable stream routed through
+ *      `__browx_fs_picker_write({handleId, op, data?})`.
+ *    - `{decision:"deny"}`: the stub throws `NotAllowedError`.
+ *
+ *  Stubs are written to be browser-only JS (no TS-only syntax). The
+ *  install guards on `window.__browx_fs_picker_installed`. */
+export declare const FS_PICKER_PAGE_SCRIPT = "(() => {\n  if (window.__browx_fs_picker_installed) return;\n  window.__browx_fs_picker_installed = true;\n\n  function check(api, suggestedName) {\n    try {\n      if (typeof window.__browx_fs_picker_check === \"function\") {\n        return Promise.resolve(window.__browx_fs_picker_check(JSON.stringify({\n          api: api, suggestedName: suggestedName,\n        })));\n      }\n    } catch (_) {}\n    // Binding missing \u2014 safe-by-default deny so the page never deadlocks.\n    return Promise.resolve(JSON.stringify({ decision: \"deny\" }));\n  }\n\n  function notAllowed(msg) {\n    var e = new Error(msg || \"The user aborted a request.\");\n    try { e.name = \"NotAllowedError\"; } catch (_) {}\n    return e;\n  }\n\n  function b64ToBytes(b64) {\n    try {\n      var binary = atob(b64);\n      var len = binary.length;\n      var bytes = new Uint8Array(len);\n      for (var i = 0; i < len; i++) bytes[i] = binary.charCodeAt(i);\n      return bytes;\n    } catch (_) {\n      return new Uint8Array(0);\n    }\n  }\n\n  function syntheticFile(spec) {\n    var name = spec.name || \"browxai-virtual\";\n    var mimeType = spec.mimeType || \"application/octet-stream\";\n    var bytes = spec.contents ? b64ToBytes(spec.contents) : new Uint8Array(0);\n    try {\n      return new File([bytes], name, { type: mimeType });\n    } catch (_) {\n      // Fallback Blob-shaped object for environments without File (test\n      // pages); the constructor is universally available on real browsers.\n      var blob = new Blob([bytes], { type: mimeType });\n      blob.name = name;\n      return blob;\n    }\n  }\n\n  function syntheticWritable(handleId) {\n    // Route every operation through the server-side binding. Each call is\n    // ack'd by the binding so we surface back-pressure to a determined page\n    // (await stream.write(buf) resolves only after the write hit disk).\n    function call(op, data) {\n      try {\n        if (typeof window.__browx_fs_picker_write === \"function\") {\n          return Promise.resolve(window.__browx_fs_picker_write(JSON.stringify({\n            handleId: handleId, op: op, data: data == null ? null : data,\n          })));\n        }\n      } catch (_) {}\n      return Promise.resolve(undefined);\n    }\n    return {\n      write: function (data) {\n        // Accept BufferSource | Blob | string | { type:\"write\"|\"seek\"|\"truncate\", \u2026 }\n        if (data == null) return Promise.resolve(undefined);\n        if (typeof data === \"string\") return call(\"write\", data);\n        if (data.type === \"seek\") return call(\"seek\", String(data.position || 0));\n        if (data.type === \"truncate\") return call(\"truncate\", String(data.size || 0));\n        if (data.type === \"write\" && data.data != null) return call(\"write\", encodeForBinding(data.data));\n        return call(\"write\", encodeForBinding(data));\n      },\n      seek: function (position) { return call(\"seek\", String(position || 0)); },\n      truncate: function (size) { return call(\"truncate\", String(size || 0)); },\n      close: function () { return call(\"close\"); },\n      abort: function () { return call(\"abort\"); },\n    };\n  }\n\n  function encodeForBinding(data) {\n    // base64-encode any BufferSource / Blob / string for binding transport.\n    // exposeBinding payloads are strings; we wrap as \"b64:<base64>\" so the\n    // server side can distinguish from a literal text write.\n    function bytesToB64(bytes) {\n      var s = \"\";\n      for (var i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]);\n      try { return \"b64:\" + btoa(s); } catch (_) { return \"b64:\"; }\n    }\n    if (typeof data === \"string\") return data;\n    if (data instanceof ArrayBuffer) return bytesToB64(new Uint8Array(data));\n    if (ArrayBuffer.isView && ArrayBuffer.isView(data)) {\n      return bytesToB64(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));\n    }\n    if (data instanceof Blob) {\n      // Synchronous-from-page Promise; the binding awaits.\n      return data.arrayBuffer().then(function (ab) { return bytesToB64(new Uint8Array(ab)); });\n    }\n    return String(data);\n  }\n\n  function syntheticFileHandle(spec) {\n    var handleId = spec.handleId;\n    var name = spec.name || \"browxai-virtual\";\n    return {\n      kind: \"file\",\n      name: name,\n      getFile: function () { return Promise.resolve(syntheticFile(spec)); },\n      createWritable: function () { return Promise.resolve(syntheticWritable(handleId)); },\n      // Minimal queryPermission / requestPermission \u2014 the page often probes\n      // before reading. Always \"granted\" for our virtual handles.\n      queryPermission: function () { return Promise.resolve(\"granted\"); },\n      requestPermission: function () { return Promise.resolve(\"granted\"); },\n      // Comparison helper expected by some libraries.\n      isSameEntry: function (other) { return Promise.resolve(other === this); },\n    };\n  }\n\n  function syntheticDirectoryHandle(spec) {\n    var name = spec.name || \"browxai-virtual\";\n    // MVP scope: empty directory. Most editors will fall back to per-file\n    // pickers when iteration yields nothing.\n    var empty = {\n      next: function () { return Promise.resolve({ value: undefined, done: true }); },\n      return: function () { return Promise.resolve({ value: undefined, done: true }); },\n    };\n    var emptyIter = { __asyncIterator__: true };\n    emptyIter[Symbol.asyncIterator] = function () { return empty; };\n    return {\n      kind: \"directory\",\n      name: name,\n      entries: function () { return emptyIter; },\n      values: function () { return emptyIter; },\n      keys: function () { return emptyIter; },\n      getFileHandle: function () { return Promise.reject(notAllowed(\"Not found in virtual directory\")); },\n      getDirectoryHandle: function () { return Promise.reject(notAllowed(\"Not found in virtual directory\")); },\n      removeEntry: function () { return Promise.resolve(undefined); },\n      resolve: function () { return Promise.resolve(null); },\n      queryPermission: function () { return Promise.resolve(\"granted\"); },\n      requestPermission: function () { return Promise.resolve(\"granted\"); },\n      isSameEntry: function (other) { return Promise.resolve(other === this); },\n      [Symbol.asyncIterator]: function () { return empty; },\n    };\n  }\n\n  function installStub(apiName, isDirectory, isMulti) {\n    Object.defineProperty(window, apiName, {\n      configurable: true,\n      writable: true,\n      value: function (options) {\n        var suggestedName = options && options.suggestedName ? String(options.suggestedName) : undefined;\n        return check(apiName, suggestedName).then(function (raw) {\n          var resp;\n          try { resp = typeof raw === \"string\" ? JSON.parse(raw) : (raw || {}); } catch (_) { resp = { decision: \"deny\" }; }\n          if (resp.decision !== \"allow\") {\n            throw notAllowed(\"The user aborted a \" + apiName + \" request.\");\n          }\n          var files = Array.isArray(resp.files) ? resp.files : [];\n          if (isDirectory) {\n            var dirSpec = files[0] || { handleId: resp.handleIdFallback || \"dir-0\", name: \"browxai-virtual\" };\n            return syntheticDirectoryHandle(dirSpec);\n          }\n          if (isMulti) {\n            return files.map(function (f) { return syntheticFileHandle(f); });\n          }\n          var spec = files[0] || { handleId: resp.handleIdFallback || \"file-0\", name: \"browxai-virtual\" };\n          return syntheticFileHandle(spec);\n        });\n      },\n    });\n  }\n\n  // showOpenFilePicker: returns Array<FileSystemFileHandle> (multi by default).\n  installStub(\"showOpenFilePicker\", false, true);\n  // showSaveFilePicker: returns FileSystemFileHandle (single).\n  installStub(\"showSaveFilePicker\", false, false);\n  // showDirectoryPicker: returns FileSystemDirectoryHandle (single).\n  installStub(\"showDirectoryPicker\", true, false);\n})();";
+/** Server-side wire-up. Installs:
+ *   - `__browx_fs_picker_check` exposeBinding: synchronous-from-page consult
+ *     that records the request, dequeues an agent-staged response when the
+ *     policy is `allow` (or routes ask-human via `askHandler`), and returns
+ *     `{decision, files?}`. Files carry a `handleId` the page-side stub
+ *     uses to route subsequent `createWritable()` ops back to the right
+ *     target.
+ *   - `__browx_fs_picker_write` exposeBinding: target of every
+ *     `createWritable()`-driven write. Writes append-mode to the
+ *     workspace-rooted path the agent supplied. `close` / `abort` clean
+ *     up the per-handle target.
+ *   - The page-side init script (see above), re-injected by Playwright on
+ *     every new document.
+ *
+ * Idempotent on the same context. Errors during install are logged and
+ * swallowed — the page-side stub falls back to safe-by-default deny when
+ * the binding is missing, so the page still doesn't deadlock.
+ */
+export declare function attachFsPickerPolicy(context: BrowserContext, state: FsPickerPolicyState, workspaceRoot: string, askHandler: FsPickerAskHandler): Promise<void>;