browxai 0.7.0

package/dist/tools/extensions-rebuild.js

@@ -0,0 +1,208 @@
+// RFC 0004 P3 / D3 (SRP) — the persistent-session extension context rebuild,
+// extracted verbatim out of `extensions-batch-tools.ts` so each tool module stays
+// under the size budget. Chromium cannot add/remove extensions on a live context,
+// so install/reload/uninstall close the BrowserSession, relaunch with the updated
+// `--load-extension` flags, and splice the new inner pieces onto the existing
+// SessionEntry. The per-server boundary deps (caps / configStore / workspace /
+// launch options) are threaded in EXPLICITLY — never a module-global — preserving
+// the composition root's per-server isolation. Behaviour is byte-identical to the
+// prior in-closure helper; only the dependency wiring is made explicit.
+import { DEFAULT_SESSION_ID } from "../session/registry.js";
+import { openManagedSession } from "../session/managed.js";
+import { resolveDevice } from "../session/device.js";
+import { reapplyAll as reapplyEmulation } from "../session/emulation.js";
+import { attachDialogPolicy } from "../session/dialog.js";
+import { attachPermissionPolicy, applyCdpBaseline as applyPermissionCdpBaseline, } from "../session/permission.js";
+import { attachNotificationPolicy } from "../session/notification.js";
+import { attachFsPickerPolicy } from "../session/fs-picker.js";
+import { attachDeviceEmulation } from "../session/device-emu.js";
+import { RefRegistry } from "../page/refs.js";
+import { snapshotSubstrateFor } from "../page/snapshot-substrate-select.js";
+import { networkSubstrateFor } from "../page/network-substrate-select.js";
+import { WsInteractiveRegistry } from "../page/ws-interactive.js";
+import { WorkersRegistry } from "../page/workers.js";
+import { ConsoleBuffer } from "../page/console.js";
+import { BrowxBridge } from "../helper/bridge.js";
+import { applyOverlayHide } from "../helper/overlay-hide.js";
+import { applyStealth } from "../helper/stealth.js";
+import { requireCdp } from "../engine/index.js";
+import { log } from "../util/logging.js";
+/** Rebuild the persistent session's browser context with the entry's current
+ *  extension list reflected as launch flags. Closes the existing BrowserSession +
+ *  bridge, relaunches via `openManagedSession`, and replaces the entry's inner
+ *  pieces in-place so the registry mapping (sessionId → entry) stays valid. Caller
+ *  MUST have verified the entry is `persistent` and not headless (via the
+ *  extension-refusal check). */
+export async function rebuildPersistentForExtensions(e, deps) {
+    const { caps, configStore, workspace, opts, resolvedConfig } = deps;
+    const headless = opts.headless ?? resolvedConfig.headless;
+    const disableWebSecurity = configStore.resolve().disableWebSecurity === true;
+    const profileName = e.launchProfile ?? e.id;
+    const profileDir = e.id === DEFAULT_SESSION_ID && !e.launchProfile
+        ? workspace.sub("profile")
+        : workspace.sub(`profiles/${profileName}`);
+    const extensionPaths = e.extensions.loaded.filter((x) => x.enabled).map((x) => x.path);
+    // Preserve the engine across the rebuild (extensions are Chromium-only, so
+    // this is chromium today; reading it before close keeps the rebuild engine-
+    // faithful for when a second engine lands).
+    const rebuildEngine = e.session.engine;
+    // Tear down the current session BEFORE relaunching — Chromium will not
+    // open a second persistent context on the same profile dir.
+    await e.bridge.detach().catch(() => undefined);
+    await e.session.close().catch(() => undefined);
+    // Resolve device fresh from the current resolved config (no spec stored
+    // post-creation; the device-emulation state on `e.deviceEmulation` is
+    // re-applied below).
+    const device = resolveDevice({
+        device: resolvedConfig.defaultDevice,
+        viewport: resolvedConfig.defaultViewport,
+    });
+    const sess = await openManagedSession({
+        headless,
+        profileDir,
+        device,
+        disableWebSecurity,
+        browserType: rebuildEngine,
+        ...(extensionPaths.length ? { extensionPaths } : {}),
+    });
+    // Rebuild the per-session inner pieces. The secrets / dialog policy /
+    // device-emulation state survive on the entry (intentional — they are
+    // operator-supplied across rebuilds); buffers and refs are replaced
+    // since they referenced the now-closed CDP session.
+    const consoleBuf = new ConsoleBuffer();
+    consoleBuf.attach(sess.page());
+    // Re-select the network substrate on the rebuilt context (extensions are
+    // chromium-only, so this stays the CDP substrate — but routing through the
+    // selector keeps the rebuild engine-agnostic and the entry's substrate live).
+    const networkSub = networkSubstrateFor(sess);
+    await networkSub.attach();
+    const networkBuf = networkSub.http;
+    const wsBuf = networkSub.ws;
+    consoleBuf.setSecrets(e.secrets);
+    networkSub.setSecrets(e.secrets);
+    const br = new BrowxBridge();
+    await br.attach(sess.page().context());
+    attachDialogPolicy(sess.page().context(), e.dialog);
+    // Re-attach permission policy on the rebuilt context. The state's
+    // wired-contexts WeakSet ensures the new context is treated as fresh
+    // (the old one was torn down), so the binding + init-script install
+    // afresh and the CDP baseline is re-applied.
+    await attachPermissionPolicy(sess.page().context(), e.permission, async (permission, origin) => {
+        log.info(`permission ask-human: ${permission}${origin ? ` (${origin})` : ""} → call __browx.confirm(true|false) in DevTools to respond`);
+        try {
+            const sig = await br.awaitSignal("respond", 300_000);
+            const data = sig.data;
+            if (data && data.kind === "confirm" && data.value === true)
+                return "allow";
+            return "deny";
+        }
+        catch {
+            return "deny";
+        }
+    });
+    await applyPermissionCdpBaseline(sess.page().context(), e.permission).catch(() => undefined);
+    // Re-attach notification-constructor policy on the rebuilt context. The
+    // state's wired-contexts WeakSet ensures the new context is treated as
+    // fresh (the old one was torn down), so the binding + init-script install
+    // afresh and the sync-decision hint is re-seeded.
+    await attachNotificationPolicy(sess.page().context(), e.notification, async (n) => {
+        log.info(`notification ask-human: ${JSON.stringify({ title: n.title, origin: n.origin })} → call __browx.confirm(true|false) in DevTools to respond`);
+        try {
+            const sig = await br.awaitSignal("respond", 300_000);
+            const data = sig.data;
+            if (data && data.kind === "confirm" && data.value === true)
+                return "allow";
+            return "deny";
+        }
+        catch {
+            return "deny";
+        }
+    });
+    // Re-attach fs-picker policy on the rebuilt context. WeakSet inside the
+    // state treats the new context as fresh — binding + init script are
+    // re-installed, write-target handles for the previous context are
+    // garbage-collected with it.
+    await attachFsPickerPolicy(sess.page().context(), e.fsPicker, workspace.root, async (api, suggestedName) => {
+        log.info(`fs-picker ask-human: ${api}${suggestedName ? ` (${suggestedName})` : ""} → call __browx.respond({files:[…]}) in DevTools (or fs_picker_respond) to answer`);
+        try {
+            const sig = await br.awaitSignal("respond", 300_000);
+            const data = sig.data;
+            if (data &&
+                data.kind === "fs_picker_respond" &&
+                Array.isArray(data.value?.files)) {
+                return data.value.files;
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }).catch(() => undefined);
+    await applyOverlayHide(sess.page().context(), configStore.resolve().hideOverlaySelectors);
+    // Re-apply per-context stealth init-script (capability `stealth`) on the
+    // rebuilt context. Stealth must engage on every navigation post-rebuild,
+    // not just on the original launch.
+    if (caps.enabled.has("stealth")) {
+        await applyStealth(sess.page().context()).catch((err) => {
+            log.warn(`stealth: rebuild failed to apply init script — ${err instanceof Error ? err.message : String(err)}`);
+        });
+    }
+    // Re-apply per-primitive device emulation state to the fresh context's
+    // pages (locale/timezone/UA via CDP, geolocation/colour-scheme/reduced-
+    // motion/permissions via Playwright). Best-effort — failures don't
+    // abort the rebuild.
+    try {
+        await reapplyEmulation(sess.page().context(), sess.page(), requireCdp(sess), e.deviceEmulation);
+    }
+    catch {
+        /* best-effort */
+    }
+    // Re-attach Web Bluetooth / WebUSB / WebHID device-emulation wrappers on
+    // the rebuilt context. The state's wired-contexts WeakSet treats the new
+    // context as fresh — binding + init script reinstall, current catalog is
+    // re-served verbatim on the next page-side requestDevice.
+    await attachDeviceEmulation(sess.page().context(), e.webDeviceEmulation).catch(() => undefined);
+    sess
+        .page()
+        .context()
+        .on("page", (newPage) => {
+        (async () => {
+            try {
+                const newCdp = await sess.page().context().newCDPSession(newPage);
+                await reapplyEmulation(sess.page().context(), newPage, newCdp, e.deviceEmulation);
+            }
+            catch {
+                /* best-effort */
+            }
+        })().catch(() => undefined);
+    });
+    // Splice the new pieces onto the existing entry — sessionId still maps
+    // here so every caller holding `entry` keeps working.
+    e.session = sess;
+    e.console = consoleBuf;
+    e.networkSubstrate = networkSub;
+    e.network = networkBuf;
+    e.ws = wsBuf;
+    e.bridge = br;
+    e.refs = new RefRegistry();
+    // The rebuild minted a fresh CDP session on the new context; re-derive the
+    // snapshot substrate so it captures the live handle (extensions are
+    // chromium-only, so this stays the CDP substrate).
+    e.snapshotSubstrate = snapshotSubstrateFor(sess);
+    // Interactive-WS state is page-side; the rebuild destroyed the wrapper
+    // and any active interceptors with it. Discard the server-side mirror
+    // so it doesn't claim live interceptors that no longer exist, then
+    // re-install the wrapper before any nav so the new context's first
+    // page sees the wrapped WebSocket constructor.
+    e.wsInteractive = new WsInteractiveRegistry();
+    if (caps.enabled.has("action")) {
+        await e.wsInteractive.install(sess.page()).catch(() => undefined);
+    }
+    // workers visibility. Rebuild destroyed the page-side wrapper
+    // and any SW attachments; discard the server-side mirror and re-install.
+    e.workers.dispose();
+    e.workers = new WorkersRegistry();
+    if (caps.enabled.has("read")) {
+        await e.workers.installPageWrapper(sess.page()).catch(() => undefined);
+    }
+}

package/dist/tools/extensions-tools.d.ts

@@ -0,0 +1,2 @@
+import type { RegisterHost, GateHost, SessionHost, ConfigHost, ServerServicesHost } from "./host.js";
+export declare function registerExtensionsTools(host: RegisterHost & GateHost & SessionHost & ConfigHost & ServerServicesHost): void;

package/dist/tools/extensions-tools.js

@@ -0,0 +1,331 @@
+import { resolveExtensionPath, readManifest, refuseIfUnsupported as refuseExtensionsIfUnsupported, applyInstall as applyExtensionInstall, applyUninstall as applyExtensionUninstall, applyReload as applyExtensionReload, } from "../session/extensions.js";
+import { estimateTokens } from "../util/tokens.js";
+import { rebuildPersistentForExtensions } from "./extensions-rebuild.js";
+import { SESSION_ARG } from "./schemas.js";
+/**
+ * Chrome-extension management tools: extensions_install / extensions_list /
+ * extensions_reload / extensions_trigger / extensions_uninstall. Off-by-default
+ * `extensions` capability; headed-persistent only. install/reload/uninstall
+ * rebuild the underlying browser context (Chromium can't mutate extensions on a
+ * live context) via the extracted `rebuildPersistentForExtensions`. Split out of
+ * `extensions-batch-tools` by cohesive family (RFC 0004 P3 / D3 SRP); registered
+ * through the shared `ToolHost` seam in the same source order.
+ */
+/** Discover the loaded extensions' Chrome-runtime ids by inspecting the
+ *  context's service-worker (MV3) + background-page (MV2) URLs — both start with
+ *  `chrome-extension://<runtime-id>/`. Best-effort: older Playwright builds may
+ *  not surface every channel; returns the deduped set. */
+function discoverExtensionRuntimeIds(ctx) {
+    const idsFrom = (urls) => urls
+        .map((w) => w.url())
+        .filter((u) => u.startsWith("chrome-extension://"))
+        .map((u) => u.slice("chrome-extension://".length).split("/")[0]);
+    const c = ctx;
+    const swIds = idsFrom(c.serviceWorkers?.() ?? []);
+    const bgIds = idsFrom(c.backgroundPages?.() ?? []);
+    return Array.from(new Set([...swIds, ...bgIds]));
+}
+export function registerExtensionsTools(host) {
+    const { z, register, gateCheck, engineGate, entryFor, caps, workspace, configStore, startOptions: opts, resolvedConfig, } = host;
+    // The per-server boundary deps the context rebuild threads in (was the closure
+    // the in-module helper held). Passed explicitly to the extracted rebuild fn.
+    const rebuildDeps = {
+        caps,
+        configStore,
+        workspace,
+        opts,
+        resolvedConfig,
+    };
+    /** Pure refusal check for the extension tools. Returns a typed early-exit
+     *  envelope when the session is incognito / attached / headless; null when
+     *  the session can host extensions. */
+    const extensionRefusal = (e, tool) => {
+        if (e.mode === "persistent" || e.mode === "incognito" || e.mode === "attached") {
+            const headless = !!(opts.headless ?? resolvedConfig.headless);
+            const r = refuseExtensionsIfUnsupported({ mode: e.mode, headless, tool });
+            if (r) {
+                const body = { ok: false, error: r.error, hint: r.hint };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ ...body, tokensEstimate: estimateTokens(JSON.stringify(body)) }, null, 2),
+                        },
+                    ],
+                };
+            }
+        }
+        return null;
+    };
+    /** Envelope helper for the extension tools. */
+    const extensionEnvelope = (e, extra) => {
+        const body = {
+            ok: true,
+            session: e.id,
+            loaded: e.extensions.loaded.map((x) => ({ ...x })),
+            ...extra,
+        };
+        body.tokensEstimate = estimateTokens(JSON.stringify(body));
+        return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
+    };
+    const extensionErrorEnvelope = (tool, err) => {
+        const body = {
+            ok: false,
+            action: { type: tool },
+            error: err instanceof Error ? err.message : String(err),
+        };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ ...body, tokensEstimate: estimateTokens(JSON.stringify(body)) }, null, 2),
+                },
+            ],
+        };
+    };
+    register("extensions_install", {
+        capability: "extensions",
+        deep: true,
+        description: "Load an unpacked Chromium extension (MV3 or MV2 directory containing `manifest.json`) into the session's managed-profile launch. **Gated behind the off-by-default `extensions` capability** — same posture class as `eval` / `network-body` / `secrets`. Loaded extensions can READ every page the session visits and make ARBITRARY network requests; the extension code itself becomes trust-equivalent to the agent. " +
+            "`path` is workspace-rooted (under $BROWX_WORKSPACE) — traversal / absolute-outside is rejected. Pass the UNPACKED extension directory; `.crx` packed archives must be unpacked first (the directory must contain `manifest.json`). " +
+            "Headed + persistent only — incognito / attached / headless sessions REFUSE with a structured error and hint. **install REBUILDS the underlying browser context** (Chromium doesn't support adding extensions to a live context): the current page navigates to about:blank, refs invalidate, console/network/ws buffers reset. Profile state on disk (cookies, localStorage, IndexedDB) survives. Treat install as a session-restart. " +
+            "Returns `{ok, session, installed:{id,name,version,path}, loaded:[…], note?, tokensEstimate}`. The `id` is a stable hash of the resolved path — pass it back to `extensions_reload` / `extensions_trigger` / `extensions_uninstall`.",
+        inputSchema: {
+            path: z
+                .string()
+                .describe("Workspace-rooted directory of the unpacked extension (must contain `manifest.json`)."),
+            ...SESSION_ARG,
+        },
+    }, async ({ path, session }) => {
+        const g = gateCheck("extensions_install");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        const eg = engineGate("extensions_install", e);
+        if (eg)
+            return eg;
+        const refused = extensionRefusal(e, "extensions_install");
+        if (refused)
+            return refused;
+        let resolved;
+        let manifest;
+        try {
+            resolved = resolveExtensionPath(workspace.root, path, "extensions_install");
+            manifest = readManifest(resolved, "extensions_install");
+        }
+        catch (err) {
+            return extensionErrorEnvelope("extensions_install", err);
+        }
+        let installed;
+        try {
+            const r = applyExtensionInstall(e.extensions, { path: resolved, name: manifest.name, version: manifest.version }, "extensions_install");
+            e.extensions.loaded = r.loaded;
+            installed = e.extensions.loaded.find((x) => x.id === r.id);
+        }
+        catch (err) {
+            return extensionErrorEnvelope("extensions_install", err);
+        }
+        try {
+            await rebuildPersistentForExtensions(e, rebuildDeps);
+        }
+        catch (err) {
+            // rebuild failed — roll back the registry so the next call doesn't
+            // try to re-apply a now-doomed extension list.
+            e.extensions.loaded = e.extensions.loaded.filter((x) => x.id !== installed.id);
+            return extensionErrorEnvelope("extensions_install", err);
+        }
+        return extensionEnvelope(e, {
+            installed: {
+                id: installed.id,
+                name: installed.name,
+                version: installed.version,
+                path: installed.path,
+            },
+            note: "browser context rebuilt — refs / console / network / ws buffers reset; on-disk profile state preserved",
+        });
+    });
+    register("extensions_list", {
+        capability: "extensions",
+        deep: true,
+        description: "List extensions currently loaded for this session. Returns `[{id, name, version, path, enabled}]`. Empty list when no extension is loaded (the default). Gated behind the off-by-default `extensions` capability — disabled sessions return a structured error before reaching this list. Headed + persistent sessions only.",
+        inputSchema: { ...SESSION_ARG },
+    }, async ({ session }) => {
+        const g = gateCheck("extensions_list");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        const eg = engineGate("extensions_list", e);
+        if (eg)
+            return eg;
+        const refused = extensionRefusal(e, "extensions_list");
+        if (refused)
+            return refused;
+        return extensionEnvelope(e, {});
+    });
+    register("extensions_reload", {
+        capability: "extensions",
+        deep: true,
+        description: "Reload an installed extension: re-parse its `manifest.json`, then rebuild the underlying browser context so Chromium re-injects content scripts and restarts the MV3 service worker. Identify the extension by its `id` (from `extensions_install` / `extensions_list`). Same rebuild caveat as install — refs / buffers reset, on-disk profile state survives. Headed + persistent sessions only.",
+        inputSchema: {
+            id: z.string().describe("Extension id returned by extensions_install / extensions_list."),
+            ...SESSION_ARG,
+        },
+    }, async ({ id, session }) => {
+        const g = gateCheck("extensions_reload");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        const eg = engineGate("extensions_reload", e);
+        if (eg)
+            return eg;
+        const refused = extensionRefusal(e, "extensions_reload");
+        if (refused)
+            return refused;
+        const target = e.extensions.loaded.find((x) => x.id === id);
+        if (!target) {
+            return extensionErrorEnvelope("extensions_reload", new Error(`no extension with id "${id}" is loaded in this session (call extensions_list to see ids)`));
+        }
+        let parsed;
+        try {
+            parsed = readManifest(target.path, "extensions_reload");
+        }
+        catch (err) {
+            return extensionErrorEnvelope("extensions_reload", err);
+        }
+        try {
+            const r = applyExtensionReload(e.extensions, id, parsed, "extensions_reload");
+            e.extensions.loaded = r.loaded;
+        }
+        catch (err) {
+            return extensionErrorEnvelope("extensions_reload", err);
+        }
+        try {
+            await rebuildPersistentForExtensions(e, rebuildDeps);
+        }
+        catch (err) {
+            return extensionErrorEnvelope("extensions_reload", err);
+        }
+        const after = e.extensions.loaded.find((x) => x.id === id);
+        return extensionEnvelope(e, {
+            reloaded: after
+                ? { id: after.id, name: after.name, version: after.version, path: after.path }
+                : null,
+            note: "browser context rebuilt — content scripts re-injected; refs / buffers reset",
+        });
+    });
+    register("extensions_trigger", {
+        capability: "extensions",
+        deep: true,
+        description: "Best-effort invoke of an installed extension's surface. With `command`, attempts to fire the keyboard-command binding declared in the extension's manifest (`commands` key). Without `command`, navigates the session's active page to the extension's `chrome-extension://<id>/<default_popup>` URL so the popup renders in-tab and is driveable like any other page. Many extensions lack both surfaces; this tool returns `ok:false` with a clear reason in those cases. Read-only side-effects on the extension itself — it does not mutate the loaded list. Headed + persistent sessions only.\n\n" +
+            "**Note on `id`.** browxai's id (a hash of the path) does NOT necessarily equal the Chrome-runtime id of the loaded extension — Chrome derives its id from the extension's signing key when one is present. For popup-style triggers we attempt to read the active page's `chrome-extension://` runtime id from the context's service workers / background pages; on a mismatch the tool returns a hint pointing at extensions_list and the page's own discovery.",
+        inputSchema: {
+            id: z.string().describe("Extension id returned by extensions_install / extensions_list."),
+            command: z
+                .string()
+                .optional()
+                .describe('Optional manifest `commands` binding name to fire (e.g. "_execute_action"). Omit to open the extension\'s default_popup in the active page.'),
+            ...SESSION_ARG,
+        },
+    }, async ({ id, command, session }) => {
+        const g = gateCheck("extensions_trigger");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        const eg = engineGate("extensions_trigger", e);
+        if (eg)
+            return eg;
+        const refused = extensionRefusal(e, "extensions_trigger");
+        if (refused)
+            return refused;
+        const target = e.extensions.loaded.find((x) => x.id === id);
+        if (!target) {
+            return extensionErrorEnvelope("extensions_trigger", new Error(`no extension with id "${id}" is loaded in this session (call extensions_list to see ids)`));
+        }
+        try {
+            // Resolve the Chrome-runtime id by inspecting the context's
+            // service-worker / background-page URLs. Best-effort — surfaces the
+            // discovered ids so the caller can decide.
+            const runtimeIds = discoverExtensionRuntimeIds(e.session.page().context());
+            // We can't reliably map our path-hash id to the runtime id without
+            // parsing the manifest's `key` field — when there's exactly one loaded
+            // extension AND one runtime id we assume the mapping.
+            const runtimeId = runtimeIds.length === 1 && e.extensions.loaded.length === 1 ? runtimeIds[0] : undefined;
+            if (command) {
+                // Chrome keyboard-command bindings are user-keyboard-only; CDP has
+                // no public surface to dispatch them programmatically. Return a
+                // structured "not supported" rather than silently no-op.
+                return extensionErrorEnvelope("extensions_trigger", new Error(`extensions_trigger: keyboard command "${command}" — Chromium does not expose extension keyboard-command dispatch via CDP / Playwright. ` +
+                    `Workaround: invoke the extension's underlying behaviour via its content-script API or open its popup (call extensions_trigger without \`command\`).`));
+            }
+            if (!runtimeId) {
+                return extensionErrorEnvelope("extensions_trigger", new Error(`extensions_trigger: cannot determine Chrome-runtime extension id for path-hash id "${id}". ` +
+                    `Browxai's id is a hash of the unpacked path and does NOT necessarily equal Chrome's runtime id (Chrome derives that from the manifest \`key\` when present). ` +
+                    `runtimeIdsDetected: ${JSON.stringify(runtimeIds)}; loaded: ${e.extensions.loaded.length}. ` +
+                    `Workaround: navigate the page directly to the extension popup URL once you know the runtime id.`));
+            }
+            // Open the extension's popup (or its background page) in the active
+            // page. The extension serves `chrome-extension://<id>/` from its
+            // manifest's `action.default_popup` / `browser_action.default_popup`.
+            const url = `chrome-extension://${runtimeId}/`;
+            await e.session
+                .page()
+                .goto(url, { waitUntil: "domcontentloaded" })
+                .catch(() => undefined);
+            return extensionEnvelope(e, {
+                triggered: { id, runtimeId, url, command: command ?? null },
+                note: "best-effort: navigated active page to extension root; default_popup discovery depends on the extension's manifest",
+            });
+        }
+        catch (err) {
+            return extensionErrorEnvelope("extensions_trigger", err);
+        }
+    });
+    register("extensions_uninstall", {
+        capability: "extensions",
+        deep: true,
+        description: "Remove an installed extension from the session and rebuild the underlying browser context without it. Same rebuild caveat as install — refs / buffers reset, on-disk profile state survives. Headed + persistent sessions only.",
+        inputSchema: {
+            id: z.string().describe("Extension id returned by extensions_install / extensions_list."),
+            ...SESSION_ARG,
+        },
+    }, async ({ id, session }) => {
+        const g = gateCheck("extensions_uninstall");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        const eg = engineGate("extensions_uninstall", e);
+        if (eg)
+            return eg;
+        const refused = extensionRefusal(e, "extensions_uninstall");
+        if (refused)
+            return refused;
+        let removed;
+        try {
+            const r = applyExtensionUninstall(e.extensions, id, "extensions_uninstall");
+            e.extensions.loaded = r.loaded;
+            removed = r.removed;
+        }
+        catch (err) {
+            return extensionErrorEnvelope("extensions_uninstall", err);
+        }
+        try {
+            await rebuildPersistentForExtensions(e, rebuildDeps);
+        }
+        catch (err) {
+            // rebuild failed after registry mutation — restore the entry so the
+            // agent can retry the operation. The original BrowserSession is
+            // already torn down (we cannot recover it), so the session itself
+            // is in a degraded state; surface that explicitly.
+            return extensionErrorEnvelope("extensions_uninstall", new Error(`(post-rebuild) ${err instanceof Error ? err.message : String(err)} — session "${e.id}" is now in a degraded state; close it and open a fresh one.`));
+        }
+        return extensionEnvelope(e, {
+            uninstalled: {
+                id: removed.id,
+                name: removed.name,
+                version: removed.version,
+                path: removed.path,
+            },
+            note: "browser context rebuilt without this extension — refs / buffers reset",
+        });
+    });
+}

package/dist/tools/forms-fill-tools.d.ts

@@ -0,0 +1,8 @@
+import type { RegisterHost, GateHost, SessionHost, ActionHost, EnvelopeHost, ServerServicesHost } from "./host.js";
+/**
+ * Multi-field form-fill tool: `fill_form`. Compose N field fills (plus an optional
+ * final submit click) into one action window, with atomic pre-resolution. Split
+ * out of `forms-recording-tools` (RFC 0004 P3 / D3 SRP); registered through the
+ * shared `ToolHost` seam in the same source order.
+ */
+export declare function registerFormsFillTools(host: RegisterHost & GateHost & SessionHost & ActionHost & EnvelopeHost & ServerServicesHost): void;

package/dist/tools/forms-fill-tools.js

@@ -0,0 +1,109 @@
+import { confirmByobAction } from "../policy/confirm.js";
+import { fillForm } from "../page/fill-form.js";
+import { ACTION_OPTS } from "./schemas.js";
+/**
+ * Multi-field form-fill tool: `fill_form`. Compose N field fills (plus an optional
+ * final submit click) into one action window, with atomic pre-resolution. Split
+ * out of `forms-recording-tools` (RFC 0004 P3 / D3 SRP); registered through the
+ * shared `ToolHost` seam in the same source order.
+ */
+export function registerFormsFillTools(host) {
+    const { z, register, gateCheck, entryFor, confirmCtxFor, denyContent, actionTimeout, asActionResultText, ctxFor, } = host;
+    // ---------- multi-field form fill (compose fill into one action window) ----------
+    // Per-field target shape — same surface as the single-field tools, minus
+    // `coords` (fill needs a real input element, not a viewport point).
+    const FILL_FORM_FIELD = z.object({
+        ref: z.string().optional().describe("Stable [eN] ref from snapshot()/find()"),
+        selector: z.string().optional().describe("CSS / selectorHint fallback"),
+        named: z.string().optional().describe("Mnemonic name previously bound with name_ref"),
+        contextRef: z.string().optional().describe("Resolve `selector` within the subtree of this ref"),
+        value: z
+            .string()
+            .describe("Value to fill (substring `<NAME>` triggers secrets materialisation when the secrets capability is on)"),
+    });
+    // The optional submit slot accepts the same target shapes (also no coords —
+    // a coord-only submit is fine via a follow-up click, and keeping submit
+    // ref/selector-only matches the recorder's replay model).
+    const FILL_FORM_SUBMIT = z.object({
+        ref: z.string().optional(),
+        selector: z.string().optional(),
+        named: z.string().optional(),
+        contextRef: z.string().optional(),
+    });
+    /** Project a per-field user arg into an `ActionTarget` (the shape
+     *  `fillForm` expects). Mirrors `asTarget` for one field at a time but
+     *  scoped to "no coords" — coords on a form field is rejected upstream. */
+    const fieldArgToTarget = (raw, label, refs) => {
+        const provided = [raw.ref, raw.selector, raw.named].filter(Boolean).length;
+        if (provided === 0)
+            throw new Error(`fill_form: ${label} requires one of \`ref\` / \`selector\` / \`named\``);
+        if (provided > 1)
+            throw new Error(`fill_form: ${label} — pass exactly one of \`ref\` / \`selector\` / \`named\``);
+        if (raw.ref)
+            return { ref: raw.ref };
+        if (raw.named) {
+            const resolved = refs.refByNameLookup(raw.named);
+            if (!resolved)
+                throw new Error(`fill_form: ${label} — name "${raw.named}" not bound. Call name_ref({name, ref}) first.`);
+            return { ref: resolved };
+        }
+        return raw.contextRef
+            ? { selector: raw.selector, contextRef: raw.contextRef }
+            : { selector: raw.selector };
+    };
+    register("fill_form", {
+        capability: "action",
+        batchable: true,
+        description: "Fill N form fields atomically in one action window, with an optional final `submit` click. Replaces the fill/fill/fill/click round-trip pattern with one dispatch — same action-window envelope (navigation/structure/console/network/snapshotDelta) as a single fill, plus an `elements: ElementProbe[]` slot carrying per-field probes in dispatch order. **Atomic pre-resolution**: every field's target (ref/selector/named) is resolved before any DOM write; if any target misses, the call returns `ok:false` with a structured `fieldResolution` block and NO partial fills land. Same posture for the optional `submit` — a missing submit aborts the whole call. **Secrets-masking composes**: a field value like `<SECRET_NAME>` triggers the standard registry substitution at dispatch (capability `secrets`); the recorded descriptor + per-field probe carry the alias, not the real value. Field targets accept `ref`/`selector`/`named` (no `coords` — fill needs a real input element).",
+        inputSchema: {
+            fields: z
+                .array(FILL_FORM_FIELD)
+                .min(1)
+                .describe("Ordered list of {target, value} pairs. Filled sequentially after atomic pre-resolution."),
+            submit: FILL_FORM_SUBMIT.optional().describe("Optional click target dispatched after every field fills. Aborts atomically if its target misses."),
+            ...ACTION_OPTS,
+        },
+    }, async (args) => {
+        const g = gateCheck("fill_form");
+        if (g)
+            return g;
+        const e = await entryFor(args.session);
+        const c = await confirmByobAction("fill_form", confirmCtxFor(e));
+        if (!c.ok)
+            return denyContent("fill_form", c);
+        // Project the schema-validated args into the lower-half's shape. Any
+        // target-shape error here surfaces as a structured "invalid args"
+        // result rather than a thrown handler — agents debugging a malformed
+        // call shouldn't see a stack trace.
+        let mappedFields;
+        let mappedSubmit;
+        try {
+            mappedFields = args.fields.map((f, i) => ({
+                target: fieldArgToTarget(f, `fields[${i}]`, e.refs),
+                value: f.value,
+            }));
+            if (args.submit) {
+                mappedSubmit = fieldArgToTarget(args.submit, "submit", e.refs);
+            }
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ok: false, error: err instanceof Error ? err.message : String(err) }, null, 2),
+                    },
+                ],
+            };
+        }
+        const td = actionTimeout(args);
+        return asActionResultText(fillForm(ctxFor(e), {
+            fields: mappedFields,
+            submit: mappedSubmit,
+            mode: args.mode,
+            maxResultTokens: args.maxResultTokens,
+            deadlineMs: td.ms,
+            deadlineWarning: td.warning,
+        }));
+    });
+}