browxai 0.7.0

package/dist/sdk/transport-in-process.js

@@ -0,0 +1,44 @@
+// In-process transport: drives the MCP server's `handlers` map directly in
+// the same Node process. This is the SDK default — no subprocess, no IPC,
+// no socket. Egress hygiene (URL sanitizer, `<SECRET_NAME>` substitution,
+// capability gates, session isolation) is the SAME code path the MCP
+// transport runs, because `handlers[name]` IS the wrapped registered
+// handler — gate + sanitiser inclusive (see register() in src/server.ts).
+import { createServer } from "../server.js";
+import { parseEnvelope } from "./transport.js";
+import { registerTransport } from "./transport-registry.js";
+/**
+ * Construct an in-process transport. The factory `await`s the underlying
+ * `createServer()` (which does NOT start the MCP stdio loop — `server.start()`
+ * is what does that, and the SDK never calls it) so the returned transport
+ * is immediately ready to dispatch.
+ */
+export async function openInProcessTransport(opts = {}) {
+    const server = await createServer(opts);
+    const handlers = server.handlers;
+    let closed = false;
+    const dispatch = async (toolName, args) => {
+        if (closed)
+            throw new Error(`browxai-sdk: dispatch on a closed transport (tool=${toolName})`);
+        const fn = handlers[toolName];
+        if (!fn) {
+            throw new Error(`browxai-sdk: unknown tool "${toolName}" — not registered on the in-process server. ` +
+                `Either the tool name is wrong or the SDK's tool registry is out of sync with server.ts.`);
+        }
+        const result = await fn(args);
+        return parseEnvelope(result.content);
+    };
+    const close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        await server.shutdown().catch(() => undefined);
+    };
+    return { dispatch, close };
+}
+// RFC 0004 P4 / D6 — self-register under the "in-process" mode. The factory maps
+// the SDK options to this opener's argument shape EXACTLY as the old
+// `case "in-process"` arm did (`{ attachCdp, headless }`).
+registerTransport("in-process", {
+    open: (opts) => openInProcessTransport({ attachCdp: opts.attachCdp, headless: opts.headless }),
+});

package/dist/sdk/transport-registry.d.ts

@@ -0,0 +1,19 @@
+import type { BrowxaiSdkOptions } from "./types.js";
+import type { SdkTransport } from "./transport.js";
+/** The transport selector — derived from the real SDK option union so the
+ *  registry key stays in lockstep with the public surface (a new option value
+ *  is a compile error here until a factory is registered for it). */
+export type TransportMode = NonNullable<BrowxaiSdkOptions["transport"]>;
+/** One transport's construction surface. `open` receives the full SDK options
+ *  and reads only the fields its transport needs — the same mapping the old
+ *  `switch` arm performed inline. */
+export interface TransportFactory {
+    open(opts: BrowxaiSdkOptions): Promise<SdkTransport>;
+}
+/** Register a transport factory under its mode. Add-only: each transport file
+ *  registers itself once at module load, so the composition root never edits a
+ *  central conditional to add one. */
+export declare function registerTransport(mode: TransportMode, factory: TransportFactory): void;
+/** Resolve + open the transport for `mode`. Throws the same structured error the
+ *  old `default` arm did when the mode is unknown (no registered factory). */
+export declare function openTransport(mode: TransportMode, opts: BrowxaiSdkOptions): Promise<SdkTransport>;

package/dist/sdk/transport-registry.js

@@ -0,0 +1,31 @@
+// SDK transport registry (RFC 0004 P4 / D6) — the add-only `Map<TransportMode,
+// TransportFactory>` that replaces the `switch (mode)` in `createBrowxai`.
+//
+// The `SdkTransport` PORT (src/sdk/transport.ts) was already proven — three real
+// implementations drive it (in-process / stdio-child / socket). The only piece
+// that was a switch is the SELECTION: which factory builds the transport for a
+// given `opts.transport`. This registry resolves the SAME factory each `case`
+// did, so a fourth transport becomes a `registerTransport(...)` call in its own
+// transport file rather than a new `case` in the composition root — and the
+// dependency-cruiser layering rule keeps `createBrowxai` from growing per-
+// transport imports.
+//
+// Behavior-preservation: `openTransport(mode, opts)` constructs the transport
+// with the EXACT argument shape the old `case` passed (the socket endpoint guard
+// included), so `sdk.keystone.test.ts` drives all three transports unchanged.
+const TRANSPORTS = new Map();
+/** Register a transport factory under its mode. Add-only: each transport file
+ *  registers itself once at module load, so the composition root never edits a
+ *  central conditional to add one. */
+export function registerTransport(mode, factory) {
+    TRANSPORTS.set(mode, factory);
+}
+/** Resolve + open the transport for `mode`. Throws the same structured error the
+ *  old `default` arm did when the mode is unknown (no registered factory). */
+export function openTransport(mode, opts) {
+    const factory = TRANSPORTS.get(mode);
+    if (!factory) {
+        throw new Error(`browxai-sdk: unknown transport "${String(mode)}"`);
+    }
+    return factory.open(opts);
+}

package/dist/sdk/transport-socket.d.ts

@@ -0,0 +1,12 @@
+import { type SdkTransport } from "./transport.js";
+/**
+ * Translate the SDK-public endpoint URL into a Node `net.connect` path. The
+ * scheme namespace is intentionally small so a typo (e.g. `tcp://`) fails
+ * loudly rather than silently mis-routing.
+ */
+export declare function resolveEndpointPath(endpoint: string): string;
+export interface SocketTransportOptions {
+    /** SDK-public endpoint URL — see resolveEndpointPath above. */
+    readonly endpoint: string;
+}
+export declare function openSocketTransport(opts: SocketTransportOptions): Promise<SdkTransport>;

package/dist/sdk/transport-socket.js

@@ -0,0 +1,77 @@
+// Endpoint-attached transport: connect to an already-running browxai server
+// over a Unix domain socket (macOS/Linux) or a Windows named pipe. The wire
+// protocol is MCP-over-newline-delimited-JSON, byte-identical to stdio.
+//
+// Endpoint formats accepted:
+//   unix:///absolute/path/to/sock     — Unix domain socket (mac/Linux)
+//   pipe://./pipe/<name>              — Windows named pipe (\\.\pipe\<name>)
+//
+// The SDK does NOT own the server lifecycle on this path. `close()` ends the
+// local connection only. The server is expected to have been launched
+// out-of-band by the operator (e.g. `browxai serve --socket /tmp/foo.sock`).
+import { createConnection } from "node:net";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { NAME, VERSION } from "../server.js";
+import { SocketTransport } from "./socket-transport.js";
+import { parseEnvelope } from "./transport.js";
+import { registerTransport } from "./transport-registry.js";
+/**
+ * Translate the SDK-public endpoint URL into a Node `net.connect` path. The
+ * scheme namespace is intentionally small so a typo (e.g. `tcp://`) fails
+ * loudly rather than silently mis-routing.
+ */
+export function resolveEndpointPath(endpoint) {
+    if (endpoint.startsWith("unix://")) {
+        const path = endpoint.slice("unix://".length);
+        if (!path)
+            throw new Error(`browxai-sdk: invalid endpoint "${endpoint}" — empty unix:// path`);
+        return path;
+    }
+    if (endpoint.startsWith("pipe://")) {
+        // pipe://./pipe/foo  →  \\.\pipe\foo  (Windows named-pipe convention)
+        const tail = endpoint.slice("pipe://".length).replace(/^\.\//, "");
+        if (!tail)
+            throw new Error(`browxai-sdk: invalid endpoint "${endpoint}" — empty pipe:// path`);
+        return `\\\\.\\${tail.replace(/\//g, "\\")}`;
+    }
+    throw new Error(`browxai-sdk: unsupported endpoint scheme in "${endpoint}". ` +
+        `Supported: unix:///path/to/sock, pipe://./pipe/name. Other schemes are rejected so a typo fails loudly.`);
+}
+export async function openSocketTransport(opts) {
+    const path = resolveEndpointPath(opts.endpoint);
+    const socket = await new Promise((resolve, reject) => {
+        const s = createConnection({ path }, () => resolve(s));
+        s.once("error", (err) => reject(err));
+    });
+    const transport = new SocketTransport(socket);
+    const client = new Client({ name: `${NAME}-sdk`, version: VERSION }, { capabilities: {} });
+    await client.connect(transport);
+    let closed = false;
+    const dispatch = async (toolName, args) => {
+        if (closed)
+            throw new Error(`browxai-sdk: dispatch on a closed transport (tool=${toolName})`);
+        const res = await client.callTool({ name: toolName, arguments: args });
+        const content = res.content ?? [];
+        return parseEnvelope(content);
+    };
+    const close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        await client.close().catch(() => undefined);
+    };
+    return { dispatch, close };
+}
+// RFC 0004 P4 / D6 — self-register under the "socket" mode. The factory carries
+// the endpoint guard the old `case "socket"` arm enforced inline: a socket
+// transport REQUIRES `opts.endpoint`, and the structured error message is
+// byte-identical to the prior switch arm.
+registerTransport("socket", {
+    open: (opts) => {
+        if (!opts.endpoint) {
+            throw new Error(`browxai-sdk: transport "socket" requires an \`endpoint\`. ` +
+                `Set { endpoint: "unix:///path/to/sock" } (or pipe://./pipe/<name> on Windows).`);
+        }
+        return openSocketTransport({ endpoint: opts.endpoint });
+    },
+});

package/dist/sdk/transport-stdio-child.d.ts

@@ -0,0 +1,10 @@
+import { type SdkTransport } from "./transport.js";
+export interface StdioChildOptions {
+    /** Defaults to "browxai" — the bin entrypoint. Override for local dev. */
+    readonly command?: string;
+    readonly args?: ReadonlyArray<string>;
+    readonly env?: Record<string, string>;
+    /** Optional cwd for the spawned child. */
+    readonly cwd?: string;
+}
+export declare function openStdioChildTransport(opts?: StdioChildOptions): Promise<SdkTransport>;

package/dist/sdk/transport-stdio-child.js

@@ -0,0 +1,47 @@
+// Stdio-child transport: spawn the `browxai` CLI as a subprocess and speak
+// MCP-over-stdio to it via the MCP SDK's `StdioClientTransport`. Owns the
+// child lifecycle — `close()` ends the subprocess.
+//
+// This is the right transport when the caller wants OS-level process
+// isolation (e.g. crash containment, capability isolation via per-child
+// env). Egress hygiene + capability gates still hold: the child runs the
+// SAME server code path; the wire just carries the post-sanitisation
+// content array.
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { parseEnvelope } from "./transport.js";
+import { registerTransport } from "./transport-registry.js";
+import { NAME, VERSION } from "../server.js";
+export async function openStdioChildTransport(opts = {}) {
+    const transport = new StdioClientTransport({
+        command: opts.command ?? "browxai",
+        args: opts.args ? [...opts.args] : [],
+        env: opts.env,
+        cwd: opts.cwd,
+        // Surface child stderr to the parent so a misconfiguration is visible.
+        stderr: "inherit",
+    });
+    const client = new Client({ name: `${NAME}-sdk`, version: VERSION }, { capabilities: {} });
+    await client.connect(transport);
+    let closed = false;
+    const dispatch = async (toolName, args) => {
+        if (closed)
+            throw new Error(`browxai-sdk: dispatch on a closed transport (tool=${toolName})`);
+        const res = await client.callTool({ name: toolName, arguments: args });
+        const content = res.content ?? [];
+        return parseEnvelope(content);
+    };
+    const close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        await client.close().catch(() => undefined);
+    };
+    return { dispatch, close };
+}
+// RFC 0004 P4 / D6 — self-register under the "stdio-child" mode. The factory maps
+// the SDK options to this opener's argument shape EXACTLY as the old
+// `case "stdio-child"` arm did (`{ command, args, env }`).
+registerTransport("stdio-child", {
+    open: (opts) => openStdioChildTransport({ command: opts.command, args: opts.args, env: opts.env }),
+});

package/dist/sdk/transport.d.ts

@@ -0,0 +1,10 @@
+import type { BrowxaiContentItem, BrowxaiResult } from "./types.js";
+/** Lower-level transport contract. One method, idempotent close. */
+export interface SdkTransport {
+    /** Dispatch a single tool call and return the SDK envelope. */
+    dispatch(toolName: string, args: Record<string, unknown>): Promise<BrowxaiResult>;
+    /** Tear down the transport. Idempotent. */
+    close(): Promise<void>;
+}
+/** Parse the first text item of an MCP content array as JSON, when applicable. */
+export declare function parseEnvelope(content: ReadonlyArray<BrowxaiContentItem>): BrowxaiResult;

package/dist/sdk/transport.js

@@ -0,0 +1,35 @@
+// SDK transport interface — abstracts the wire between the SDK client and
+// the browxai server. The single method is `dispatch(toolName, args)`: a
+// tool name + JSON args → an MCP-shaped `{ content }` envelope. Three
+// implementations exist:
+//
+//   1. InProcessTransport (src/sdk/transport-in-process.ts) — drives the
+//      server's `handlers` map directly. No subprocess, no socket. Owns the
+//      server lifecycle (`close` calls `server.shutdown()`).
+//
+//   2. StdioChildTransport (src/sdk/transport-stdio-child.ts) — spawns
+//      `browxai` as a child process and speaks MCP-over-stdio to it via the
+//      MCP SDK's StdioClientTransport. Owns the child lifecycle.
+//
+//   3. SocketTransport (src/sdk/transport-socket.ts) — attaches to an
+//      already-running browxai server over a Unix socket (or named pipe on
+//      Windows). The SDK does NOT own the server lifecycle; `close()` only
+//      tears down the local connection.
+/** Parse the first text item of an MCP content array as JSON, when applicable. */
+export function parseEnvelope(content) {
+    for (const item of content) {
+        if (item && item.type === "text") {
+            try {
+                const parsed = JSON.parse(item.text);
+                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                    return { content, data: parsed };
+                }
+            }
+            catch {
+                /* not JSON — a snapshot tree or other plain-text payload */
+            }
+            return { content };
+        }
+    }
+    return { content };
+}

package/dist/sdk/types.d.ts

@@ -0,0 +1,176 @@
+import type { Capability } from "../util/capabilities.js";
+import type { AwaitHumanArgs, AwaitHumanResult, ChooseOptionArgs, ChooseOptionResult, ClickArgs, ClickResult, CloseSessionArgs, CloseSessionResult, CloseSessionsArgs, CloseSessionsResult, ConsoleReadArgs, ConsoleReadResult, ExecuteArgs, ExecuteResult, ExtractArgs, ExtractResult, FillArgs, FillFormArgs, FillFormResult, FillResult, FindArgs, FindResult, FramesListArgs, FramesListResult, GenerateLocatorArgs, GenerateLocatorResult, GoBackArgs, GoBackResult, GoForwardArgs, GoForwardResult, HoverArgs, HoverResult, InspectArgs, InspectResult, ListSessionsArgs, ListSessionsResult, NameRefArgs, NameRefResult, NavigateArgs, NavigateResult, NetworkReadArgs, NetworkReadResult, OpenSessionArgs, OpenSessionResult, PlanArgs, PlanResult, PressArgs, PressResult, ScreenshotArgs, ScreenshotResult, ScrollArgs, ScrollResult, SelectArgs, SelectResult, SetViewportArgs, SetViewportResult, SnapshotArgs, SnapshotResult, TextSearchArgs, TextSearchResult, VerifyAttributeArgs, VerifyCountArgs, VerifyPredicateArgs, VerifyResult, VerifyTextArgs, VerifyValueArgs, VerifyVisibleArgs, WaitForArgs, WaitForResult, WsReadArgs, WsReadResult } from "./tool-types.js";
+/** Discriminated content item the SDK forwards from MCP results. */
+export type BrowxaiContentItem = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+/**
+ * Standard SDK result envelope. Mirrors the MCP `{ content: [...] }` shape
+ * 1:1 so adopters who already think in MCP terms keep their mental model.
+ * `data` is a convenience: when the first text item is parseable JSON, it is
+ * surfaced here so callers do not have to JSON.parse content[0].text by hand.
+ */
+export interface BrowxaiResult<T = Record<string, unknown>> {
+    /** Raw MCP content items — preserves images, multi-item results, etc. */
+    readonly content: ReadonlyArray<BrowxaiContentItem>;
+    /** Parsed JSON object from the first text item, when applicable. */
+    readonly data?: T;
+}
+/** Argument shape: an open record. Per-tool field names match the MCP `inputSchema`. */
+export type BrowxaiArgs = Record<string, unknown>;
+/**
+ * Options for {@link createBrowxai}.
+ */
+export interface BrowxaiSdkOptions {
+    /**
+     * Endpoint of a running browxai server to attach to.
+     *
+     * - `unix:///path/to/sock` — Unix domain socket on macOS/Linux.
+     * - `pipe://./pipe/name` — Windows named pipe.
+     * - When omitted, the SDK runs the server in-process (single Node process,
+     *   no subprocess, no socket) — appropriate for tests and single-script
+     *   automation. To force a child-process posture, set `transport: "stdio-child"`.
+     *
+     * Other schemes are rejected at `createBrowxai()` time with a clear error.
+     */
+    readonly endpoint?: string;
+    /**
+     * Transport selector. Default behaviour:
+     *   - if `endpoint` set         → "socket"
+     *   - if `endpoint` unset       → "in-process"
+     * Set `"stdio-child"` to spawn a `browxai` child process and speak MCP-over-
+     * stdio to it; this is the right choice when the caller wants OS-level
+     * process isolation but does not want to manage a long-lived server.
+     */
+    readonly transport?: "in-process" | "stdio-child" | "socket";
+    /**
+     * Path to the browxai CLI when using `stdio-child`. Defaults to the
+     * `browxai` bin on `PATH`.
+     */
+    readonly command?: string;
+    /** Extra args for the `stdio-child` command. */
+    readonly args?: ReadonlyArray<string>;
+    /** Environment overrides for the spawned child (stdio-child only). */
+    readonly env?: Record<string, string>;
+    /**
+     * Default session id to bind action calls to. When unset, every call
+     * resolves to the lazy "default" session — same posture as the MCP path's
+     * omitted-`session` field.
+     */
+    readonly session?: string;
+    /**
+     * Capability set the SDK is allowed to expose. Defaults to the server's
+     * default set (read + navigation + action + human). Posture-broadening
+     * capabilities (`eval`, `network-body`, `secrets`, `file-io`,
+     * `byob-attach`, `extensions`, `stealth`, `captcha`, `credentials`,
+     * `clipboard`) remain off-by-default — name them here to opt in.
+     *
+     * Two enforcement layers consult this set:
+     *   1. The registry walker filters which methods are visible on the client.
+     *   2. {@link BrowxaiClient.callTool} refuses unknown / off-capability tools
+     *      at runtime so a `(client as any).eval_js({...})` escape hatch still
+     *      fails closed.
+     */
+    readonly capabilities?: ReadonlyArray<Capability>;
+    /**
+     * Config overrides applied to the in-process server. Same shape as the
+     * MCP `ConfigStore` resolve patch — for the `stdio-child` and `socket`
+     * transports the option is ignored (server-side config wins).
+     */
+    readonly config?: Record<string, unknown>;
+    /**
+     * Run the in-process server headless. Ignored for `stdio-child` and
+     * `socket` transports (those rely on the server-side launch flags).
+     */
+    readonly headless?: boolean;
+    /**
+     * Attach-to-an-existing-Chrome endpoint, passed through to the in-process
+     * server. Requires the `byob-attach` capability.
+     */
+    readonly attachCdp?: string;
+}
+/**
+ * The driver returned by {@link createBrowxai}. Every method is a typed
+ * 1:1 wrapper over the matching MCP tool — args are forwarded, results are
+ * the SDK envelope (raw content + parsed-JSON convenience field).
+ */
+export interface BrowxaiClient {
+    snapshot(args?: SnapshotArgs): Promise<SnapshotResult>;
+    find(args: FindArgs): Promise<FindResult>;
+    frames_list(args?: FramesListArgs): Promise<FramesListResult>;
+    screenshot(args?: ScreenshotArgs): Promise<ScreenshotResult>;
+    console_read(args?: ConsoleReadArgs): Promise<ConsoleReadResult>;
+    network_read(args?: NetworkReadArgs): Promise<NetworkReadResult>;
+    ws_read(args?: WsReadArgs): Promise<WsReadResult>;
+    inspect(args: InspectArgs): Promise<InspectResult>;
+    text_search(args: TextSearchArgs): Promise<TextSearchResult>;
+    extract(args: ExtractArgs): Promise<ExtractResult>;
+    verify_visible(args: VerifyVisibleArgs): Promise<VerifyResult>;
+    verify_text(args: VerifyTextArgs): Promise<VerifyResult>;
+    verify_value(args: VerifyValueArgs): Promise<VerifyResult>;
+    verify_count(args: VerifyCountArgs): Promise<VerifyResult>;
+    verify_attribute(args: VerifyAttributeArgs): Promise<VerifyResult>;
+    verify_predicate(args: VerifyPredicateArgs): Promise<VerifyResult>;
+    generate_locator(args: GenerateLocatorArgs): Promise<GenerateLocatorResult>;
+    plan(args: PlanArgs): Promise<PlanResult>;
+    navigate(args: NavigateArgs): Promise<NavigateResult>;
+    go_back(args?: GoBackArgs): Promise<GoBackResult>;
+    go_forward(args?: GoForwardArgs): Promise<GoForwardResult>;
+    scroll(args: ScrollArgs): Promise<ScrollResult>;
+    set_viewport(args: SetViewportArgs): Promise<SetViewportResult>;
+    click(args: ClickArgs): Promise<ClickResult>;
+    fill(args: FillArgs): Promise<FillResult>;
+    press(args: PressArgs): Promise<PressResult>;
+    shortcut(args: BrowxaiArgs): Promise<BrowxaiResult>;
+    hover(args: HoverArgs): Promise<HoverResult>;
+    select(args: SelectArgs): Promise<SelectResult>;
+    choose_option(args: ChooseOptionArgs): Promise<ChooseOptionResult>;
+    fill_form(args: FillFormArgs): Promise<FillFormResult>;
+    wait_for(args: WaitForArgs): Promise<WaitForResult>;
+    execute(args: ExecuteArgs): Promise<ExecuteResult>;
+    await_human(args: AwaitHumanArgs): Promise<AwaitHumanResult>;
+    name_ref(args: NameRefArgs): Promise<NameRefResult>;
+    open_session(args: OpenSessionArgs): Promise<OpenSessionResult>;
+    close_session(args: CloseSessionArgs): Promise<CloseSessionResult>;
+    close_sessions(args?: CloseSessionsArgs): Promise<CloseSessionsResult>;
+    list_sessions(args?: ListSessionsArgs): Promise<ListSessionsResult>;
+    /**
+     * Typed escape hatch for adopters that want to call a tool by name (for
+     * example, capability-gated tools opted in via `capabilities`). The
+     * registry walker still applies — calling a tool whose capability is not
+     * in `opts.capabilities` rejects with a clear `BROWXAI_SDK_NOT_EXPOSED`
+     * error. This is the layer that closes the `(client as any).eval_js(...)`
+     * escape hole: even unrestricted runtime indexing must round-trip through
+     * `callTool`, where the gate fires.
+     */
+    callTool(name: string, args?: BrowxaiArgs): Promise<BrowxaiResult>;
+    /**
+     * namespaced caller for plugin-registered tools. Indexed
+     * twice: `client.plugins.<namespace>.<tool>(args)`. The wrapper
+     * round-trips through {@link BrowxaiClient.callTool}, so
+     * capability gating + the call-graph enforcement applied at the
+     * server still fire.
+     *
+     * The default type is intentionally permissive — plugin authors
+     * ship typed `.d.ts` overlays so consumers get `client.plugins.figma.moveNode`
+     * autocomplete. Cast through `BrowxaiClientWithPlugins<Schema>`
+     * (see docs/plugin-authoring.md) to enable the typed path.
+     */
+    readonly plugins: Record<string, Record<string, (args?: BrowxaiArgs) => Promise<BrowxaiResult>>>;
+    /** Names of every MCP tool currently exposed on this client. */
+    readonly exposedTools: ReadonlyArray<string>;
+    /** Capability set currently in effect on this client. */
+    readonly capabilities: ReadonlySet<Capability>;
+    /** Default session id every method binds to when `args.session` is omitted. */
+    readonly session: string | undefined;
+    /**
+     * Close the session + (when applicable) terminate the spawned server.
+     * Idempotent — a second call resolves to `undefined` immediately.
+     */
+    close(): Promise<void>;
+}

package/dist/sdk/types.js

@@ -0,0 +1,10 @@
+// Public type surface for `browxai` SDK consumers. Argument /
+// result shapes are deliberately structural (`Record<string, unknown>` /
+// `BrowxaiResult`) so the SDK does not have to re-mirror every Zod schema
+// the MCP server already owns — the source of truth for input shape is the
+// `inputSchema` of each registered MCP tool, and the source of truth for
+// output shape is the documented per-tool reference (see
+// `docs/tool-reference.md`). The SDK's job is to (a) restrict the visible
+// surface to stable + capability-permitted tools and (b) preserve the egress
+// hygiene the MCP path enforces — NOT to re-author every per-tool schema.
+export {};

package/dist/server.d.ts

@@ -0,0 +1,33 @@
+import { type EngineKind } from "./engine/index.js";
+import "./tools/tool-metadata.js";
+import { SESSION_ARG, TIMEOUT_ARG, ACTION_OPTS, REF_OR_SELECTOR } from "./tools/schemas.js";
+export declare const NAME = "browxai";
+export declare const VERSION: string;
+export interface StartOptions {
+    attachCdp?: string;
+    headless?: boolean;
+    /** Browser engine for sessions this server launches. Defaults to
+     *  `"chromium"`. chromium, firefox, and webkit are all wired today (see
+     *  src/engine/); a future-declared engine without an adapter is rejected at
+     *  the launch path with a clear `engine-not-yet-supported` error. */
+    browserType?: EngineKind;
+}
+export { SESSION_ARG, TIMEOUT_ARG, ACTION_OPTS, REF_OR_SELECTOR };
+export declare function createServer(opts?: StartOptions): Promise<{
+    start: () => Promise<void>;
+    shutdown: () => Promise<void>;
+    /** Programmatic in-process driving seam: the registered MCP tool handlers,
+     *  keyed by tool name, each returning the same `{ content: [...] }` shape an
+     *  MCP call would. Used by the headless-CI keystone (and any embedder that
+     *  wants to drive the surface without the stdio transport). */
+    handlers: Record<string, (args: unknown) => Promise<{
+        content: Array<{
+            type: "text";
+            text: string;
+        } | {
+            type: "image";
+            data: string;
+            mimeType: string;
+        }>;
+    }>>;
+}>;