browxai 0.7.0

package/dist/plugin/runtime.js

@@ -0,0 +1,402 @@
+// Plugin runtime — the orchestrator the server invokes at start.
+//
+// Flow:
+//   1. Read `<workspace>/plugins.json` for the declared set.
+//   2. Resolve each declared plugin's manifest off disk.
+//   3. Validate namespaces: globally unique + non-reserved.
+//   4. Validate apiVersion: each plugin's apiVersion must be compatible
+//      with this runtime's RUNTIME_API_VERSION.
+//   5. Validate dependsOn target exists + satisfies semver range.
+//   6. Build dep graph; reject cycles loudly (server start fails).
+//   7. Topo-sort load order.
+//   8. For each plugin: check declared capabilities ⊆ enabled set;
+//      on mismatch, mark plugin disabled-by-capability-mismatch and
+//      skip without aborting server start.
+//   9. Dynamic-import the entry module; call register(api).
+//   10. Per-tool: gate behind the capability the plugin declared; route
+//       through the host's existing capability gate at dispatch.
+//
+// In-process JS modules only (v1). No out-of-process plugin processes.
+// Resolved-once-at-server-start. No hot reload — restart is the contract.
+import { pathToFileURL } from "node:url";
+import { log } from "../util/logging.js";
+import { PACKAGE_VERSION } from "../util/version.js";
+import { isApiVersionCompatible, RUNTIME_API_VERSION, satisfiesRange } from "./manifest.js";
+import { pluginPaths, readDeclaration, resolveDeclaredPlugin, } from "./resolver.js";
+import { buildDepGraph, DepGraphCycleError } from "./depgraph.js";
+/** Error code emitted when a plugin's `api.callTool` violates the call graph. */
+export const PLUGIN_CALL_GRAPH_VIOLATION = "plugin-call-graph-violation";
+/**
+ * Top-level entry point: read the declaration, resolve manifests,
+ * validate the graph, load each plugin in dep-order.
+ *
+ * Throws ONLY on cycle errors (server start aborts — the contract). All
+ * other failures (capability mismatch, missing dep, validation error,
+ * load-time exception) downgrade the affected plugin to a non-loaded
+ * status and continue.
+ */
+export async function startPluginRuntime(opts) {
+    const paths = pluginPaths(opts.workspaceRoot);
+    const fromFile = readDeclaration(paths).filter((d) => d.enabled);
+    // Union with any plugins declared via the config store. The config
+    // store entry is a simple `string[]` (npm names) — file entries (which
+    // can also carry a per-entry trust override) take precedence on name
+    // collision.
+    const known = new Set(fromFile.map((d) => d.name));
+    const merged = [...fromFile];
+    for (const name of opts.extraDeclared ?? []) {
+        if (!known.has(name)) {
+            merged.push({ name, enabled: true });
+            known.add(name);
+        }
+    }
+    const declared = merged;
+    if (declared.length === 0) {
+        log.info("plugin runtime: no plugins declared", { declarationFile: paths.declarationFile });
+        return { plugins: [], toolCount: 0 };
+    }
+    // Stage 1: resolve manifests.
+    const resolved = new Map();
+    for (const decl of declared) {
+        resolved.set(decl.name, resolveDeclaredPlugin(paths, decl));
+    }
+    // Stage 2: filter to fully-resolved + validate namespace uniqueness +
+    // apiVersion + dep targets. Anything that fails is downgraded to a
+    // load-error record we'll surface at the end.
+    const earlyDisabled = [];
+    const validResolved = new Map();
+    const declaredAt = new Date().toISOString();
+    for (const [name, res] of resolved) {
+        if (res.kind === "not-installed") {
+            earlyDisabled.push({
+                manifest: {
+                    name,
+                    version: "0.0.0",
+                    path: "",
+                    entryPath: "",
+                    trust: "community",
+                    browxai: {
+                        apiVersion: "",
+                        namespace: "",
+                        register: "",
+                        capabilities: [],
+                        dependsOn: [],
+                    },
+                },
+                status: "load-error",
+                tools: [],
+                transitiveDeps: [],
+                statusReason: `not installed under ${paths.nodeModulesDir}/${name}/. Run \`browxai plugin install ${name}\` (or \`browxai plugin sync\` if the declaration was hand-edited).`,
+                declaredCapabilities: [],
+                declaredAt,
+            });
+            continue;
+        }
+        if (res.kind === "invalid-manifest") {
+            earlyDisabled.push({
+                manifest: {
+                    name,
+                    version: "0.0.0",
+                    path: "",
+                    entryPath: "",
+                    trust: "community",
+                    browxai: {
+                        apiVersion: "",
+                        namespace: "",
+                        register: "",
+                        capabilities: [],
+                        dependsOn: [],
+                    },
+                },
+                status: "load-error",
+                tools: [],
+                transitiveDeps: [],
+                statusReason: `invalid plugin manifest: ${res.error}`,
+                declaredCapabilities: [],
+                declaredAt,
+            });
+            continue;
+        }
+        validResolved.set(name, res.manifest);
+    }
+    // browxaiVersion advisory. The manifest field is the host range the
+    // plugin was tested against — a mismatch NEVER rejects loading (a
+    // conservative range must not lock out a known-good host that already
+    // shipped), but it warns loudly so the operator knows the combination
+    // is untested.
+    for (const [name, m] of validResolved) {
+        const range = m.browxai.browxaiVersion;
+        if (range && !satisfiesRange(PACKAGE_VERSION, range)) {
+            log.warn(`plugin runtime: ${name} was tested against browxai "${range}" but this host is ${PACKAGE_VERSION} — ` +
+                `untested combination (advisory only; the plugin still loads). ` +
+                `Upgrade the plugin or widen its browxaiVersion range.`);
+        }
+    }
+    // apiVersion check.
+    const apiVersionFail = [];
+    for (const [name, m] of validResolved) {
+        if (!isApiVersionCompatible(m.browxai.apiVersion, RUNTIME_API_VERSION)) {
+            apiVersionFail.push(name);
+            earlyDisabled.push({
+                manifest: m,
+                status: "load-error",
+                tools: [],
+                transitiveDeps: [],
+                statusReason: `plugin apiVersion "${m.browxai.apiVersion}" is incompatible with the host runtime apiVersion "${RUNTIME_API_VERSION}". ` +
+                    `Upgrade the plugin (or pin a host browxai version compatible with the plugin's runtime contract).`,
+                declaredCapabilities: m.browxai.capabilities,
+                declaredAt,
+            });
+        }
+    }
+    for (const n of apiVersionFail)
+        validResolved.delete(n);
+    // Namespace uniqueness.
+    const namespaceOwner = new Map();
+    const namespaceConflicts = [];
+    for (const [name, m] of validResolved) {
+        const ns = m.browxai.namespace;
+        const prior = namespaceOwner.get(ns);
+        if (prior) {
+            namespaceConflicts.push(name);
+            earlyDisabled.push({
+                manifest: m,
+                status: "disabled-by-namespace-conflict",
+                tools: [],
+                transitiveDeps: [],
+                statusReason: `namespace "${ns}" is already claimed by plugin "${prior}". Two plugins cannot share a namespace; rename one.`,
+                declaredCapabilities: m.browxai.capabilities,
+                declaredAt,
+            });
+        }
+        else {
+            namespaceOwner.set(ns, name);
+        }
+    }
+    for (const n of namespaceConflicts)
+        validResolved.delete(n);
+    // dependsOn target + version-range check.
+    const depFail = new Map();
+    for (const [name, m] of validResolved) {
+        for (const dep of m.browxai.dependsOn) {
+            const target = validResolved.get(dep.plugin);
+            if (!target) {
+                depFail.set(name, `dependsOn["${dep.plugin}"] not loaded — install or enable it.`);
+                break;
+            }
+            if (!satisfiesRange(target.version, dep.version)) {
+                depFail.set(name, `dependsOn["${dep.plugin}"] installed version ${target.version} does not satisfy range "${dep.version}".`);
+                break;
+            }
+        }
+    }
+    for (const [name, reason] of depFail) {
+        const m = validResolved.get(name);
+        earlyDisabled.push({
+            manifest: m,
+            status: "disabled-by-dep-missing",
+            tools: [],
+            transitiveDeps: [],
+            statusReason: reason,
+            declaredCapabilities: m.browxai.capabilities,
+            declaredAt,
+        });
+        validResolved.delete(name);
+    }
+    // Stage 3: build dep graph. Cycles abort startup loudly.
+    const directDeps = new Map();
+    for (const [name, m] of validResolved) {
+        directDeps.set(name, m.browxai.dependsOn.map((d) => d.plugin));
+    }
+    let depResult;
+    try {
+        depResult = buildDepGraph({ directDeps });
+    }
+    catch (e) {
+        if (e instanceof DepGraphCycleError) {
+            // Surface every cycle plugin explicitly so the operator sees the
+            // shape of the cycle, then re-throw with the structured error.
+            for (const c of e.cycles) {
+                log.error(`plugin runtime: cycle ${c.join(" → ")} → ${c[0]}`);
+            }
+            throw e;
+        }
+        throw e;
+    }
+    // Stage 4: capability subset check. Mismatched plugins get a
+    // disabled-by-capability-mismatch record + skipped.
+    const capFail = new Map();
+    for (const [name, m] of validResolved) {
+        const missing = m.browxai.capabilities.filter((c) => !opts.enabledCapabilities.has(c));
+        if (missing.length > 0) {
+            capFail.set(name, `plugin declares capabilities [${missing.join(", ")}] not enabled on this server. ` +
+                `Add them to BROWX_CAPABILITIES (or set_config({capabilities:[...]})) and RESTART. ` +
+                `Capabilities are resolved ONCE at server start — set_config alone won't enable a plugin's gate.`);
+        }
+    }
+    // Stage 5: load each plugin in dep-order.
+    // Note: skipped (capability-mismatched) plugins still consume their slot
+    // in the order — their dependents will fail later if they actually call
+    // a tool the skipped plugin owns, but the LOAD itself doesn't fail.
+    const records = [];
+    const liveTools = new Map();
+    let toolCount = 0;
+    const transitiveDeps = depResult.transitiveDeps;
+    const ownerOf = (toolName) => {
+        const t = liveTools.get(toolName);
+        if (t)
+            return t.ownerPlugin;
+        return opts.host.ownerOf(toolName);
+    };
+    for (const name of depResult.loadOrder) {
+        const m = validResolved.get(name);
+        const reason = capFail.get(name);
+        if (reason) {
+            records.push({
+                manifest: m,
+                status: "disabled-by-capability-mismatch",
+                tools: [],
+                transitiveDeps: [...(transitiveDeps.get(name) ?? new Set())],
+                statusReason: reason,
+                declaredCapabilities: m.browxai.capabilities,
+                declaredAt,
+            });
+            log.warn(`plugin runtime: ${name} disabled — ${reason}`);
+            continue;
+        }
+        const myToolNames = [];
+        const myDeps = transitiveDeps.get(name) ?? new Set();
+        const callTool = async (targetName, args) => {
+            // Core tools: always allowed (implicit-root).
+            if (opts.host.isCoreTool(targetName)) {
+                return opts.host.dispatch(targetName, args ?? {});
+            }
+            const targetOwner = ownerOf(targetName);
+            if (!targetOwner) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                ok: false,
+                                error: `plugin "${name}" tried to call unknown tool "${targetName}"`,
+                                code: PLUGIN_CALL_GRAPH_VIOLATION,
+                                fromPlugin: name,
+                                targetTool: targetName,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            // Owner-call: a plugin may always call its own tools.
+            if (targetOwner === name) {
+                return opts.host.dispatch(targetName, args ?? {});
+            }
+            // Declared-graph check.
+            if (!myDeps.has(targetOwner)) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                ok: false,
+                                error: `plugin call-graph violation: ${name} tried to call ${targetOwner}.${targetName.slice(targetName.indexOf(".") + 1)} but did not declare ${targetOwner} in dependsOn`,
+                                code: PLUGIN_CALL_GRAPH_VIOLATION,
+                                fromPlugin: name,
+                                targetPlugin: targetOwner,
+                                targetTool: targetName,
+                                declaredDeps: [...myDeps].sort(),
+                                hint: `Add { "plugin": "${targetOwner}", "version": "^${(validResolved.get(targetOwner) ?? { version: "0.0.0" }).version}" } to ` +
+                                    `the "dependsOn" array in this plugin's package.json#browxai field, reinstall (pnpm install in the plugin's repo), and restart the browxai server.`,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            return opts.host.dispatch(targetName, args ?? {});
+        };
+        const api = {
+            namespace: m.browxai.namespace,
+            declaredCapabilities: m.browxai.capabilities,
+            registerTool: (toolName, def, handler) => {
+                if (!toolName.startsWith(`${m.browxai.namespace}.`)) {
+                    throw new Error(`plugin "${name}": tool "${toolName}" must be prefixed with "${m.browxai.namespace}." — namespace prefix is mandatory. ` +
+                        `Plugins cannot override or wrap core browxai tools.`);
+                }
+                if (toolName === `${m.browxai.namespace}.`) {
+                    throw new Error(`plugin "${name}": tool name has empty suffix after the namespace — pass a real tool name like "${m.browxai.namespace}.do_thing".`);
+                }
+                if (liveTools.has(toolName) || opts.host.isCoreTool(toolName)) {
+                    throw new Error(`plugin "${name}": tool "${toolName}" is already registered. Tool names are globally unique.`);
+                }
+                // The plugin's capability is the gate for ALL its tools. The
+                // simple v1 contract — fine-grained per-tool capabilities can
+                // be layered on top later without breaking this signature.
+                // If the plugin declared more than one capability, the gate is
+                // the FIRST one (semantic: "this tool needs at least these
+                // caps"; declaring multiple is an additive claim). We pass it
+                // through to the host's gate so an MCP call against the tool
+                // refuses cleanly when the capability isn't on.
+                const cap = m.browxai.capabilities[0];
+                const record = {
+                    name: toolName,
+                    ownerPlugin: name,
+                    ...(cap !== undefined ? { capability: cap } : {}),
+                    description: def.description,
+                    ...(def.inputSchema !== undefined ? { inputSchema: def.inputSchema } : {}),
+                };
+                liveTools.set(toolName, record);
+                myToolNames.push(toolName);
+                opts.host.registerTool(toolName, def, handler, cap, name);
+            },
+            callTool,
+            log: {
+                info: (msg, meta) => log.info(`plugin[${m.browxai.namespace}]: ${msg}`, { plugin: name, ...(meta ?? {}) }),
+                warn: (msg, meta) => log.warn(`plugin[${m.browxai.namespace}]: ${msg}`, { plugin: name, ...(meta ?? {}) }),
+                error: (msg, meta) => log.error(`plugin[${m.browxai.namespace}]: ${msg}`, { plugin: name, ...(meta ?? {}) }),
+            },
+        };
+        let loaded = false;
+        let loadError;
+        try {
+            const mod = (await import(pathToFileURL(m.entryPath).href));
+            const fn = mod.register ?? mod.default;
+            if (typeof fn !== "function") {
+                throw new Error(`entry module ${m.entryPath} must export a \`register(api)\` function (named or default).`);
+            }
+            await fn(api);
+            loaded = true;
+        }
+        catch (e) {
+            loadError = e instanceof Error ? e.message : String(e);
+            log.warn(`plugin runtime: ${name} failed to load — ${loadError}`);
+        }
+        const status = loaded ? "loaded" : "load-error";
+        records.push({
+            manifest: m,
+            status,
+            tools: [...myToolNames],
+            transitiveDeps: [...myDeps].sort(),
+            ...(status === "loaded" ? {} : { statusReason: loadError ?? "unknown load error" }),
+            declaredCapabilities: m.browxai.capabilities,
+            declaredAt,
+            ...(loaded ? { enabledAt: new Date().toISOString() } : {}),
+        });
+        if (loaded)
+            toolCount += myToolNames.length;
+    }
+    return {
+        plugins: [...records, ...earlyDisabled].sort((a, b) => a.manifest.name.localeCompare(b.manifest.name)),
+        toolCount,
+    };
+}
+/**
+ * Lookup table accessor exposed for the `plugins_info` MCP tool. The
+ * runtime holds an internal `liveTools` map; the result of
+ * {@link startPluginRuntime} is the structured surface — this helper is
+ * just for callers wanting the tool registry view on a plugin.
+ */
+export function toolsForPlugin(records, pluginName) {
+    const rec = records.find((r) => r.manifest.name === pluginName);
+    return rec?.tools ?? [];
+}

package/dist/plugin/types.d.ts

@@ -0,0 +1,113 @@
+import type { z } from "zod";
+import type { ResolvedManifest } from "./manifest.js";
+/**
+ * MCP-style tool response. Same shape as the host's internal
+ * `ToolResponse` — plugin tools return this verbatim and the runtime
+ * forwards it through the MCP / SDK surface without rewriting.
+ */
+export interface PluginToolResponse {
+    readonly content: ReadonlyArray<{
+        type: "text";
+        text: string;
+    } | {
+        type: "image";
+        data: string;
+        mimeType: string;
+    }>;
+}
+/** Tool handler signature. Plugin authors implement this. */
+export type PluginToolHandler = (args: unknown) => Promise<PluginToolResponse>;
+/**
+ * The runtime API surface a plugin receives in its `register(api)` call.
+ * Stable across the runtime's API major version (`apiVersion` in the
+ * manifest).
+ */
+export interface PluginApi {
+    /** The plugin's own namespace, as declared in its manifest. */
+    readonly namespace: string;
+    /** The capabilities the plugin declared. (Already verified subset.) */
+    readonly declaredCapabilities: ReadonlyArray<string>;
+    /**
+     * Register a tool. The name MUST start with `<namespace>.` — passing
+     * anything else (or the bare namespace alone) throws synchronously.
+     *
+     *   - `name`         The full tool name (`figma.move_node`). Will appear
+     *                    on MCP `tools/list` exactly as given.
+     *   - `def`          Tool description + optional input schema. The
+     *                    schema is the same `inputSchema` shape host tools
+     *                    use — a `Record<string, z.ZodTypeAny>`. Pass an
+     *                    empty object (or omit) for argless tools.
+     *   - `handler`      Async function returning the MCP envelope. The
+     *                    runtime applies the per-tool capability gate +
+     *                    diagnostics + metrics wrapping the same as for
+     *                    core tools.
+     */
+    registerTool(name: string, def: {
+        description: string;
+        inputSchema?: Record<string, z.ZodTypeAny> | undefined;
+    }, handler: PluginToolHandler): void;
+    /**
+     * Call another tool by name (a core browxai tool or a tool registered
+     * by a plugin in this plugin's transitively-declared `dependsOn`
+     * graph). Calls outside the declared graph fail with a structured
+     * error.
+     *
+     * Capability gates fire as if the call came in from MCP — a plugin
+     * cannot call a tool whose capability isn't enabled on the host.
+     */
+    callTool(name: string, args?: Record<string, unknown>): Promise<PluginToolResponse>;
+    /**
+     * Plugin-scoped logger. Output is funnelled through the host's
+     * structured logger with `plugin=<namespace>` attached. Plugins should
+     * NOT write to stdout/stderr directly — stdout is the MCP wire.
+     */
+    log: {
+        info(msg: string, meta?: Record<string, unknown>): void;
+        warn(msg: string, meta?: Record<string, unknown>): void;
+        error(msg: string, meta?: Record<string, unknown>): void;
+    };
+}
+/**
+ * The function shape a plugin's entry module must export — either as
+ * the default export or as a named `register`.
+ */
+export type PluginRegisterFn = (api: PluginApi) => void | Promise<void>;
+/**
+ * The post-load status of one plugin. Surfaced verbatim via
+ * `plugins_list` so an operator can see why anything didn't load.
+ */
+export type PluginStatus = "loaded" | "disabled-by-capability-mismatch" | "disabled-by-cycle" | "disabled-by-dep-missing" | "disabled-by-namespace-conflict" | "load-error";
+export interface PluginRecord {
+    /** Resolved manifest (npm name, version, etc.). */
+    readonly manifest: ResolvedManifest;
+    /** Live status. */
+    readonly status: PluginStatus;
+    /** Tools registered by this plugin (`<namespace>.<tool>` names). */
+    readonly tools: ReadonlyArray<string>;
+    /** Transitive `dependsOn` closure (plugin names). */
+    readonly transitiveDeps: ReadonlyArray<string>;
+    /** Status-explainer (only populated for non-`loaded` statuses). */
+    readonly statusReason?: string;
+    /** Capabilities this plugin DECLARED. */
+    readonly declaredCapabilities: ReadonlyArray<string>;
+    /** ISO timestamp of when the manifest was read off disk. */
+    readonly declaredAt: string;
+    /** ISO timestamp of when this plugin loaded. Only set when status === "loaded". */
+    readonly enabledAt?: string;
+}
+/**
+ * Per-tool registration record — the runtime keeps one of these per
+ * plugin tool so it can route capability gating + call-graph
+ * enforcement against the right owner.
+ */
+export interface PluginToolRecord {
+    /** Full tool name (`<namespace>.<tool>`). */
+    readonly name: string;
+    /** Plugin (npm package name) that registered it. */
+    readonly ownerPlugin: string;
+    /** Capability gate for this tool (subset of the plugin's declaredCapabilities). */
+    readonly capability?: string | undefined;
+    /** Description + input schema (passed to MCP tools/list). */
+    readonly description: string;
+    readonly inputSchema?: Record<string, z.ZodTypeAny> | undefined;
+}

package/dist/plugin/types.js

@@ -0,0 +1,4 @@
+// Shared types for the plugin runtime — the surface a plugin author
+// codes against (the `register(api)` argument) and the surface the host
+// server consumes (registered tool definitions + status records).
+export {};

package/dist/policy/confirm.d.ts

@@ -0,0 +1,76 @@
+import { type OriginPolicy } from "./origin.js";
+import type { ConfirmHook } from "../util/capabilities.js";
+import type { BrowxBridge } from "../helper/bridge.js";
+export interface ConfirmContext {
+    hooks: ReadonlySet<ConfirmHook>;
+    policy: OriginPolicy;
+    bridge: BrowxBridge | null;
+    /** True iff the active session attached over CDP (BYOB). */
+    isByob: boolean;
+    /** session-scoped pre-approvals. When a scope is granted, confirm
+     *  hooks for that scope auto-approve without the page-side `__browx.confirm`
+     *  round-trip. Lets non-Claude MCP clients run unattended without a human
+     *  at DevTools to issue confirms. */
+    approvals?: ApprovalStore;
+}
+/**
+ * session-scoped pre-approvals. The non-Claude verification path
+ * surfaced that `__browx.confirm(true)` is operator-driven — a non-Claude MCP
+ * client can't drive it from inside a blocked action call. This store lets
+ * the client pre-approve confirm scopes for a TTL window. Each grant +
+ * consume is logged for audit.
+ *
+ * Pre-approval is *not* an override; the confirm hook still runs, finds the
+ * grant, and returns ok:true with `reason: "pre-approved"`. The page-side
+ * channel is the fallback when no pre-approval covers the scope.
+ */
+export declare class ApprovalStore {
+    private grants;
+    /** Grant a scope for `ttlSeconds`. Overwrites any prior grant for the same scope. */
+    grant(scope: ConfirmHook, ttlSeconds: number): void;
+    /** Revoke a previously-granted scope. Returns true if a live grant existed. */
+    revoke(scope: ConfirmHook): boolean;
+    /** Check (and consume) a grant. Returns true when an unexpired grant covers
+     *  the scope — the call is counted toward audit. Returns false (and evicts
+     *  the grant) when the grant has expired. */
+    consume(scope: ConfirmHook): boolean;
+    /** Snapshot of live grants for audit / `list_approvals` style tooling. */
+    list(): Array<{
+        scope: ConfirmHook;
+        grantedAt: number;
+        expiresAt: number;
+        uses: number;
+        remainingMs: number;
+    }>;
+}
+export interface ConfirmDecision {
+    /** Action proceeds if true. */
+    ok: boolean;
+    /** Short reason (logged). */
+    reason: string;
+    /** True iff a human confirmation was sought. */
+    asked: boolean;
+}
+/**
+ * Decide whether navigate() may proceed. If the URL is on-allowlist (or there's no
+ * allowlist), proceeds without asking. If off-allowlist:
+ *   - if `navigate_off_allowlist` is in `hooks`, asks for human confirm via the bridge;
+ *   - otherwise proceeds with a stderr warning.
+ *
+ * Returns `{ ok: false }` only when the human declined; never auto-denies (this is
+ * defense-in-depth, not a boundary).
+ */
+export declare function confirmNavigation(url: string, ctx: ConfirmContext): Promise<ConfirmDecision>;
+/**
+ * Decide whether a generic action may proceed in BYOB mode. Returns ok:true when not
+ * in BYOB, or when the hook isn't set. Otherwise blocks on human confirm.
+ *
+ * Note: this is a *coarse* gate — every action in BYOB hits it. In practice most
+ * adopters either set the hook (and confirm once per session) or omit it (and trust
+ * the BYOB attach decision they already opted into).
+ */
+export declare function confirmByobAction(toolName: string, ctx: ConfirmContext): Promise<ConfirmDecision>;
+/** Count of requests in an action window whose origin escaped the allowlist. */
+export declare function countEgressOffAllowlist(requests: Array<{
+    url: string;
+}>, policy: OriginPolicy): number;