browxai 0.7.0

package/dist/policy/confirm.js

@@ -0,0 +1,162 @@
+// Confirmation hooks —  policy. Routes potentially-irreversible operations
+// through `await_human({kind:"confirm"})` before they dispatch. See `docs/threat-model.md`
+// "The capability set" → confirm_required.
+//
+// Hooks defined:
+//   - navigate_off_allowlist: navigate() to a URL outside BROWX_ALLOWED_ORIGINS
+//   - byob_action: any action while attached over BROWX_ATTACH_CDP
+//   - file_download / file_upload: (slot reserved; future tools)
+//
+// Configuring via env: BROWX_CONFIRM_REQUIRED (handled in src/util/capabilities.ts).
+import { isOriginAllowed } from "./origin.js";
+import { log } from "../util/logging.js";
+/**
+ * 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 class ApprovalStore {
+    grants = new Map();
+    /** Grant a scope for `ttlSeconds`. Overwrites any prior grant for the same scope. */
+    grant(scope, ttlSeconds) {
+        const ttl = Math.max(1, Math.floor(ttlSeconds));
+        const expiresAt = Date.now() + ttl * 1000;
+        this.grants.set(scope, { expiresAt, grantedAt: Date.now(), uses: 0 });
+        log.info(`approve_actions: scope="${scope}" ttl=${ttl}s expires=${new Date(expiresAt).toISOString()}`);
+    }
+    /** Revoke a previously-granted scope. Returns true if a live grant existed. */
+    revoke(scope) {
+        const had = this.grants.delete(scope);
+        if (had)
+            log.info(`approve_actions: revoked scope="${scope}"`);
+        return had;
+    }
+    /** 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) {
+        const grant = this.grants.get(scope);
+        if (!grant)
+            return false;
+        if (Date.now() > grant.expiresAt) {
+            this.grants.delete(scope);
+            log.info(`approve_actions: scope="${scope}" expired`);
+            return false;
+        }
+        grant.uses++;
+        return true;
+    }
+    /** Snapshot of live grants for audit / `list_approvals` style tooling. */
+    list() {
+        const now = Date.now();
+        const out = [];
+        for (const [scope, grant] of this.grants) {
+            if (now > grant.expiresAt)
+                continue;
+            out.push({
+                scope,
+                grantedAt: grant.grantedAt,
+                expiresAt: grant.expiresAt,
+                uses: grant.uses,
+                remainingMs: grant.expiresAt - now,
+            });
+        }
+        return out;
+    }
+}
+/**
+ * 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 async function confirmNavigation(url, ctx) {
+    if (isOriginAllowed(url, ctx.policy)) {
+        return { ok: true, reason: "on-allowlist", asked: false };
+    }
+    if (!ctx.hooks.has("navigate_off_allowlist")) {
+        log.warn(`navigate: ${url} is off the allowed-origins list; no confirm hook set, proceeding`);
+        return { ok: true, reason: "off-allowlist; no hook", asked: false };
+    }
+    if (ctx.approvals?.consume("navigate_off_allowlist")) {
+        return { ok: true, reason: "pre-approved", asked: false };
+    }
+    if (!ctx.bridge) {
+        // No bridge means no way to confirm — fail closed.
+        return {
+            ok: false,
+            reason: "off-allowlist; no helper bridge to confirm; blocked",
+            asked: false,
+        };
+    }
+    log.info(`confirm navigate (off-allowlist): ${url} — call __browx.confirm(true) to proceed`);
+    try {
+        const sig = await ctx.bridge.awaitSignal("respond", 5 * 60_000);
+        const value = sig.data && typeof sig.data === "object" && "value" in sig.data
+            ? sig.data.value
+            : sig.data;
+        return value === true
+            ? { ok: true, reason: "human-approved", asked: true }
+            : { ok: false, reason: "human-declined", asked: true };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            reason: `confirm timed out / failed: ${e instanceof Error ? e.message : String(e)}`,
+            asked: true,
+        };
+    }
+}
+/**
+ * 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 async function confirmByobAction(toolName, ctx) {
+    if (!ctx.isByob)
+        return { ok: true, reason: "not byob", asked: false };
+    if (!ctx.hooks.has("byob_action")) {
+        return { ok: true, reason: "byob; no confirm hook", asked: false };
+    }
+    if (ctx.approvals?.consume("byob_action")) {
+        return { ok: true, reason: "pre-approved", asked: false };
+    }
+    if (!ctx.bridge) {
+        return { ok: false, reason: "byob; no helper bridge to confirm; blocked", asked: false };
+    }
+    log.info(`confirm byob ${toolName} — call __browx.confirm(true) to proceed`);
+    try {
+        const sig = await ctx.bridge.awaitSignal("respond", 5 * 60_000);
+        const value = sig.data && typeof sig.data === "object" && "value" in sig.data
+            ? sig.data.value
+            : sig.data;
+        return value === true
+            ? { ok: true, reason: "human-approved", asked: true }
+            : { ok: false, reason: "human-declined", asked: true };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            reason: `confirm timed out / failed: ${e instanceof Error ? e.message : String(e)}`,
+            asked: true,
+        };
+    }
+}
+/** Count of requests in an action window whose origin escaped the allowlist. */
+export function countEgressOffAllowlist(requests, policy) {
+    if (policy.allowed.length === 0)
+        return 0;
+    return requests.filter((r) => !isOriginAllowed(r.url, policy)).length;
+}

package/dist/policy/origin.d.ts

@@ -0,0 +1,17 @@
+export interface OriginPolicy {
+    /** Empty allowlist = no restriction ( default). */
+    readonly allowed: ReadonlyArray<OriginPattern>;
+    /** Blocked overrides allowed: an origin in `blocked` returns false even if in `allowed`. */
+    readonly blocked: ReadonlyArray<OriginPattern>;
+}
+export interface OriginPattern {
+    /** The original string, kept for error messages. */
+    raw: string;
+    /** Pre-compiled matcher: protocol exact, host wildcard-aware. */
+    test(originUrl: URL): boolean;
+}
+export declare function resolveOriginPolicy(env?: NodeJS.ProcessEnv): OriginPolicy;
+/** Returns true iff the URL is *allowed* under the policy (and not blocked). */
+export declare function isOriginAllowed(url: string | URL, policy: OriginPolicy): boolean;
+/** Pretty-print for startup log. */
+export declare function describePolicy(policy: OriginPolicy): string;

package/dist/policy/origin.js

@@ -0,0 +1,79 @@
+// Origin allow/blocklist —  defense-in-depth gate (NOT a security boundary).
+// See `docs/threat-model.md` for the framing: this is a blast-radius reducer + a hook
+// point for confirmation prompts, *not* a guarantee that off-allowlist requests can't
+// happen (page-initiated redirects, JS-driven nav, BYOB-mode etc. can still escape).
+//
+// Configuring:
+//   BROWX_ALLOWED_ORIGINS=https://app.example.com,https://api.example.com,https://*.cdn.example.com
+//   BROWX_BLOCKED_ORIGINS=https://*.tracking.example.com,https://ads.example.com
+export function resolveOriginPolicy(env = process.env) {
+    const allowed = parseList(env.BROWX_ALLOWED_ORIGINS?.trim() ?? "");
+    const blocked = parseList(env.BROWX_BLOCKED_ORIGINS?.trim() ?? "");
+    return { allowed, blocked };
+}
+function parseList(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map(parsePattern);
+}
+function parsePattern(raw) {
+    // Accept `https://app.example.com`, `https://*.example.com`, `http://localhost:3000`.
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`origin policy: invalid URL "${raw}". Expected e.g. "https://app.example.com".`);
+    }
+    const protocol = url.protocol;
+    const hostPattern = url.hostname;
+    const port = url.port; // may be ""
+    const isWild = hostPattern.startsWith("*.");
+    const wildSuffix = isWild ? hostPattern.slice(1) : ""; // ".example.com" for "*.example.com"
+    const test = (candidate) => {
+        if (candidate.protocol !== protocol)
+            return false;
+        if (port && candidate.port && candidate.port !== port)
+            return false;
+        if (isWild) {
+            // Match exact suffix domain or sub-domain (not the bare suffix itself).
+            return (candidate.hostname.endsWith(wildSuffix) && candidate.hostname.length > wildSuffix.length);
+        }
+        return candidate.hostname === hostPattern;
+    };
+    return { raw, test };
+}
+/** Returns true iff the URL is *allowed* under the policy (and not blocked). */
+export function isOriginAllowed(url, policy) {
+    const parsed = typeof url === "string" ? safeUrl(url) : url;
+    if (!parsed)
+        return false; // unparseable URLs aren't trusted
+    if (policy.blocked.some((p) => p.test(parsed)))
+        return false;
+    if (policy.allowed.length === 0)
+        return true; // no allowlist = no restriction
+    return policy.allowed.some((p) => p.test(parsed));
+}
+function safeUrl(s) {
+    try {
+        return new URL(s);
+    }
+    catch {
+        return null;
+    }
+}
+/** Pretty-print for startup log. */
+export function describePolicy(policy) {
+    if (policy.allowed.length === 0 && policy.blocked.length === 0)
+        return "(none)";
+    const bits = [];
+    if (policy.allowed.length)
+        bits.push(`allowed=[${policy.allowed.map((p) => p.raw).join(", ")}]`);
+    if (policy.blocked.length)
+        bits.push(`blocked=[${policy.blocked.map((p) => p.raw).join(", ")}]`);
+    return bits.join(" ");
+}

package/dist/sdk/client.d.ts

@@ -0,0 +1,21 @@
+import { type Capability } from "../util/capabilities.js";
+import type { SdkTransport } from "./transport.js";
+import type { BrowxaiClient } from "./types.js";
+/** Error message tag used by the SDK boundary's runtime gate. Tested by the
+ *  capability-enforcement spec. Stable string — adopters can match on it. */
+export declare const NOT_EXPOSED_ERROR = "BROWXAI_SDK_NOT_EXPOSED";
+export interface BuildClientOptions {
+    readonly transport: SdkTransport;
+    readonly capabilities: ReadonlySet<Capability>;
+    readonly session?: string;
+}
+/**
+ * Build a BrowxaiClient over a ready transport. Method-name → MCP-tool-name
+ * is 1:1 (the registry walker emits a wrapper per stable tool); a thin
+ * `callTool(name, args)` escape hatch exists for typed-but-unwrapped tools
+ * (notably the capability-gated ones).
+ */
+export declare function buildClient(opts: BuildClientOptions): BrowxaiClient;
+/** Default capability set when the caller did not pass one. Mirrors the MCP
+ *  server defaults (read + navigation + action + human). */
+export declare function defaultSdkCapabilities(): ReadonlySet<Capability>;

package/dist/sdk/client.js

@@ -0,0 +1,174 @@
+// BrowxaiClient implementation. The exposed-method walker, the capability
+// gate filter at the SDK boundary, and the typed `callTool` escape hatch
+// all live here.
+import { DEFAULT_CAPABILITIES } from "../util/capabilities.js";
+import { ALWAYS_EXPOSED, SDK_TOOLS, capabilityFor } from "./registry.js";
+/** Error message tag used by the SDK boundary's runtime gate. Tested by the
+ *  capability-enforcement spec. Stable string — adopters can match on it. */
+export const NOT_EXPOSED_ERROR = "BROWXAI_SDK_NOT_EXPOSED";
+/**
+ * Build a BrowxaiClient over a ready transport. Method-name → MCP-tool-name
+ * is 1:1 (the registry walker emits a wrapper per stable tool); a thin
+ * `callTool(name, args)` escape hatch exists for typed-but-unwrapped tools
+ * (notably the capability-gated ones).
+ */
+export function buildClient(opts) {
+    const { transport, capabilities, session } = opts;
+    // The set of tool names this SDK instance will expose. The walker runs
+    // ONCE at construction; runtime `callTool` re-checks against the same set
+    // so even `(client as any).fooBar` indexing cannot bypass the gate.
+    const exposed = new Set();
+    for (const name of SDK_TOOLS) {
+        if (ALWAYS_EXPOSED.has(name)) {
+            exposed.add(name);
+            continue;
+        }
+        const cap = capabilityFor(name);
+        // `human` capability is implicit — it's always on. Otherwise the cap
+        // must be in the SDK's opted-in set for the tool to be exposed.
+        if (cap === "human" || capabilities.has(cap)) {
+            exposed.add(name);
+        }
+    }
+    let closed = false;
+    /** Apply the session default + dispatch. */
+    const dispatch = async (toolName, args) => {
+        if (closed)
+            throw new Error(`browxai-sdk: ${toolName} called on a closed client`);
+        const merged = { ...(args ?? {}) };
+        if (session !== undefined && merged.session === undefined) {
+            merged.session = session;
+        }
+        return transport.dispatch(toolName, merged);
+    };
+    /** Runtime gate — the immutable barrier for capability-gated tools. */
+    const callTool = async (name, args) => {
+        if (!exposed.has(name)) {
+            const cap = capabilityFor(name);
+            const error = new Error(`${NOT_EXPOSED_ERROR}: tool "${name}" is not exposed on this SDK client. ` +
+                `Required capability: "${cap}". Active capabilities: [${[...capabilities].join(", ")}]. ` +
+                `Pass it in \`createBrowxai({ capabilities: ["${cap}"] })\` to opt in. ` +
+                `Posture-broadening capabilities (eval / network-body / secrets / file-io / extensions / stealth / captcha / credentials / clipboard / byob-attach) are OFF-by-default by design — same posture as the MCP server's capability gates.`);
+            throw error;
+        }
+        return dispatch(name, args);
+    };
+    // Per-tool wrappers — typed methods listed in BrowxaiClient. Each forwards
+    // through `dispatch` for exposed tools, or refuses early via the same
+    // walker check used by `callTool`. We emit ALL the typed methods (every
+    // SDK_TOOLS name) regardless of exposure: when a capability is off, the
+    // method exists at the type level but throws BROWXAI_SDK_NOT_EXPOSED at
+    // call time. This makes `client.eval_js?.(...)` a tractable refactor when
+    // the operator later opts the capability in.
+    //
+    // The runtime wrapper is intentionally `(args?: BrowxaiArgs) => …` — the
+    // dispatch path is shape-agnostic. The per-tool TypeScript signatures
+    // declared on `BrowxaiClient` specialise this at the type layer only; the
+    // cast below assigns one generic factory output to each typed slot without
+    // duplicating the wrapper N times.
+    // The runtime fn signature is uniform; the per-method TS signatures on
+    // `BrowxaiClient` narrow it. `<F>` lets each call site project the wrapper
+    // into the exact typed slot without per-method duplication.
+    const guarded = (toolName) => (async (args) => callTool(toolName, args));
+    // namespaced caller for plugin tools. Every tool the
+    // server exposes whose name contains a `.` is a plugin tool; the
+    // client surfaces it lazily under `client.plugins[namespace][tool]`
+    // so an adopter can write `client.plugins.figma.moveNode({...})`
+    // without manually round-tripping through `callTool`.
+    //
+    // The plugin tools an SDK client sees are sourced from the
+    // transport's introspection: at construction time the SDK doesn't
+    // know which plugin tools the server has registered (the in-process
+    // transport COULD inspect the handler map, but for parity with
+    // socket/stdio-child we defer to a lazy first-access pattern —
+    // every namespaced access just dispatches via `callTool`, which
+    // round-trips to the server and surfaces a clear error if the tool
+    // doesn't exist).
+    const plugins = new Proxy({}, {
+        get(_target, namespace) {
+            if (typeof namespace !== "string")
+                return undefined;
+            return new Proxy({}, {
+                get(_t2, toolName) {
+                    if (typeof toolName !== "string")
+                        return undefined;
+                    return (args) => 
+                    // Mirror tool naming: `namespace.tool`. Convert camelCase
+                    // tool name back to snake_case? No — the SDK uses the
+                    // tool name as-is. Plugin authors declare e.g.
+                    // `figma.move_node` AND `figma.moveNode`'s caller hits
+                    // `figma.moveNode` — so the JS-style access maps 1:1 to
+                    // whatever the plugin registered. Plugin authors who
+                    // want snake_case at the wire and camelCase at the JS
+                    // level can ship a `.d.ts` wrapper (documented).
+                    callTool(`${namespace}.${toolName}`, args);
+                },
+            });
+        },
+    });
+    const client = {
+        // read
+        snapshot: guarded("snapshot"),
+        find: guarded("find"),
+        frames_list: guarded("frames_list"),
+        screenshot: guarded("screenshot"),
+        console_read: guarded("console_read"),
+        network_read: guarded("network_read"),
+        ws_read: guarded("ws_read"),
+        inspect: guarded("inspect"),
+        text_search: guarded("text_search"),
+        extract: guarded("extract"),
+        verify_visible: guarded("verify_visible"),
+        verify_text: guarded("verify_text"),
+        verify_value: guarded("verify_value"),
+        verify_count: guarded("verify_count"),
+        verify_attribute: guarded("verify_attribute"),
+        verify_predicate: guarded("verify_predicate"),
+        generate_locator: guarded("generate_locator"),
+        plan: guarded("plan"),
+        // navigation
+        navigate: guarded("navigate"),
+        go_back: guarded("go_back"),
+        go_forward: guarded("go_forward"),
+        scroll: guarded("scroll"),
+        set_viewport: guarded("set_viewport"),
+        // action
+        click: guarded("click"),
+        fill: guarded("fill"),
+        press: guarded("press"),
+        shortcut: guarded("shortcut"),
+        hover: guarded("hover"),
+        select: guarded("select"),
+        choose_option: guarded("choose_option"),
+        fill_form: guarded("fill_form"),
+        wait_for: guarded("wait_for"),
+        execute: guarded("execute"),
+        // coordination
+        await_human: guarded("await_human"),
+        name_ref: guarded("name_ref"),
+        // session lifecycle
+        open_session: guarded("open_session"),
+        close_session: guarded("close_session"),
+        close_sessions: guarded("close_sessions"),
+        list_sessions: guarded("list_sessions"),
+        // escape hatch + introspection
+        callTool,
+        exposedTools: [...exposed].sort(),
+        capabilities,
+        session,
+        // namespaced plugin caller (proxy-based; see comment above).
+        plugins,
+        close: async () => {
+            if (closed)
+                return;
+            closed = true;
+            await transport.close();
+        },
+    };
+    return client;
+}
+/** Default capability set when the caller did not pass one. Mirrors the MCP
+ *  server defaults (read + navigation + action + human). */
+export function defaultSdkCapabilities() {
+    return new Set([...DEFAULT_CAPABILITIES]);
+}

package/dist/sdk/index.d.ts

@@ -0,0 +1,32 @@
+import "../tools/tool-metadata.js";
+import "./transport-in-process.js";
+import "./transport-socket.js";
+import "./transport-stdio-child.js";
+import type { BrowxaiClient, BrowxaiSdkOptions } from "./types.js";
+export type { BrowxaiArgs, BrowxaiClient, BrowxaiContentItem, BrowxaiResult, BrowxaiSdkOptions, } from "./types.js";
+export type { ActionOpts, ActionResult, ActionResultData, Coords, RefTarget, SessionArg, SnapshotMode, Stability, Target, TimeoutArg, BBox, ChooseOptionArgs, ChooseOptionResult, ConsoleReadArgs, ConsoleReadResult, ConsoleReadResultData, ConsoleRow, ExtractArgs, ExtractEvidence, ExtractFail, ExtractOk, ExtractResult, ExtractResultData, FindArgs, FindCandidate, FindCandidateContext, FindResult, FindResultData, FrameInfo, FramesListArgs, FramesListData, FramesListResult, GenerateLocatorArgs, GenerateLocatorFail, GenerateLocatorOk, GenerateLocatorResult, GenerateLocatorResultData, InspectArgs, InspectResult, InspectResultData, LocatorComponent, NetworkReadArgs, NetworkReadResult, NetworkReadResultData, NetworkRequestRow, ScreenshotArgs, ScreenshotResult, SnapshotArgs, SnapshotResult, TextSearchArgs, TextSearchMatch, TextSearchResult, TextSearchResultData, VerifyAttributeArgs, VerifyCountArgs, VerifyFail, VerifyFailure, VerifyOk, VerifyPredicateArgs, VerifyResult, VerifyResultData, VerifyTextArgs, VerifyValueArgs, VerifyVisibleArgs, WsFrame, WsReadArgs, WsReadResult, WsReadResultData, ActionDescriptor, ExecuteArgs, ExecuteResult, PlanArgs, PlanFail, PlanOk, PlanResult, PlanResultData, PlanVerb, PlanVerbArgs, ClickArgs, ClickResult, FillArgs, FillFormArgs, FillFormFieldArg, FillFormResult, FillFormSubmitArg, FillResult, GoBackArgs, GoBackResult, GoForwardArgs, GoForwardResult, HoverArgs, HoverResult, NavigateArgs, NavigateResult, PressArgs, PressResult, ScrollArgs, ScrollResult, SelectArgs, SelectResult, SetViewportArgs, SetViewportResult, WaitForArgs, WaitForResult, AwaitHumanArgs, AwaitHumanResult, AwaitHumanResultData, CloseSessionArgs, CloseSessionResult, CloseSessionResultData, CloseSessionsArgs, CloseSessionsResult, CloseSessionsResultData, ListSessionsArgs, ListSessionsResult, ListSessionsResultData, ListSessionsRow, NameRefArgs, NameRefResult, NameRefResultData, OpenSessionArgs, OpenSessionResult, OpenSessionResultData, SessionMode, Actionable, EvalJsArgs, EvalJsFail, EvalJsOk, EvalJsResult, EvalJsResultData, NetworkBodyArgs, NetworkBodyResult, NetworkBodyResultData, RegisterSecretArgs, RegisterSecretResult, RegisterSecretResultData, UploadFileArgs, UploadFileResult, UploadFileResultData, } from "./tool-types.js";
+export { NOT_EXPOSED_ERROR } from "./client.js";
+export { resolveEndpointPath } from "./transport-socket.js";
+export type { BrowxaiClientWithPlugins, PluginSchema } from "./plugin-types.js";
+/**
+ * Create a typed `BrowxaiClient`. The transport is chosen by these rules:
+ *
+ *   1. `opts.transport === "socket"` OR `opts.endpoint` set → socket-attach
+ *      to a running browxai server. Endpoint scheme MUST be `unix://` or
+ *      `pipe://`; other schemes are rejected. SDK does NOT own the server
+ *      lifecycle on this path.
+ *
+ *   2. `opts.transport === "stdio-child"` → spawn `browxai` (or the command
+ *      given via `opts.command`) as a child process and speak MCP-over-stdio.
+ *      SDK owns the child lifecycle; `close()` ends it.
+ *
+ *   3. Otherwise → run the server in-process. SDK owns the lifecycle;
+ *      `close()` calls `server.shutdown()`.
+ *
+ * In every mode the capability set passed in `opts.capabilities` is
+ * authoritative for which methods are exposed AND callable on the returned
+ * client (see `buildClient`). Posture-broadening capabilities (`eval`,
+ * `network-body`, `secrets`, `file-io`, `extensions`, `stealth`, `captcha`,
+ * `credentials`, `clipboard`, `byob-attach`) remain off-by-default.
+ */
+export declare function createBrowxai(opts?: BrowxaiSdkOptions): Promise<BrowxaiClient>;

package/dist/sdk/index.js

@@ -0,0 +1,61 @@
+// browxai SDK — typed programmatic surface over the same tool registry the
+// MCP path exposes. See docs/sdk.md (or src/sdk/types.ts) for the public
+// types, and `test/sdk/` for executable specs.
+//
+// Mental model: a `BrowxaiClient` is a thin, typed driver over ONE of three
+// transports. Whichever transport the caller picks, every dispatch goes
+// through the same server-side handler registry, so capability gates, the
+// URL sanitiser, the `<SECRET_NAME>` substitution, and per-session isolation
+// are enforced once at the server and trusted by the SDK.
+// RFC 0004 P2 / D1 (SECURITY-CRITICAL): the SDK client's capability gate
+// (`buildClient` → `capabilityFor` → `TOOL_CAPABILITY`) reads the derived map.
+// The SOCKET transport never calls `createServer`, so without this side-effect
+// import the gate would read an empty (fail-open) map. Importing the bootstrap
+// here EAGERLY populates the derived maps for every `createBrowxai` transport —
+// the SDK entry is one of the four real entry points the bootstrap guarantees.
+import "../tools/tool-metadata.js";
+import { buildClient, defaultSdkCapabilities } from "./client.js";
+// Importing the three transport modules runs their side-effect
+// `registerTransport(...)` calls (RFC 0004 P4 / D6), populating the transport
+// registry below. `createBrowxai` then dispatches through `openTransport`
+// rather than a `switch (mode)` — a fourth transport is add-only.
+import "./transport-in-process.js";
+import "./transport-socket.js";
+import "./transport-stdio-child.js";
+import { openTransport } from "./transport-registry.js";
+export { NOT_EXPOSED_ERROR } from "./client.js";
+export { resolveEndpointPath } from "./transport-socket.js";
+/**
+ * Create a typed `BrowxaiClient`. The transport is chosen by these rules:
+ *
+ *   1. `opts.transport === "socket"` OR `opts.endpoint` set → socket-attach
+ *      to a running browxai server. Endpoint scheme MUST be `unix://` or
+ *      `pipe://`; other schemes are rejected. SDK does NOT own the server
+ *      lifecycle on this path.
+ *
+ *   2. `opts.transport === "stdio-child"` → spawn `browxai` (or the command
+ *      given via `opts.command`) as a child process and speak MCP-over-stdio.
+ *      SDK owns the child lifecycle; `close()` ends it.
+ *
+ *   3. Otherwise → run the server in-process. SDK owns the lifecycle;
+ *      `close()` calls `server.shutdown()`.
+ *
+ * In every mode the capability set passed in `opts.capabilities` is
+ * authoritative for which methods are exposed AND callable on the returned
+ * client (see `buildClient`). Posture-broadening capabilities (`eval`,
+ * `network-body`, `secrets`, `file-io`, `extensions`, `stealth`, `captcha`,
+ * `credentials`, `clipboard`, `byob-attach`) remain off-by-default.
+ */
+export async function createBrowxai(opts = {}) {
+    const capabilities = opts.capabilities && opts.capabilities.length
+        ? new Set([...opts.capabilities])
+        : defaultSdkCapabilities();
+    const mode = opts.transport ?? (opts.endpoint ? "socket" : "in-process");
+    // Resolve the transport via the add-only registry. `openTransport` returns the
+    // SAME transport the old `switch (mode)` constructed for each mode (the per-
+    // transport argument mapping + the socket endpoint guard now live in each
+    // transport file's `registerTransport(...)`), and throws the same structured
+    // error for an unknown mode.
+    const transport = await openTransport(mode, opts);
+    return buildClient({ transport, capabilities, session: opts.session });
+}

package/dist/sdk/plugin-types.d.ts

@@ -0,0 +1,33 @@
+import type { BrowxaiArgs, BrowxaiClient, BrowxaiResult } from "./types.js";
+/**
+ * The lattice plugin authors implement. Each top-level key is a
+ * plugin namespace; each inner key is a tool name; each inner value is
+ * a function-returning-promise. Intentionally permissive — concrete
+ * plugin schemas are typed precisely while composed types
+ * (intersections of multiple plugin schemas) stay assignable.
+ */
+export type PluginSchema = Record<string, Record<string, (...args: never[]) => Promise<BrowxaiResult>>>;
+export type _PluginSchemaArgs = BrowxaiArgs;
+/**
+ * A {@link BrowxaiClient} typed against a composition of one or more
+ * plugin schemas. Use at the point you `createBrowxai()` — the runtime
+ * surface is unchanged; this only widens the `plugins` namespace at
+ * the type layer.
+ *
+ *   import type { FigmaPlugin } from "@browxai/plugin-figma";
+ *   import type { ExamplePlugin } from "@browxai/plugin-example";
+ *
+ *   type Schema = FigmaPlugin & ExamplePlugin;
+ *
+ *   const client = (await createBrowxai({...})) as BrowxaiClientWithPlugins<Schema>;
+ *   await client.plugins.figma.moveNode({nodeId: "n1", dx: 10, dy: 20});
+ *   await client.plugins.example.echo({msg: "hi"});
+ *
+ * The type parameter is intentionally unconstrained — interface
+ * schemas (which lack TS's "string index signature") still compose
+ * cleanly. The runtime is shape-agnostic; the typing layer just
+ * widens the `plugins` namespace.
+ */
+export type BrowxaiClientWithPlugins<P> = Omit<BrowxaiClient, "plugins"> & {
+    readonly plugins: P & BrowxaiClient["plugins"];
+};

package/dist/sdk/plugin-types.js

@@ -0,0 +1,22 @@
+// typed SDK seam for plugin tools.
+//
+// Plugin authors ship a TypeScript declaration shaped like:
+//
+//   export interface MyPluginSchema {
+//     readonly figma: {
+//       moveNode(args: { nodeId: string; dx: number; dy: number }): Promise<BrowxaiResult>;
+//       resizeNode(args: { nodeId: string; width: number; height: number }): Promise<BrowxaiResult>;
+//     };
+//   }
+//
+// Consumers compose multiple plugin schemas via the {@link
+// BrowxaiClientWithPlugins} helper and get full autocomplete on every
+// plugin tool — `client.plugins.figma.moveNode({nodeId, dx, dy})` —
+// while the underlying runtime still rides the same `callTool`
+// dispatch path the in-process / socket / stdio-child transports use.
+//
+// The typing surface is purely additive — passing zero schemas leaves
+// the plugin caller as the permissive
+// `Record<string, Record<string, (args?) => Promise<BrowxaiResult>>>`
+// from {@link BrowxaiClient.plugins}.
+export {};

package/dist/sdk/registry.d.ts

@@ -0,0 +1,17 @@
+import { type Capability } from "../util/capabilities.js";
+/** Tools the SDK exposes as typed methods on `BrowxaiClient`. */
+export declare const SDK_TOOLS: readonly ["snapshot", "find", "screenshot", "console_read", "network_read", "ws_read", "inspect", "text_search", "extract", "verify_visible", "verify_text", "verify_value", "verify_count", "verify_attribute", "verify_predicate", "generate_locator", "plan", "navigate", "go_back", "go_forward", "scroll", "set_viewport", "click", "fill", "press", "shortcut", "hover", "select", "choose_option", "fill_form", "wait_for", "execute", "await_human", "name_ref", "open_session", "close_session", "close_sessions", "list_sessions", "eval_js", "network_body", "upload_file", "register_secret", "diagnostics_note", "diagnostics_search", "diagnostics_report"];
+export type SdkToolName = (typeof SDK_TOOLS)[number];
+/**
+ * Tool → capability lookup the SDK uses to decide which methods to expose.
+ * Pulled from the same `TOOL_CAPABILITY` map the MCP server uses so the two
+ * paths cannot drift.
+ */
+export declare function capabilityFor(tool: string): Capability | "human";
+/**
+ * SDK methods always exposed regardless of capability set — these are the
+ * coordination / session-management primitives whose capability is `human`
+ * (always-enabled by the server) plus the SDK lifecycle method itself.
+ * Used by the registry walker to short-circuit the gate check.
+ */
+export declare const ALWAYS_EXPOSED: ReadonlySet<string>;