browxai 0.7.0

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

@@ -0,0 +1,353 @@
+import { requireCdp } from "../engine/index.js";
+import { applyLocaleCdp, applyLocaleNavigator, clearLocaleCdp, applyTimezoneCdp, clearTimezoneCdp, applyUserAgentCdp, clearUserAgentCdp, applyPermissions, clearPermissions, BYOB_EMULATION_WARNING, } from "../session/emulation.js";
+import { setTabVisibility } from "../page/visibility.js";
+import { estimateTokens } from "../util/tokens.js";
+import { SESSION_ARG } from "./schemas.js";
+/**
+ * Per-primitive live emulation — the seven sibling mutators that each set ONE
+ * live knob on the session (`set_locale` / `set_timezone` / `set_geolocation` /
+ * `set_color_scheme` / `set_reduced_motion` / `set_user_agent` /
+ * `grant_permissions`) plus `tab_visibility`. State persists on the SessionEntry.
+ * Registered through the shared `ToolHost` seam.
+ */
+export function registerLiveEmulationTools(host) {
+    const { z, register, gateCheck, engineGate, entryFor, emulationFor } = host;
+    // ---------- Per-primitive device emulation ----------
+    //
+    // Seven sibling tools (deliberately NOT a bundled `emulate({…})`) — each
+    // mutates ONE Playwright/CDP knob on the live session: `set_locale`,
+    // `set_timezone`, `set_geolocation`, `set_color_scheme`, `set_reduced_motion`,
+    // `set_user_agent`, `grant_permissions`. State persists on the SessionEntry
+    // so new pages within the same context re-apply automatically. CONTEXT-
+    // time-only Playwright settings (locale, timezone, UA) are routed through
+    // their CDP equivalents (`Emulation.setLocaleOverride`,
+    // `Emulation.setTimezoneOverride`, `Network.setUserAgentOverride`) — those
+    // DO take effect mid-session. The other four use Playwright's stable
+    // mutators. BYOB / attached sessions surface a warning that overrides
+    // applied via CDP outlive browxai's detach.
+    /** Wrap an emulation-tool result with the standard envelope (`ok`, `applied`,
+     *  `state` snapshot, `tokensEstimate`, plus BYOB warning when applicable). */
+    const emulationResult = (e, applied, extra = {}) => {
+        const warnings = [...(extra.warnings ?? [])];
+        if (e.mode === "attached")
+            warnings.push(BYOB_EMULATION_WARNING);
+        const body = {
+            ok: true,
+            session: e.id,
+            applied,
+            state: {
+                locale: e.deviceEmulation.locale ?? null,
+                timezoneId: e.deviceEmulation.timezoneId ?? null,
+                geolocation: e.deviceEmulation.geolocation ?? null,
+                colorScheme: e.deviceEmulation.colorScheme ?? null,
+                reducedMotion: e.deviceEmulation.reducedMotion ?? null,
+                userAgent: e.deviceEmulation.userAgent ?? null,
+                permissions: Object.fromEntries(e.deviceEmulation.permissions),
+            },
+        };
+        if (warnings.length)
+            body.warnings = warnings;
+        if (extra.note)
+            body.note = extra.note;
+        body.tokensEstimate = estimateTokens(JSON.stringify(body));
+        return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
+    };
+    /** Standard emulation failure envelope. */
+    const emulationError = (toolName, err) => ({
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    ok: false,
+                    action: { type: toolName },
+                    error: err instanceof Error ? err.message : String(err),
+                    tokensEstimate: 0,
+                }, null, 2),
+            },
+        ],
+    });
+    /** Render an EmulationSubstrate refusal as the standard failure envelope (the
+     *  Safari adapter has no live surface for the knob). Carries the adapter's
+     *  `hint` so the agent knows where the override IS available. */
+    const emulationRefusal = (toolName, refusal) => ({
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    ok: false,
+                    action: { type: toolName },
+                    error: refusal.error,
+                    ...(refusal.hint ? { hint: refusal.hint } : {}),
+                    tokensEstimate: 0,
+                }, null, 2),
+            },
+        ],
+    });
+    register("set_locale", {
+        capability: "action",
+        batchable: true,
+        deep: true,
+        description: "Override the session's browser locale (`navigator.language` / `navigator.languages`, `Intl.*` defaults, `Accept-Language` header). Persists across navigation + new tabs in the same session and takes effect on the current page immediately. Pass `locale: null` to clear the override and restore the browser default. NOTE: Playwright's `BrowserContext.locale` is creation-time-only, so this primitive combines CDP `Emulation.setLocaleOverride` (Accept-Language + Intl) with a context init-script that patches the JS `navigator.language(s)` getters — `setLocaleOverride` alone does not move them. BYOB caveat: both overrides persist on the attached Chrome until it navigates/restarts after detach.",
+        inputSchema: {
+            locale: z
+                .union([z.string(), z.null()])
+                .optional()
+                .describe('BCP-47 locale tag, e.g. "en-US", "de-DE", "ja-JP". Pass null (or omit) to clear the override and restore the browser default.'),
+            ...SESSION_ARG,
+        },
+    }, async ({ locale, session }) => {
+        const g = gateCheck("set_locale");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        const eg = engineGate("set_locale", e);
+        if (eg)
+            return eg;
+        try {
+            const localePage = e.session.page();
+            if (locale === null || locale === undefined) {
+                await clearLocaleCdp(requireCdp(e.session));
+                await applyLocaleNavigator(localePage.context(), localePage, "");
+                e.deviceEmulation.locale = undefined;
+                return emulationResult(e, { locale: null });
+            }
+            await applyLocaleCdp(requireCdp(e.session), locale);
+            await applyLocaleNavigator(localePage.context(), localePage, locale);
+            e.deviceEmulation.locale = locale;
+            return emulationResult(e, { locale });
+        }
+        catch (err) {
+            return emulationError("set_locale", err);
+        }
+    });
+    register("set_timezone", {
+        capability: "action",
+        batchable: true,
+        deep: true,
+        description: "Override the session's IANA timezone for `Date`, `Intl.DateTimeFormat`, etc. Persists across navigation + new tabs. Pass `timezoneId: null` to clear. NOTE: Playwright's `BrowserContext.timezoneId` is creation-time-only, so this primitive uses CDP `Emulation.setTimezoneOverride` (mid-session-capable). BYOB caveat: the CDP override persists on attached Chrome after detach.",
+        inputSchema: {
+            timezoneId: z
+                .union([z.string(), z.null()])
+                .optional()
+                .describe('IANA timezone, e.g. "America/New_York", "Europe/London", "Asia/Tokyo". Pass null (or omit) to clear.'),
+            ...SESSION_ARG,
+        },
+    }, async ({ timezoneId, session }) => {
+        const g = gateCheck("set_timezone");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        const eg = engineGate("set_timezone", e);
+        if (eg)
+            return eg;
+        try {
+            if (timezoneId === null || timezoneId === undefined) {
+                await clearTimezoneCdp(requireCdp(e.session));
+                e.deviceEmulation.timezoneId = undefined;
+                return emulationResult(e, { timezoneId: null });
+            }
+            await applyTimezoneCdp(requireCdp(e.session), timezoneId);
+            e.deviceEmulation.timezoneId = timezoneId;
+            return emulationResult(e, { timezoneId });
+        }
+        catch (err) {
+            return emulationError("set_timezone", err);
+        }
+    });
+    register("set_geolocation", {
+        capability: "action",
+        batchable: true,
+        description: "Override the session's HTML5 Geolocation reading. The page MUST also be granted the `geolocation` permission via `grant_permissions` for `navigator.geolocation.*` to deliver this value (browsers gate it). Uses Playwright's `context.setGeolocation()` which mutates a live context — no CDP fallback needed. Pass no coords (or `latitude:null`) to clear.",
+        inputSchema: {
+            latitude: z
+                .union([z.number(), z.null()])
+                .optional()
+                .describe("Latitude in degrees [-90, 90]. Pass null (or omit) to clear the override."),
+            longitude: z.number().optional().describe("Longitude in degrees [-180, 180]."),
+            accuracy: z
+                .number()
+                .nonnegative()
+                .optional()
+                .describe("Accuracy radius in metres. Default 0."),
+            ...SESSION_ARG,
+        },
+    }, async ({ latitude, longitude, accuracy, session }) => {
+        const g = gateCheck("set_geolocation");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        try {
+            const isClear = latitude === null || latitude === undefined;
+            if (isClear) {
+                const r = await emulationFor(e).setGeolocation(null);
+                if (r.kind === "refusal")
+                    return emulationRefusal("set_geolocation", r);
+                e.deviceEmulation.geolocation = undefined;
+                return emulationResult(e, { geolocation: null });
+            }
+            if (longitude === undefined) {
+                return emulationError("set_geolocation", new Error("longitude is required when latitude is set"));
+            }
+            const coords = { latitude, longitude, accuracy };
+            const r = await emulationFor(e).setGeolocation(coords);
+            if (r.kind === "refusal")
+                return emulationRefusal("set_geolocation", r);
+            e.deviceEmulation.geolocation = coords;
+            const warnings = [];
+            const grantedHere = e.deviceEmulation.permissions.get("") ?? [];
+            const grantedAll = [...e.deviceEmulation.permissions.values()].flat();
+            if (![...grantedHere, ...grantedAll].includes("geolocation")) {
+                warnings.push('set_geolocation: pages need the `geolocation` permission for navigator.geolocation to deliver this — call grant_permissions({ permissions: ["geolocation"] }) for the relevant origin.');
+            }
+            return emulationResult(e, { geolocation: coords }, { warnings });
+        }
+        catch (err) {
+            return emulationError("set_geolocation", err);
+        }
+    });
+    register("set_color_scheme", {
+        capability: "action",
+        batchable: true,
+        description: "Override the session's `prefers-color-scheme` media query — drives dark-mode rendering. Mutates a live page via Playwright's `page.emulateMedia({colorScheme})`; takes effect immediately (CSS media queries re-evaluate). Pass `\"no-preference\"` to clear the override.",
+        inputSchema: {
+            scheme: z
+                .enum(["light", "dark", "no-preference"])
+                .describe("`light` / `dark` force the scheme; `no-preference` clears the override and restores the system default."),
+            ...SESSION_ARG,
+        },
+    }, async ({ scheme, session }) => {
+        const g = gateCheck("set_color_scheme");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        try {
+            const r = await emulationFor(e).setColorScheme(scheme);
+            if (r.kind === "refusal")
+                return emulationRefusal("set_color_scheme", r);
+            e.deviceEmulation.colorScheme = scheme === "no-preference" ? undefined : scheme;
+            return emulationResult(e, { colorScheme: scheme });
+        }
+        catch (err) {
+            return emulationError("set_color_scheme", err);
+        }
+    });
+    register("set_reduced_motion", {
+        capability: "action",
+        batchable: true,
+        description: "Override the session's `prefers-reduced-motion` media query — useful when an animation-heavy page is unstable to drive, or to verify a reduced-motion code path. Mutates a live page via Playwright's `page.emulateMedia({reducedMotion})`. Pass `on:false` to clear.",
+        inputSchema: {
+            on: z.boolean().describe("true → `reduce`; false → `no-preference` (clears the override)."),
+            ...SESSION_ARG,
+        },
+    }, async ({ on, session }) => {
+        const g = gateCheck("set_reduced_motion");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        try {
+            const motion = on ? "reduce" : "no-preference";
+            const r = await emulationFor(e).setReducedMotion(motion);
+            if (r.kind === "refusal")
+                return emulationRefusal("set_reduced_motion", r);
+            e.deviceEmulation.reducedMotion = on ? "reduce" : undefined;
+            return emulationResult(e, { reducedMotion: motion });
+        }
+        catch (err) {
+            return emulationError("set_reduced_motion", err);
+        }
+    });
+    register("set_user_agent", {
+        capability: "action",
+        batchable: true,
+        deep: true,
+        description: "Override the session's User-Agent (HTTP header + `navigator.userAgent`). Persists across navigation + new tabs. Pass `userAgent: null` to clear. NOTE: Playwright's `BrowserContext.userAgent` is creation-time-only, so this primitive uses CDP `Network.setUserAgentOverride` (mid-session-capable; updates both the network header and the JS-visible value). BYOB caveat: the CDP override persists on attached Chrome after detach.",
+        inputSchema: {
+            userAgent: z
+                .union([z.string(), z.null()])
+                .optional()
+                .describe("Full User-Agent string. Pass null (or omit) to clear and restore the browser default."),
+            ...SESSION_ARG,
+        },
+    }, async ({ userAgent, session }) => {
+        const g = gateCheck("set_user_agent");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        const eg = engineGate("set_user_agent", e);
+        if (eg)
+            return eg;
+        try {
+            if (userAgent === null || userAgent === undefined) {
+                await clearUserAgentCdp(requireCdp(e.session));
+                e.deviceEmulation.userAgent = undefined;
+                return emulationResult(e, { userAgent: null });
+            }
+            await applyUserAgentCdp(requireCdp(e.session), userAgent);
+            e.deviceEmulation.userAgent = userAgent;
+            return emulationResult(e, { userAgent });
+        }
+        catch (err) {
+            return emulationError("set_user_agent", err);
+        }
+    });
+    register("grant_permissions", {
+        capability: "action",
+        batchable: true,
+        description: "Grant browser permissions for the session — `geolocation`, `notifications`, `clipboard-read`, `clipboard-write`, `camera`, `microphone`, `midi`, `background-sync`, `accelerometer`, `gyroscope`, `magnetometer`, `ambient-light-sensor`, `payment-handler`, etc. (Chromium permission names). Mutates a live context via Playwright `context.grantPermissions`. Optionally scope to a specific `origin`; otherwise grants for the current page's origin. Pass `permissions: []` (or omit) to clear all grants for the session — Playwright does not expose per-origin revocation, so clearing is context-wide.",
+        inputSchema: {
+            permissions: z
+                .array(z.string())
+                .optional()
+                .describe("List of Chromium permission names. Pass empty array (or omit) to clear ALL grants (context-wide; per-origin revocation isn't supported by the underlying platform)."),
+            origin: z
+                .string()
+                .optional()
+                .describe('Origin to scope the grant to (e.g. "https://example.com"). Omit to use the current page\'s origin.'),
+            ...SESSION_ARG,
+        },
+    }, async ({ permissions, origin, session }) => {
+        const g = gateCheck("grant_permissions");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        try {
+            if (!permissions || permissions.length === 0) {
+                const hadOrigin = origin !== undefined;
+                await clearPermissions(e.session.page().context(), e.deviceEmulation, origin);
+                const note = hadOrigin
+                    ? "Per-origin permission revocation isn't supported by Playwright; cleared ALL grants for the session context."
+                    : "Cleared ALL permission grants for the session context.";
+                return emulationResult(e, { permissions: [], origin: origin ?? null }, { note });
+            }
+            await applyPermissions(e.session.page().context(), e.deviceEmulation, permissions, origin);
+            return emulationResult(e, { permissions, origin: origin ?? null });
+        }
+        catch (err) {
+            return emulationError("grant_permissions", err);
+        }
+    });
+    register("tab_visibility", {
+        capability: "navigation",
+        description: 'Background or foreground the session\'s tab — the only way to reproduce the bug class that only fires when the tab is hidden (throttled setTimeout, paused requestAnimationFrame so framework enter/animation hooks never run, and on-return a visibilitychange/focus handler replays stale state). `state:"background"` overrides document.visibilityState/hidden + dispatches visibilitychange, AND best-effort takes front focus away from the page so real timer/rAF throttling applies (real throttling is best-effort under headless). `state:"background"` with `holdMs` is the headline form: background, hold hidden for holdMs, then auto-foreground — reproducing the background→return transition in one call. `state:"foreground"` restores visibility and re-focuses the tab.',
+        inputSchema: {
+            state: z
+                .enum(["background", "foreground"])
+                .describe("background = hide/deprioritise the tab; foreground = restore + re-focus."),
+            holdMs: z
+                .number()
+                .int()
+                .positive()
+                .max(120_000)
+                .optional()
+                .describe("background only: hold hidden this long (ms), then auto-foreground. Cap 120000."),
+            ...SESSION_ARG,
+        },
+    }, async ({ state, holdMs, session }) => {
+        const g = gateCheck("tab_visibility");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        const result = await setTabVisibility(e.session.page(), e.session.page().context(), state, holdMs);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/tools/plugin-runtime.d.ts

@@ -0,0 +1,36 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { PluginRecord } from "../plugin/types.js";
+import type { Capability } from "../util/capabilities.js";
+import type { ToolHost, ToolResponse } from "./host.js";
+/** The createServer-owned pieces the plugin runtime needs that the shared
+ *  `ToolHost` doesn't surface: the raw MCP server (for plugin-tool
+ *  registration) and the per-dispatch metrics/diagnostics noters (plugin tools
+ *  ride the same accounting path as core tools, minus the wedge tracker). */
+export interface PluginRuntimeDeps {
+    server: McpServer;
+    noteMetrics: (toolName: string, args: unknown, res: ToolResponse, startedAt: number) => void;
+    noteDiagnostics: (toolName: string, args: unknown, res: ToolResponse, startedAt: number) => void;
+}
+/** The capability each plugin-info MCP tool gates under (both `read` — they are
+ *  pure-read introspection over the loaded-plugin set). The SINGLE SOURCE for
+ *  these two rows: `wirePluginRuntime`'s `register` calls read it (colocated
+ *  metadata, RFC 0004 P2), and the metadata-collector bootstrap
+ *  (`tool-metadata.ts`) reads it to derive the rows WITHOUT running the async
+ *  plugin loader. Keyed by tool name. */
+export declare const PLUGIN_INFO_TOOL_CAPABILITY: Readonly<Record<string, Capability>>;
+/**
+ * Plugin runtime wiring — the LAST step of `createServer`, run after every core
+ * `register*Tools(host)` call so the `coreToolNames` snapshot below counts the
+ * full core surface as "core" and plugins load on top of it.
+ *
+ * Plugins are loaded ONCE here. Cycle detection is fatal; everything else
+ * (capability mismatch, missing dep, malformed manifest, load-time exception)
+ * downgrades the affected plugin to a non-`loaded` status and surfaces on
+ * `plugins_list`. `set_config({plugins})` persists into the config store but
+ * takes effect on NEXT server restart — mirroring the capability lifecycle.
+ *
+ * Returns the loaded `PluginRecord[]`; `createServer` assigns it to the
+ * `pluginRecords` local that `get_config` reports the live enabled-plugin set
+ * from (via the host getter).
+ */
+export declare function wirePluginRuntime(host: ToolHost, deps: PluginRuntimeDeps): Promise<ReadonlyArray<PluginRecord>>;

package/dist/tools/plugin-runtime.js

@@ -0,0 +1,274 @@
+import { startPluginRuntime } from "../plugin/runtime.js";
+import { RUNTIME_API_VERSION } from "../plugin/manifest.js";
+import { log } from "../util/logging.js";
+/** The capability each plugin-info MCP tool gates under (both `read` — they are
+ *  pure-read introspection over the loaded-plugin set). The SINGLE SOURCE for
+ *  these two rows: `wirePluginRuntime`'s `register` calls read it (colocated
+ *  metadata, RFC 0004 P2), and the metadata-collector bootstrap
+ *  (`tool-metadata.ts`) reads it to derive the rows WITHOUT running the async
+ *  plugin loader. Keyed by tool name. */
+export const PLUGIN_INFO_TOOL_CAPABILITY = {
+    plugins_list: "read",
+    plugins_info: "read",
+};
+/**
+ * Plugin runtime wiring — the LAST step of `createServer`, run after every core
+ * `register*Tools(host)` call so the `coreToolNames` snapshot below counts the
+ * full core surface as "core" and plugins load on top of it.
+ *
+ * Plugins are loaded ONCE here. Cycle detection is fatal; everything else
+ * (capability mismatch, missing dep, malformed manifest, load-time exception)
+ * downgrades the affected plugin to a non-`loaded` status and surfaces on
+ * `plugins_list`. `set_config({plugins})` persists into the config store but
+ * takes effect on NEXT server restart — mirroring the capability lifecycle.
+ *
+ * Returns the loaded `PluginRecord[]`; `createServer` assigns it to the
+ * `pluginRecords` local that `get_config` reports the live enabled-plugin set
+ * from (via the host getter).
+ */
+export async function wirePluginRuntime(host, deps) {
+    const { register, gateCheck, caps, workspace, resolvedConfig, toolHandlers, z } = host;
+    const { server, noteMetrics, noteDiagnostics } = deps;
+    let pluginRecords = [];
+    /** Per-plugin-tool capability map. Populated as the runtime registers
+     *  tools; `isToolEnabled` consults this first for namespaced tools and
+     *  falls back to the core map otherwise. */
+    const pluginToolCapability = new Map();
+    /** Per-plugin-tool ownership map (tool → plugin npm name). Mirrors the
+     *  runtime's internal liveTools registry so the host-side `ownerOf`
+     *  hook can answer "who owns tool X" without crossing the runtime
+     *  boundary. */
+    const pluginToolOwner = new Map();
+    /** Per-plugin-tool def cache — keeps the description + input schema
+     *  so `plugins_info` can dump the registered shape. */
+    const pluginToolDef = new Map();
+    // Snapshot of core tool names at this point — anything registered
+    // BEFORE plugin loading is a core tool from the plugin runtime's point
+    // of view.
+    const coreToolNames = new Set(Object.keys(toolHandlers));
+    // Wrap `gateCheck` for plugin tools by patching the active gate
+    // check pipeline. We can't reuse the core `gateCheck` directly — it
+    // consults `TOOL_CAPABILITY` for the core surface only. The wrapper
+    // injected on every plugin tool registration does the check inline.
+    const pluginGate = (toolName) => {
+        const cap = pluginToolCapability.get(toolName);
+        if (cap === undefined)
+            return null; // no capability declared → allowed
+        if (caps.enabled.has(cap))
+            return null;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        ok: false,
+                        error: `plugin tool "${toolName}" is disabled — its declared capability is not in the server's ACTIVE set`,
+                        requiredCapability: cap,
+                        activeCapabilities: [...caps.enabled],
+                        hint: "Plugin-declared capabilities are gated the same way as core tools — add the capability to BROWX_CAPABILITIES " +
+                            "(or set_config({capabilities:[...]})) and RESTART the browxai server.",
+                    }, null, 2),
+                },
+            ],
+        };
+    };
+    const registerPluginTool = (name, def, handler, capability, ownerPlugin) => {
+        if (capability !== undefined) {
+            pluginToolCapability.set(name, capability);
+        }
+        else {
+            pluginToolCapability.set(name, undefined);
+        }
+        pluginToolOwner.set(name, ownerPlugin);
+        pluginToolDef.set(name, def);
+        // Plugin tool handler envelope: capability gate → handler → standard
+        // metrics + diagnostics wrap. We don't apply the wedge tracker —
+        // plugin tools aren't core page-exercising primitives, so the
+        // session-wedged stamping path is reserved for browser-touching
+        // tools the host owns.
+        const wrapped = async (args) => {
+            const startedAt = Date.now();
+            const gated = pluginGate(name);
+            if (gated)
+                return gated;
+            let inner;
+            try {
+                inner = await handler(args);
+            }
+            catch (e) {
+                inner = {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                ok: false,
+                                error: `plugin tool "${name}" threw: ${e instanceof Error ? e.message : String(e)}`,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            // PluginToolResponse content items match ToolResponse exactly — same
+            // shape, kept as parallel types only to draw the API boundary.
+            const out = { content: [...inner.content] };
+            noteMetrics(name, args, out, startedAt);
+            noteDiagnostics(name, args, out, startedAt);
+            return out;
+        };
+        toolHandlers[name] = wrapped;
+        // The SDK's `registerTool` generic cannot relate its conditional-typed
+        // callback to the plugin def's `Record<string, z.ZodTypeAny>` schema;
+        // widening the config's schema to a concrete `z.ZodRawShape` lets that
+        // conditional resolve, so `wrapped` (args narrowed to `unknown`, result a
+        // `CallToolResult`) matches with no assertion. Mirrors `host-build.ts`.
+        const sdkConfig = def;
+        server.registerTool(name, sdkConfig, wrapped);
+    };
+    try {
+        const result = await startPluginRuntime({
+            workspaceRoot: workspace.root,
+            enabledCapabilities: caps.enabled,
+            extraDeclared: resolvedConfig.plugins,
+            host: {
+                isCoreTool: (n) => coreToolNames.has(n),
+                dispatch: async (n, args) => {
+                    const fn = toolHandlers[n];
+                    if (!fn) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: JSON.stringify({ ok: false, error: `dispatch: unknown tool "${n}"` }, null, 2),
+                                },
+                            ],
+                        };
+                    }
+                    const res = await fn(args);
+                    return { content: [...res.content] };
+                },
+                registerTool: registerPluginTool,
+                ownerOf: (n) => {
+                    if (coreToolNames.has(n))
+                        return undefined;
+                    return pluginToolOwner.get(n);
+                },
+            },
+        });
+        pluginRecords = result.plugins;
+        const loaded = pluginRecords.filter((p) => p.status === "loaded");
+        log.info("plugin runtime: loaded", {
+            apiVersion: RUNTIME_API_VERSION,
+            pluginsDeclared: pluginRecords.length,
+            pluginsLoaded: loaded.length,
+            toolsRegistered: result.toolCount,
+        });
+        for (const p of pluginRecords) {
+            if (p.status !== "loaded") {
+                log.warn(`plugin runtime: ${p.manifest.name} status=${p.status} — ${p.statusReason ?? ""}`);
+            }
+        }
+    }
+    catch (e) {
+        // Cycle errors and only cycle errors abort startup loudly. All other
+        // failures get downgraded inside startPluginRuntime to a per-plugin
+        // load-error record.
+        log.error(`plugin runtime: fatal — ${e instanceof Error ? e.message : String(e)}`);
+        throw e;
+    }
+    // plugins_list / plugins_info MCP tools ( surface).
+    register("plugins_list", {
+        description: "List every declared browxai plugin and its load status. Each entry carries `{name, namespace, version, trust, capabilities, dependsOn, status, declaredAt, enabledAt?, statusReason?, tools, transitiveDeps}`. `status` is one of `loaded` (live), `disabled-by-capability-mismatch` (plugin declares a capability not in the server's active set), `disabled-by-cycle` (caught at startup — server start would have aborted, so this status only appears in test surfaces), `disabled-by-dep-missing` (a `dependsOn` target isn't installed or fails the version range), `disabled-by-namespace-conflict` (two plugins claimed the same namespace), or `load-error` (manifest invalid, entry module threw, etc.). Read-only — gates under `read`. The plugin runtime is RESOLVED ONCE AT SERVER START; this tool reports the live state, not what `plugins.json` currently declares (use `get_config({scope:'resolved'}).plugins` for that, plus the `pluginsPendingRestart` flag).",
+        capability: PLUGIN_INFO_TOOL_CAPABILITY.plugins_list,
+        inputSchema: {},
+    }, async () => {
+        // D3 (RFC 0004 P2): enforce the declared `read` capability at the handler,
+        // mirroring the gesture-network per-handler idiom. Without this a direct
+        // server dispatch under BROWX_CAPABILITIES=human would EXECUTE this tool
+        // despite its derived `read` row (the row alone doesn't gate the handler).
+        const g = gateCheck("plugins_list");
+        if (g)
+            return g;
+        const body = {
+            ok: true,
+            apiVersion: RUNTIME_API_VERSION,
+            plugins: pluginRecords.map((p) => ({
+                name: p.manifest.name,
+                namespace: p.manifest.browxai.namespace || null,
+                version: p.manifest.version,
+                trust: p.manifest.trust,
+                capabilities: p.declaredCapabilities,
+                dependsOn: p.manifest.browxai.dependsOn,
+                status: p.status,
+                declaredAt: p.declaredAt,
+                ...(p.enabledAt ? { enabledAt: p.enabledAt } : {}),
+                ...(p.statusReason ? { statusReason: p.statusReason } : {}),
+                tools: p.tools,
+                transitiveDeps: p.transitiveDeps,
+            })),
+        };
+        return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
+    });
+    register("plugins_info", {
+        description: "Full manifest + tool registry dump for ONE plugin. Returns `{name, version, namespace, trust, capabilities, dependsOn, transitiveDeps, status, tools: [{name, description, inputSchema?}]}` so an operator can audit what a plugin contributes to the running surface. Read-only — gates under `read`.",
+        capability: PLUGIN_INFO_TOOL_CAPABILITY.plugins_info,
+        inputSchema: {
+            name: z
+                .string()
+                .describe('npm package name of the plugin (e.g. "@browxai/plugin-example").'),
+        },
+    }, async ({ name }) => {
+        // D3 (RFC 0004 P2): enforce the declared `read` capability at the handler
+        // (see plugins_list above).
+        const g = gateCheck("plugins_info");
+        if (g)
+            return g;
+        const p = pluginRecords.find((r) => r.manifest.name === name);
+        if (!p) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            ok: false,
+                            error: `plugin "${name}" is not in the declared set`,
+                            declared: pluginRecords.map((r) => r.manifest.name),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        const tools = p.tools.map((tName) => {
+            const def = pluginToolDef.get(tName);
+            return {
+                name: tName,
+                description: def?.description ?? null,
+                // Best-effort schema introspection — Zod schemas are runtime
+                // objects, but we can surface the field names so the operator
+                // sees the input shape. Full JSON-Schema lowering is deferred.
+                inputFields: def?.inputSchema ? Object.keys(def.inputSchema).sort() : [],
+            };
+        });
+        const body = {
+            ok: true,
+            name: p.manifest.name,
+            version: p.manifest.version,
+            description: p.manifest.description ?? null,
+            path: p.manifest.path,
+            entryPath: p.manifest.entryPath,
+            namespace: p.manifest.browxai.namespace || null,
+            trust: p.manifest.trust,
+            capabilities: p.declaredCapabilities,
+            dependsOn: p.manifest.browxai.dependsOn,
+            transitiveDeps: p.transitiveDeps,
+            status: p.status,
+            statusReason: p.statusReason ?? null,
+            declaredAt: p.declaredAt,
+            enabledAt: p.enabledAt ?? null,
+            apiVersion: p.manifest.browxai.apiVersion,
+            browxaiVersion: p.manifest.browxai.browxaiVersion ?? null,
+            tools,
+        };
+        return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
+    });
+    return pluginRecords;
+}

package/dist/tools/read-observe-buffer-tools.d.ts

@@ -0,0 +1,9 @@
+import type { ToolHost } from "./host.js";
+/**
+ * Read / observe — buffer reads + element diagnostics. The session ring-buffer
+ * reads (console_read / network_read / ws_read / network_body), the DOM-metric
+ * sampler + window watcher, element inspection / locator generation / point
+ * probing, and the gated `eval_js` escape hatch. Registered through the shared
+ * `ToolHost` seam.
+ */
+export declare function registerReadObserveBufferTools(host: ToolHost): void;