browxai 0.7.0

package/dist/tools/deep-perf-tools.js

@@ -0,0 +1,324 @@
+import { requireCdp } from "../engine/index.js";
+import { estimateTokens } from "../util/tokens.js";
+import { DEFAULT_TRACE_CATEGORIES, defaultTracePath, writeTraceFile, readTraceFile, extractInsights, } from "../page/perf.js";
+import { ALL_AUDIT_CATEGORIES } from "../page/perf-audit.js";
+import { runPerfAudit } from "../page/perf-audit-runner.js";
+import { SESSION_ARG } from "./schemas.js";
+/** Whether a `ResourceSendRequest` event is render-blocking. */
+function isRenderBlockingEvent(ev) {
+    const data = (ev.args && ev.args.data);
+    const rb = data && typeof data.renderBlocking === "string" ? data.renderBlocking : "";
+    return rb === "blocking" || rb === "in_body_parser_blocking";
+}
+/** Whether an event is a long task (`RunTask`/`LongTask` ≥ 50ms). */
+function isLongTaskEvent(ev, name) {
+    return ((name === "RunTask" || name === "LongTask") && typeof ev.dur === "number" && ev.dur / 1000 >= 50);
+}
+/** Classify a trace event into the perf counter it bumps, or null. */
+function perfCountKey(ev) {
+    if (!ev || typeof ev !== "object")
+        return null;
+    const name = typeof ev.name === "string" ? ev.name : "";
+    if (!name)
+        return null;
+    if (isLongTaskEvent(ev, name))
+        return "longTaskCount";
+    if (name === "LayoutShift")
+        return "layoutShiftCount";
+    if (name === "largestContentfulPaint::Candidate")
+        return "lcpCandidateCount";
+    if (name === "ResourceSendRequest" && isRenderBlockingEvent(ev))
+        return "renderBlockingCount";
+    return null;
+}
+function inlineCounts(events) {
+    const counts = {
+        longTaskCount: 0,
+        layoutShiftCount: 0,
+        renderBlockingCount: 0,
+        lcpCandidateCount: 0,
+    };
+    for (const ev of events) {
+        const key = perfCountKey(ev);
+        if (key)
+            counts[key]++;
+    }
+    return counts;
+}
+/**
+ * Deep-diagnostics tools — the heavyweight observation surface an agent reaches
+ * for when a flow is slow, leaky, or non-deterministic: performance tracing
+ * (perf_start / perf_stop / perf_insights), the orchestrated perf_audit, JS+CSS
+ * coverage, layout-thrash tracing, V8 heap snapshots + retainer / memory-diff
+ * queries, the virtual clock + seeded RNG determinism knobs, and the
+ * network-aware act_and_wait_for_network / poll_eval waiters. Every block is
+ * registered through the shared `ToolHost` seam; the host owns the closures
+ * (gate, engine-gate, session, workspace, batch dispatch), this module owns the
+ * registrations.
+ */
+/**
+ * Deep tools — performance tracing & audit. `perf_start` / `perf_stop` (Chromium
+ * trace capture), `perf_insights` (post-hoc trace analysis), and `perf_audit`
+ * (the category-driven optimisation pass). All CDP-deep (refused off Chromium).
+ * Registered through the shared `ToolHost` seam.
+ */
+export function registerDeepPerfTools(host) {
+    const { z, register, gateCheck, engineGate, entryFor, workspace } = host;
+    // -------- performance tracing --------
+    register("perf_start", {
+        capability: "action",
+        batchable: true,
+        deep: true,
+        description: "Arm a CDP performance trace on this session — wraps `Tracing.start`. Use to diagnose **why** a slow interaction was slow: a paired `perf_stop` flushes a chromium-format trace file under `<workspace>/perf-traces/` and a `perf_insights` call extracts structured long-tasks / layout-shifts / render-blocking / LCP / navigation-timing data from it. Per-session; one trace in flight at a time. **Idempotent restart:** calling `perf_start` while a trace is already running cleanly stops the in-flight one (events discarded) and starts fresh — an agent that lost track of state always recovers by just calling again. Empty `categories` uses a DevTools-Performance-equivalent default (devtools.timeline + loading + blink.user_timing + frame). Tracing is per-target (the attached chromium); BYOB sessions: a `perf_stop` is REQUIRED to detach the trace buffer on the human's Chrome — `close_session` also cleans up on its way out.",
+        inputSchema: {
+            categories: z
+                .array(z.string())
+                .optional()
+                .describe(`Tracing categories to include. Omit for the default set (${DEFAULT_TRACE_CATEGORIES.join(", ")}).`),
+            ...SESSION_ARG,
+        },
+    }, async ({ categories, session }) => {
+        const g = gateCheck("perf_start");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        const eg = engineGate("perf_start", e);
+        if (eg)
+            return eg;
+        try {
+            const r = await e.perf.start(requireCdp(e.session), { categories });
+            const body = {
+                ok: true,
+                running: true,
+                categories: r.categories,
+                restarted: r.restarted,
+                hint: "Drive your action(s), then call perf_stop to flush the trace. Insights come from perf_insights({tracePath}).",
+            };
+            if (r.restarted) {
+                body.warning =
+                    "A prior perf_start was still active — it has been cleanly stopped (events discarded) and a fresh trace started.";
+            }
+            const tokensEstimate = estimateTokens(JSON.stringify(body));
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ ...body, tokensEstimate }, null, 2) },
+                ],
+            };
+        }
+        catch (err) {
+            const body = { ok: false, error: err instanceof Error ? err.message : String(err) };
+            const tokensEstimate = estimateTokens(JSON.stringify(body));
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ ...body, tokensEstimate }, null, 2) },
+                ],
+            };
+        }
+    });
+    register("perf_stop", {
+        capability: "action",
+        batchable: true,
+        deep: true,
+        description: "Stop the in-flight performance trace and flush it to a workspace-rooted JSON file. Wraps `Tracing.end`. Returns `{ path, bytes, eventCount, categories, durationMs }` plus a tiny summary (long-task count, layout-shift count, render-blocking count) so you don't have to call `perf_insights` for a one-glance answer. Default file path: `<workspace>/perf-traces/<sessionId>-<ts>.json` (override with `path`, which is rejected if it resolves outside `$BROWX_WORKSPACE`). **Safe to call any number of times:** if no trace is running, returns `notRunning:true` rather than an error — pairs cleanly with idempotent agent retries. The file is chromium-tracing format (`{ traceEvents, metadata }`), so it loads in DevTools' Performance panel and `chrome://tracing` directly.",
+        inputSchema: {
+            path: z
+                .string()
+                .optional()
+                .describe("Workspace-rooted output path for the trace JSON. Default: <workspace>/perf-traces/<sessionId>-<ts>.json. Rejected if it escapes $BROWX_WORKSPACE."),
+            ...SESSION_ARG,
+        },
+    }, async ({ path, session }) => {
+        const g = gateCheck("perf_stop");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        const eg = engineGate("perf_stop", e);
+        if (eg)
+            return eg;
+        try {
+            const r = await e.perf.stop(requireCdp(e.session));
+            if (r.notRunning) {
+                const body = {
+                    ok: true,
+                    notRunning: true,
+                    hint: "No trace was active for this session — perf_stop is idempotent; call perf_start first.",
+                };
+                const tokensEstimate = estimateTokens(JSON.stringify(body));
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify({ ...body, tokensEstimate }, null, 2) },
+                    ],
+                };
+            }
+            const targetPath = path ?? defaultTracePath(workspace.root, e.id);
+            // `targetPath` is rooted at workspace.root by construction (defaultTracePath
+            // uses workspace.root; explicit `path` is enforced by resolvePerfTracePath
+            // inside writeTraceFile).
+            const written = writeTraceFile(workspace.root, targetPath, r.events, { categories: r.categories, sessionId: e.id, durationMs: r.durationMs }, "perf_stop");
+            // Tiny inline summary — agent can decide whether to spend tokens on
+            // perf_insights or move on. Doesn't reparse: we count event names only.
+            const summary = inlineCounts(r.events);
+            const body = {
+                ok: true,
+                path: written.resolved,
+                bytes: written.bytes,
+                eventCount: r.events.length,
+                categories: r.categories,
+                durationMs: r.durationMs,
+                summary,
+                hint: "Call perf_insights({tracePath}) for structured long-tasks / layout-shifts / render-blocking / LCP / navigation-timing data.",
+            };
+            if (e.mode === "attached") {
+                body.warning =
+                    "BYOB / attached Chrome: the trace buffer on the human's Chrome has been released. The JSON file remains under $BROWX_WORKSPACE.";
+            }
+            const tokensEstimate = estimateTokens(JSON.stringify(body));
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ ...body, tokensEstimate }, null, 2) },
+                ],
+            };
+        }
+        catch (err) {
+            const body = { ok: false, error: err instanceof Error ? err.message : String(err) };
+            const tokensEstimate = estimateTokens(JSON.stringify(body));
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ ...body, tokensEstimate }, null, 2) },
+                ],
+            };
+        }
+    });
+    register("perf_insights", {
+        capability: "action",
+        batchable: true,
+        deep: true,
+        description: "Extract structured insights from a written performance trace file. Returns `{ longTasks, layoutShifts, renderBlocking, lcpCandidates, navigation?, totals }`: top-50 long tasks (≥50ms blocking work, sorted longest-first); layout shifts with per-shift score + sum; render-blocking CSS/JS resources with duration; LCP candidates (final = effective LCP); navigation milestones (FP / FCP / DCL / load) relative to `navigationStart`. `tracePath` is workspace-rooted (the path `perf_stop` returned) and rejected if it escapes `$BROWX_WORKSPACE`. Same chromium-tracing JSON format the DevTools Performance panel consumes — bring-your-own trace works too.",
+        inputSchema: {
+            tracePath: z
+                .string()
+                .describe("Workspace-rooted path to a chromium trace JSON file (the path returned by perf_stop)."),
+            ...SESSION_ARG,
+        },
+    }, async ({ tracePath, session: _session }) => {
+        const g = gateCheck("perf_insights");
+        if (g)
+            return g;
+        // No session-touching needed — pure file read + parse. But we still
+        // resolve the entry to honour the SESSION_ARG contract for consistency.
+        try {
+            const { events, metadata } = readTraceFile(workspace.root, tracePath, "perf_insights");
+            const insights = extractInsights(events);
+            const body = {
+                ok: true,
+                tracePath,
+                eventCount: events.length,
+                metadata: metadata ?? null,
+                insights,
+            };
+            const tokensEstimate = estimateTokens(JSON.stringify(body));
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ ...body, tokensEstimate }, null, 2) },
+                ],
+            };
+        }
+        catch (err) {
+            const body = { ok: false, error: err instanceof Error ? err.message : String(err) };
+            const tokensEstimate = estimateTokens(JSON.stringify(body));
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ ...body, tokensEstimate }, null, 2) },
+                ],
+            };
+        }
+    });
+    // -------- perf optimization module --------
+    //
+    // Four new primitives that promote browxai's perf surface from
+    // measurement to actionable:
+    //   - perf_audit            → orchestrated audit across 8 pluggable
+    //                              categories, with remediation suggestions.
+    //                              Summary mode capped at 2000 tokens.
+    //   - coverage_start/stop   → CDP Profiler.startPreciseCoverage +
+    //                              CSS.startRuleUsageTracking pair, exposing
+    //                              per-script + per-stylesheet usage% for the
+    //                              dead-code analysis the audit consumes.
+    //   - layout_thrash_trace   → focused 5-30s trace just for forced
+    //                              synchronous layouts + LayoutShift events,
+    //                              aggregated by originating call-stack.
+    //   - memory_diff           → pure-function heap-snapshot diff (two
+    //                              existing `.heapsnapshot` paths in) →
+    //                              retainer-growth report.
+    //
+    // Capability split (also in util/capabilities.ts):
+    //   perf_audit, coverage_stop, layout_thrash_trace, memory_diff → `read`
+    //   coverage_start                                                 → `action`
+    register("perf_audit", {
+        capability: "read",
+        batchable: true,
+        deep: true,
+        description: 'Run a structured performance audit on this session and return remediation-shaped findings — the headline tool. Records a CDP trace + JS/CSS precise coverage + network response metadata for `durationMs` (default 5000, max 30000), then runs 8 pluggable category analysers against the assembled context and composes a report. **Categories** (default = all): `render-blocking` (resources blocking first paint), `unused-code` (scripts/stylesheets with <30% usage), `oversize-images` (>500KB), `layout-thrashing` (>5 forced sync layouts), `long-tasks` (>50ms main-thread blockers), `leak-suspects` (>10% retainer growth — requires `memory_diff` data passed via the runner), `cache-opportunities` (static assets with missing/short Cache-Control), `font-loading` (fonts loaded >200ms after document start). **Output shape:** `{summary:{score, topIssues[]}, byCategory:{[cat]:{issues[], remediations[]}}, evidence:{tracePath, coveragePath?}, warnings[], tokensEstimate}`. **`format`** (default `"summary"`) caps each category to 3 issues + 3 remediations AND enforces a 2000-token budget on the body — over-budget low/medium severity entries are dropped + a `warnings[]` entry surfaces it. `"full"` is unbounded. **Evidence files** (workspace-rooted): the trace under `<workspace>/perf/<sessionId>-audit-<ts>.json` + coverage JSON alongside; both are loadable in DevTools\' Performance / Coverage panels. Internally pluggable — future categories add by extending `ANALYSERS` in `src/page/perf-audit.ts` without changing this public surface. Capability `read` (non-mutating observation).',
+        inputSchema: {
+            categories: z
+                .array(z.enum(ALL_AUDIT_CATEGORIES))
+                .optional()
+                .describe("Subset of audit categories. Default = all 8."),
+            durationMs: z
+                .number()
+                .int()
+                .positive()
+                .max(30_000)
+                .optional()
+                .describe("Observation window in ms. Default 5000, max 30000. Longer windows give more data but cost more wall-clock."),
+            format: z
+                .enum(["summary", "full"])
+                .optional()
+                .describe("`summary` (default) caps each category to 3 issues + enforces a 2000-token body budget. `full` is unbounded."),
+            ...SESSION_ARG,
+        },
+    }, async ({ categories, durationMs, format, session }) => {
+        const g = gateCheck("perf_audit");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        const eg = engineGate("perf_audit", e);
+        if (eg)
+            return eg;
+        try {
+            const r = await runPerfAudit(requireCdp(e.session), workspace.root, e.id, {
+                categories: categories,
+                durationMs,
+                format,
+            });
+            const body = {
+                ok: true,
+                summary: r.report.summary,
+                byCategory: r.report.byCategory,
+                evidence: r.evidence,
+                durationMs: r.durationMs,
+                categoriesRun: r.categoriesRun,
+                warnings: r.report.warnings,
+            };
+            if (e.mode === "attached") {
+                body.warning =
+                    "BYOB / attached Chrome: trace + coverage state has been released on the human's Chrome. Evidence files remain under $BROWX_WORKSPACE.";
+            }
+            const tokensEstimate = estimateTokens(JSON.stringify(body));
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ ...body, tokensEstimate }, null, 2) },
+                ],
+            };
+        }
+        catch (err) {
+            const body = { ok: false, error: err instanceof Error ? err.message : String(err) };
+            const tokensEstimate = estimateTokens(JSON.stringify(body));
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ ...body, tokensEstimate }, null, 2) },
+                ],
+            };
+        }
+    });
+}

package/dist/tools/device-emulation-tools.d.ts

@@ -0,0 +1,9 @@
+import type { ToolHost } from "./host.js";
+/**
+ * Synthetic device emulation — the off-by-default `device-emulation` surface.
+ * Web Bluetooth / WebUSB / WebHID catalog staging (`emulate_bluetooth` /
+ * `emulate_usb` / `emulate_hid`): the page-side wrapper around
+ * `navigator.<api>.requestDevice()` resolves with agent-supplied devices.
+ * Registered through the shared `ToolHost` seam.
+ */
+export declare function registerDeviceEmulationTools(host: ToolHost): void;

package/dist/tools/device-emulation-tools.js

@@ -0,0 +1,137 @@
+import { BYOB_DEVICE_EMU_WARNING } from "../session/device-emu.js";
+import { estimateTokens } from "../util/tokens.js";
+import { SESSION_ARG } from "./schemas.js";
+/**
+ * Synthetic device emulation — the off-by-default `device-emulation` surface.
+ * Web Bluetooth / WebUSB / WebHID catalog staging (`emulate_bluetooth` /
+ * `emulate_usb` / `emulate_hid`): the page-side wrapper around
+ * `navigator.<api>.requestDevice()` resolves with agent-supplied devices.
+ * Registered through the shared `ToolHost` seam.
+ */
+export function registerDeviceEmulationTools(host) {
+    const { z, register, gateCheck, entryFor } = host;
+    // ---------- Web Bluetooth / WebUSB / WebHID device emulation
+    // (capability `device-emulation`) ----------
+    //
+    // Three sibling mutators (`emulate_bluetooth` / `emulate_usb` / `emulate_hid`)
+    // plus a read-side companion (`device_requests`). All four gate behind the
+    // off-by-default `device-emulation` capability — same posture class as
+    // `eval` / `network-body` / `secrets` / `extensions` / `stealth` / `captcha`.
+    // The page-side init-script wrappers install eagerly at session creation
+    // (so a page that calls `requestDevice()` on initial document parse never
+    // hangs); the check binding short-circuits to `refused` when the capability
+    // is off, so a server without `device-emulation` still surfaces "page
+    // asked but capability was off" on `device_requests`.
+    //
+    // Shared input schema — the SyntheticDevice union (every field optional;
+    // wrappers default missing fields to deterministic placeholders so the
+    // page sees a complete shape). A single shape covers all three APIs;
+    // each wrapper picks the fields its spec exposes.
+    const SYNTHETIC_DEVICE_SCHEMA = z.object({
+        name: z
+            .string()
+            .optional()
+            .describe('Display name. Bluetooth: `.name`; USB: `.productName`; HID: `.productName`. Default `"browxai-virtual"`.'),
+        id: z
+            .string()
+            .optional()
+            .describe('Bluetooth: stable device id (UUID-style string). Default `"browxai-<api>-<index>"`.'),
+        vendorId: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe("USB / HID: 16-bit USB-IF vendor id. Default `0x0000`."),
+        productId: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe("USB / HID: 16-bit product id. Default `0x0000`."),
+        manufacturerName: z
+            .string()
+            .optional()
+            .describe('USB: human-readable manufacturer string. Default `"browxai virtual"`.'),
+        serialNumber: z
+            .string()
+            .optional()
+            .describe('USB: serial number string. Default `"BROWX-VIRTUAL"`.'),
+        deviceClass: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe("USB: 8-bit device class. Default `0xFF` (vendor-specific)."),
+        deviceSubclass: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe("USB: 8-bit device subclass. Default `0x00`."),
+        deviceProtocol: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe("USB: 8-bit device protocol. Default `0x00`."),
+        services: z
+            .array(z.string())
+            .optional()
+            .describe("Bluetooth: GATT primary service UUIDs the device advertises. Surfaced on the synthetic device as `device.uuids`. v1 does NOT emulate GATT service exchange — `gatt.getPrimaryService()` rejects."),
+        collections: z
+            .array(z.unknown())
+            .optional()
+            .describe("HID: report-descriptor collection topology exposed on `device.collections`. Pass-through — the page sees whatever shape you supplied."),
+    });
+    const registerEmulateApi = (toolName, api, hint) => {
+        register(toolName, {
+            // emulate_bluetooth / emulate_usb / emulate_hid — all device-emulation.
+            capability: "device-emulation",
+            description: `Stage a synthetic ${api === "bluetooth" ? "Web Bluetooth" : api === "usb" ? "WebUSB" : "WebHID"} device catalog for this session. The page-side wrapper around \`navigator.${api}.requestDevice()\` resolves with the agent-supplied device(s) the next time the page calls it. ${hint} ` +
+                `Pass \`{devices: [...]}\` to install a non-empty catalog (the next requestDevice call ${api === "hid" ? "resolves with the matching device list" : "resolves with the first matching device"}); pass \`{devices: []}\` or omit \`devices\` to clear the catalog (the next call ${api === "hid" ? "resolves with `[]` — the user-dismissed shape for HID" : "rejects with `NotFoundError` — the user-dismissed shape for the picker"}). Persists across navigation: the init-script is re-injected on every new document within the session. Captured page-side calls surface on \`device_requests({session})\`. ` +
+                `**Gated behind the off-by-default \`device-emulation\` capability** — the wrappers tell the page it found physical devices that don't exist, a posture-broadening change distinct from the surrounding policies. v1 covers the picker-clear path only — ${api === "bluetooth" ? "GATT service exchange (`getPrimaryService()`) rejects" : api === "usb" ? "transfer endpoints (`transferIn`/`transferOut`) resolve with zero-byte results" : "input/output reports (`oninputreport`, `sendReport()`) are stubs"}. Same posture class as \`eval\` / \`network-body\` / \`secrets\` / \`extensions\` / \`stealth\` / \`captcha\` — see docs/threat-model.md. Returns \`{ok, session, api, catalog:{devices:[…]}, warnings?, tokensEstimate}\`.`,
+            inputSchema: {
+                devices: z
+                    .array(SYNTHETIC_DEVICE_SCHEMA)
+                    .optional()
+                    .describe(`Synthetic devices to expose. Omit or pass \`[]\` to clear the catalog. ${api === "hid" ? "All entries are returned to the page on every requestDevice() call." : "Only the first entry is returned to the page on requestDevice() (Bluetooth/USB pickers are single-result)."}`),
+                ...SESSION_ARG,
+            },
+        }, async (args) => {
+            const g = gateCheck(toolName);
+            if (g)
+                return g;
+            const e = await entryFor(args.session);
+            try {
+                const devices = args.devices ?? [];
+                const catalog = e.webDeviceEmulation.set(api, devices);
+                const warnings = [];
+                if (e.mode === "attached")
+                    warnings.push(BYOB_DEVICE_EMU_WARNING);
+                const body = {
+                    ok: true,
+                    session: e.id,
+                    api,
+                    catalog,
+                };
+                if (warnings.length)
+                    body.warnings = warnings;
+                body.tokensEstimate = estimateTokens(JSON.stringify(body));
+                return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
+            }
+            catch (err) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ ok: false, error: err instanceof Error ? err.message : String(err) }, null, 2),
+                        },
+                    ],
+                };
+            }
+        });
+    };
+    registerEmulateApi("emulate_bluetooth", "bluetooth", "The synthetic `BluetoothDevice` carries `{id, name, uuids, gatt}`; `gatt.connect()` resolves with a stub server whose `getPrimaryService()` rejects (no GATT emulation in v1) — enough for pages that gate flow on the picker-clear, not enough for pages that go on to exchange characteristic data.");
+    registerEmulateApi("emulate_usb", "usb", "The synthetic `USBDevice` carries vendor/product/class/manufacturer/serial fields; `open()` / `selectConfiguration()` / `claimInterface()` resolve; transfer endpoints (`transferIn` / `transferOut` / `controlTransferIn` / `controlTransferOut`) resolve with zero-byte payloads (no synthetic data flow).");
+    registerEmulateApi("emulate_hid", "hid", "The synthetic `HIDDevice` carries vendor/product/productName/collections; `open()` / `sendReport()` / `sendFeatureReport()` resolve; `receiveFeatureReport()` resolves with an empty DataView; `oninputreport` is never fired (no synthetic device traffic).");
+}

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

@@ -0,0 +1,18 @@
+import type { ToolHost } from "./host.js";
+/**
+ * Chrome-extension management + the server-side compound primitives:
+ * extensions_install / extensions_list / extensions_reload /
+ * extensions_trigger / extensions_uninstall, plus await_human, batch,
+ * act_and_sample, act_and_diff, flake_check.
+ *
+ * RFC 0004 P3 / D3 (SRP): the registrations were split by cohesive family into
+ * three sibling modules (extensions / batch-human / batch-act), and the
+ * persistent-session context rebuild was extracted to `extensions-rebuild.ts`.
+ * This module stays the single entry point `server.ts` + `tool-metadata.ts` call,
+ * and invokes each family in the EXACT prior source order so the registered-name
+ * set + the derived maps stay byte-identical. The extension tools rebuild the
+ * underlying browser context on mutation (Chromium can't add/remove extensions on
+ * a live context). The host owns the closures; the family modules own the
+ * registrations.
+ */
+export declare function registerExtensionsBatchTools(host: ToolHost): void;

package/dist/tools/extensions-batch-tools.js

@@ -0,0 +1,24 @@
+import { registerExtensionsTools } from "./extensions-tools.js";
+import { registerBatchHumanTools } from "./batch-human-tools.js";
+import { registerBatchActTools } from "./batch-act-tools.js";
+/**
+ * Chrome-extension management + the server-side compound primitives:
+ * extensions_install / extensions_list / extensions_reload /
+ * extensions_trigger / extensions_uninstall, plus await_human, batch,
+ * act_and_sample, act_and_diff, flake_check.
+ *
+ * RFC 0004 P3 / D3 (SRP): the registrations were split by cohesive family into
+ * three sibling modules (extensions / batch-human / batch-act), and the
+ * persistent-session context rebuild was extracted to `extensions-rebuild.ts`.
+ * This module stays the single entry point `server.ts` + `tool-metadata.ts` call,
+ * and invokes each family in the EXACT prior source order so the registered-name
+ * set + the derived maps stay byte-identical. The extension tools rebuild the
+ * underlying browser context on mutation (Chromium can't add/remove extensions on
+ * a live context). The host owns the closures; the family modules own the
+ * registrations.
+ */
+export function registerExtensionsBatchTools(host) {
+    registerExtensionsTools(host);
+    registerBatchHumanTools(host);
+    registerBatchActTools(host);
+}

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

@@ -0,0 +1,22 @@
+import { type SessionEntry } from "../session/registry.js";
+import type { CapabilityConfig } from "../util/capabilities.js";
+import type { ConfigStore, ResolvedConfig } from "../util/config-store.js";
+import type { Workspace } from "../util/workspace.js";
+import type { StartOptions } from "../server.js";
+/** The per-server boundary deps the rebuild threads in (was the closure the
+ *  in-module helper held over `buildHost`'s scope). Passed explicitly so a second
+ *  server in the same process can't cross-wire this server's sessions. */
+export interface ExtensionRebuildDeps {
+    caps: CapabilityConfig;
+    configStore: ConfigStore;
+    workspace: Workspace;
+    opts: StartOptions;
+    resolvedConfig: ResolvedConfig;
+}
+/** 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 declare function rebuildPersistentForExtensions(e: SessionEntry, deps: ExtensionRebuildDeps): Promise<void>;