browxai 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kalebtec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+<p align="center">
+  <a href="https://browxai.com"><img src="brand/browxai-glass-aurora-1024.png" width="116" alt="browxai" /></a>
+</p>
+
+<h1 align="center">browxai</h1>
+
+<p align="center"><strong>A browser, built for agents.</strong><br/>
+<a href="https://browxai.com">browxai.com</a> · <a href="brand/">brand kit</a></p>
+
+**An MCP-native, model-agnostic, agentic-first browser-control server for AI agents.**
+
+browxai gives an AI agent a curated, token-efficient browser surface over the
+Model Context Protocol — a tool surface designed for agents rather than for human
+developers, and headless/CI-capable. It is **engine-agnostic**: the same tool
+surface drives Chromium, Firefox, and WebKit, real Chrome-on-Android, and real
+Safari, each over the automation protocol that fits it (CDP, WebDriver BiDi,
+safaridriver) behind one capability-port seam, so a tool never knows which engine
+it is running on.
+
+It is deliberately **not** a wrapper over `@playwright/mcp`: browxai owns its own
+multi-engine transport so it can own the full session lifecycle — managed
+profiles, attach-to-an-existing browser (BYOB), authenticated sessions, headed and
+headless — and shape an agent-first surface around it.
+
+- **Model-agnostic** — any MCP client (Claude, Codex, …), not locked to one model.
+- **Engine-agnostic** — Chromium / Firefox / WebKit / Android Chrome / Safari behind one capability-port architecture; pick with `--engine` / `BROWX_ENGINE`. The default is Chromium, so nothing changes for existing setups.
+- **Token-efficient** — `snapshot()` is a compact accessibility tree + DOM-walk, not a DOM dump; results are scoped/paginated/budgeted.
+- **Safe by default** — capability-gated tools, an origin allow/blocklist, confirmation hooks, a hard anti-wedge deadline on every call. Dangerous surface (arbitrary JS, full response bodies, OS clipboard, network mocking) is off by default.
+
+## Install
+
+```bash
+npm install -g browxai
+npx playwright-core install chromium    # one-time, ~150 MB
+```
+
+Wire it into an MCP client (stdio transport) — e.g. in an `.mcp.json`:
+
+```jsonc
+{
+  "mcpServers": {
+    "browxai": { "command": "browxai" },
+  },
+}
+```
+
+## SDK (programmatic surface)
+
+For consumers that author a single TypeScript script and run it
+autonomously, browxai also ships a typed SDK. Same tool registry, same
+capability gates, same egress hygiene — different transport.
+
+```ts
+import { createBrowxai } from "browxai";
+
+const browxai = await createBrowxai(); // in-process, single-script
+await browxai.navigate({ url: "https://example.com" });
+const { data } = await browxai.extract({
+  schema: {
+    /* … */
+  },
+});
+await browxai.close();
+```
+
+Three transports:
+
+- **In-process** (default) — single Node process; the SDK drives the server
+  in-process. `close()` shuts the embedded server.
+- **Stdio child** (`transport: "stdio-child"`) — spawns the `browxai` bin as
+  a subprocess and speaks MCP-over-stdio. `close()` ends the child.
+- **Socket-attached** (`endpoint: "unix:///tmp/foo.sock"`) — connects to a
+  long-running `browxai serve --socket /tmp/foo.sock` process. Multiple
+  clients can attach to ONE server (e.g. a parent agent plus a child script
+  sharing one Chromium). `close()` ends only the local connection.
+
+Capability gates apply identically to the MCP path: posture-broadening
+tools (`eval_js`, `network_body`, `register_secret`, `upload_file`, …) are
+**off by default** and only appear on the client when their capability is
+named in `createBrowxai({ capabilities })`. Calling a non-exposed tool —
+even via `client.callTool("eval_js", …)` — fails with a
+`BROWXAI_SDK_NOT_EXPOSED` error before any wire dispatch.
+
+## Harness setup
+
+Ready-to-use setup for the common agent harnesses — MCP-server registration
+plus a portable "driving browxai well" Agent Skill — lives in
+**[`harness/`](harness/)**: [Claude Code](harness/adapters/claude-code/),
+[Codex](harness/adapters/codex/), [Pi](harness/adapters/pi/).
+
+## The surface
+
+- **`snapshot`** — compact accessibility tree + DOM-walk pass; every node gets a stable `[ref=eN]`.
+- **`find`** — natural-language query → ranked candidate locators with `selectorHint`, `stability`, visible-rect `bbox`, and an `actionable` verdict.
+- **action tools** (`click` / `fill` / `navigate` / `select` / `wait_for` / …) — each returns a structured `ActionResult`: what navigated, what structure changed, console/network slice, a post-action element probe.
+- **read tools** — `text_search`, `inspect`, `console_read`, `network_read`, `ws_read`, `screenshot`.
+- **sessions** — isolated per-session contexts (own cookie jar / refs); `persistent`, `incognito`, or `attached` (BYOB) modes; MCP-driven config.
+- **capabilities** — `read,navigation,action,human` on by default; `eval`, `network-body`, `clipboard`, `file-io`, and `byob-attach` are explicit opt-ins.
+
+Full per-tool reference, the security model, and the stability policy are in the
+**[documentation site](https://browxai.com/)**.
+
+## Stability
+
+browxai is **v0.7.0** and follows semver. The public tool surface (tool names,
+documented input/output shapes, the `ActionResult` shape, the default
+capability set) is frozen; anything behind an off-by-default capability is
+explicitly experimental and not covered by the stability guarantee. See the
+[Stability and semver](https://browxai.com/reference/tool-reference/#stability-and-semver) policy.
+
+## Develop
+
+```bash
+corepack enable && pnpm install
+pnpm install-browser     # Chromium for playwright-core
+pnpm typecheck && pnpm test
+pnpm build               # builds dist/ — the `browxai` bin is dist/cli.js
+pnpm test:keystone       # headless end-to-end keystone (real Chromium)
+pnpm docs:dev            # the documentation site, locally
+```
+
+## Project docs
+
+- [CONTRIBUTING.md](CONTRIBUTING.md) — contributor workflow + DCO.
+- [AGENTS.md](AGENTS.md) — operating rules for AI-harness contributors.
+- [SECURITY.md](SECURITY.md) — vulnerability reporting + disclosure policy.
+- [MAINTAINERS.md](MAINTAINERS.md) — maintainer roster + responsibilities.
+- [RELEASING.md](RELEASING.md) — release ritual + OIDC publish flow.
+- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) — Contributor Covenant adoption.
+
+## License
+
+Code is MIT — see [LICENSE](LICENSE).
+
+The **browxai name and logo are trademarks of Kalebtec** and are not
+covered by the MIT License. The brand assets under [`brand/`](brand/)
+are all-rights-reserved (see [`brand/LICENSE`](brand/LICENSE)). See
+[TRADEMARKS.md](TRADEMARKS.md) for the full brand policy and what
+nominative use is allowed.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,45 @@
+# Third-party notices
+
+browxai is distributed under the MIT license (see [`LICENSE`](LICENSE)).
+The published packages depend on the following third-party software.
+
+## `browxai` (host package)
+
+Direct production dependencies:
+
+- **`@modelcontextprotocol/sdk`** — MIT.
+  Copyright Anthropic, PBC.
+  <https://github.com/modelcontextprotocol/typescript-sdk>
+- **`playwright-core`** — Apache-2.0.
+  Copyright Microsoft Corporation.
+  <https://github.com/microsoft/playwright>
+  (ships its own `NOTICE` file, installed alongside the package)
+- **`zod`** — MIT.
+  Copyright Colin McDonnell.
+  <https://github.com/colinhacks/zod>
+
+These packages pull in their own (transitive) production dependencies;
+every package in the installed tree carries its license text at
+`node_modules/<name>/LICENSE` (or `LICENSE.md`/`LICENSE.txt`), and the
+`pnpm licenses:check` CI gate restricts the production tree to the
+allowlist `MIT / Apache-2.0 / BSD-2-Clause / BSD-3-Clause / ISC / 0BSD /
+Unlicense / CC0-1.0`. A machine-readable inventory (CycloneDX SBOM,
+`sbom.cdx.json`) is attached to every GitHub Release.
+
+The optional `pnpm install-browser` step downloads Chromium via
+`playwright-core`; Chromium is licensed under the BSD-3-Clause license
+and bundles its own third-party notices (`chrome://credits`).
+
+## `@browxai/plugin-example`, `@browxai/plugin-figma`, `@browxai/plugin-tldraw`, `@browxai/plugin-excalidraw`
+
+No production dependencies — the host provides the plugin runtime API.
+The canvas adapter plugins (`figma`, `tldraw`, `excalidraw`) drive the
+respective web applications through the browser; they do not bundle or
+link any code from those applications.
+
+---
+
+This file is reviewed on every production-dependency change.
+`pnpm licenses:check` gates the production tree against the license
+allowlist in CI; `pnpm licenses:notices` prints the raw per-package
+inventory (name, license, repository, publisher) for review.

package/dist/cli/chrome.d.ts

@@ -0,0 +1 @@
+export declare function runChrome(args: string[]): Promise<number>;

package/dist/cli/chrome.js

@@ -0,0 +1,130 @@
+// `browxai chrome start|stop` — own the `--cdp` Chrome lifecycle ().
+//
+// Launches a Chromium with `--remote-debugging-port=9222 --user-data-dir=$BROWX_WORKSPACE/chrome-profile`
+// (the right flags every time; profile in the workspace so logins survive across sessions)
+// and writes the PID to `$BROWX_WORKSPACE/chrome.pid`. `stop` reads the PID file and
+// SIGTERMs the process; cleans up. Stdout is fine — this is a CLI subcommand.
+//
+// The launched Chromium is the *BYOB target* an adopter would `BROWX_ATTACH_CDP=…`
+// against. browxai itself does NOT attach to it from `chrome start` — start the
+// MCP server separately (the `browxai-attached` MCP entry) once Chrome is up.
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { chromium } from "playwright-core";
+import { resolveWorkspace } from "../util/workspace.js";
+const DEFAULT_PORT = 9222;
+export async function runChrome(args) {
+    const sub = args[0];
+    if (sub === "start")
+        return startChrome(args.slice(1));
+    if (sub === "stop")
+        return stopChrome();
+    if (sub === "status")
+        return statusChrome();
+    process.stderr.write("usage: browxai chrome <start [--port N] [--insecure] | stop | status>\n");
+    return 2;
+}
+function startChrome(opts) {
+    const port = parseFlagNum(opts, "--port") ?? DEFAULT_PORT;
+    const insecure = opts.includes("--insecure"); // opt-in security-lowered (BYOB recipe's `--disable-web-security`)
+    const ws = resolveWorkspace();
+    const profileDir = ws.sub("chrome-profile");
+    const pidFile = join(ws.root, "chrome.pid");
+    if (existsSync(pidFile)) {
+        const oldPid = readFileSync(pidFile, "utf8").trim();
+        if (oldPid && isProcessAlive(Number(oldPid))) {
+            process.stdout.write(`a previous browxai chrome is already running (pid ${oldPid}, port ${port}). Use \`browxai chrome stop\` first.\n`);
+            return Promise.resolve(1);
+        }
+        unlinkSync(pidFile);
+    }
+    const chromePath = chromium.executablePath();
+    if (!chromePath) {
+        process.stderr.write("no Chromium binary — run `pnpm install-browser` first\n");
+        return Promise.resolve(1);
+    }
+    const args = [
+        `--remote-debugging-port=${port}`,
+        `--user-data-dir=${profileDir}`,
+        "--no-first-run",
+        "--no-default-browser-check",
+    ];
+    if (insecure) {
+        args.push("--disable-web-security", "--disable-site-isolation-trials");
+        process.stdout.write("⚠  --insecure: launching Chrome with --disable-web-security. SOP is OFF for the whole browser session. Use only against test/dev targets.\n");
+    }
+    const child = spawn(chromePath, args, { detached: true, stdio: "ignore" });
+    child.unref();
+    if (!child.pid) {
+        process.stderr.write("failed to spawn Chrome\n");
+        return Promise.resolve(1);
+    }
+    writeFileSync(pidFile, String(child.pid), "utf8");
+    process.stdout.write(`browxai chrome started\n  pid:     ${child.pid}\n  port:    ${port}\n  profile: ${profileDir}\n  attach:  BROWX_ATTACH_CDP=http://127.0.0.1:${port}\n\nstop with: browxai chrome stop\n`);
+    return Promise.resolve(0);
+}
+async function stopChrome() {
+    const ws = resolveWorkspace();
+    const pidFile = join(ws.root, "chrome.pid");
+    if (!existsSync(pidFile)) {
+        process.stdout.write("no browxai chrome running (no chrome.pid in workspace)\n");
+        return 0;
+    }
+    const pid = Number(readFileSync(pidFile, "utf8").trim());
+    if (!pid || !isProcessAlive(pid)) {
+        unlinkSync(pidFile);
+        process.stdout.write(`browxai chrome (pid ${pid}) no longer running; cleaned up pid file\n`);
+        return 0;
+    }
+    try {
+        process.kill(pid, "SIGTERM");
+        // Give it a beat; if it's still alive, SIGKILL.
+        await sleep(800);
+        if (isProcessAlive(pid))
+            process.kill(pid, "SIGKILL");
+        unlinkSync(pidFile);
+        process.stdout.write(`browxai chrome (pid ${pid}) stopped\n`);
+        return 0;
+    }
+    catch (e) {
+        process.stderr.write(`failed to stop pid ${pid}: ${e instanceof Error ? e.message : String(e)}\n`);
+        return 1;
+    }
+}
+function statusChrome() {
+    const ws = resolveWorkspace();
+    const pidFile = join(ws.root, "chrome.pid");
+    if (!existsSync(pidFile)) {
+        process.stdout.write("no browxai chrome running (no chrome.pid in workspace)\n");
+        return Promise.resolve(0);
+    }
+    const pid = Number(readFileSync(pidFile, "utf8").trim());
+    if (pid && isProcessAlive(pid)) {
+        process.stdout.write(`browxai chrome running (pid ${pid})\n`);
+        return Promise.resolve(0);
+    }
+    process.stdout.write(`pid ${pid} no longer alive; run \`browxai chrome stop\` to clean up\n`);
+    return Promise.resolve(1);
+}
+function isProcessAlive(pid) {
+    if (!pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function parseFlagNum(args, flag) {
+    const i = args.indexOf(flag);
+    if (i < 0)
+        return undefined;
+    const v = Number(args[i + 1]);
+    return Number.isFinite(v) ? v : undefined;
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}

package/dist/cli/command-registry.d.ts

@@ -0,0 +1,15 @@
+/** A subcommand handler: receives the argv after the subcommand token, returns
+ *  the process exit code. */
+export type CommandHandler = (rest: string[]) => Promise<number>;
+/** Register a subcommand handler. Add-only: a new command is one
+ *  `registerCommand(...)` call, never a new `case` in `cli.ts`. */
+export declare function registerCommand(name: string, handler: CommandHandler): void;
+/** Resolve a subcommand handler, or `undefined` when the token is not a
+ *  registered subcommand (the caller then applies the literal `--version` /
+ *  `--help` / `--engine` / server-fallthrough rules — the same precedence the
+ *  old `switch` encoded by case order). */
+export declare function commandFor(name: string): CommandHandler | undefined;
+/** The registered subcommand names, in registration order — used by `cli.ts`'s
+ *  unknown-subcommand diagnostic so the "Valid: …" list stays in lockstep with
+ *  the registry (no second hand-maintained list to drift). */
+export declare function registeredCommands(): string[];

package/dist/cli/command-registry.js

@@ -0,0 +1,35 @@
+// CLI subcommand registry (RFC 0004 P4 / D6) — the add-only
+// `Map<string, CommandHandler>` that replaces the extensibility arms of the
+// `switch (subcommand)` in `src/cli.ts`.
+//
+// Scope: this registry owns the EXTENSIBILITY subcommands — the ones a future
+// command would be added alongside (`doctor` / `chrome` / `init` / `serve` /
+// `plugin`). The `--version` / `--help` literal fast paths and the
+// `undefined` / `--engine` server-fallthrough stay inline in `cli.ts`: they are
+// not "another subcommand", they are the bin's own argv shape (a help flag and
+// the default server path), so registry-ifying them would be miscategorising a
+// fixed CLI contract as an open extension point.
+//
+// Each handler takes the post-subcommand argv (`rest`) and returns the process
+// exit code, exactly as the old `runDoctor()` / `runChrome(rest)` / ... calls
+// did. The dispatcher resolves the SAME handler the `case` did — `cli.ts`
+// behavior (`browxai doctor`, `browxai plugin …`, etc.) is unchanged.
+const COMMANDS = new Map();
+/** Register a subcommand handler. Add-only: a new command is one
+ *  `registerCommand(...)` call, never a new `case` in `cli.ts`. */
+export function registerCommand(name, handler) {
+    COMMANDS.set(name, handler);
+}
+/** Resolve a subcommand handler, or `undefined` when the token is not a
+ *  registered subcommand (the caller then applies the literal `--version` /
+ *  `--help` / `--engine` / server-fallthrough rules — the same precedence the
+ *  old `switch` encoded by case order). */
+export function commandFor(name) {
+    return COMMANDS.get(name);
+}
+/** The registered subcommand names, in registration order — used by `cli.ts`'s
+ *  unknown-subcommand diagnostic so the "Valid: …" list stays in lockstep with
+ *  the registry (no second hand-maintained list to drift). */
+export function registeredCommands() {
+    return [...COMMANDS.keys()];
+}

package/dist/cli/doctor-plugins.d.ts

@@ -0,0 +1,18 @@
+import type { Check } from "./doctor.js";
+import type { Capability } from "../util/capabilities.js";
+export interface PluginChecksOptions {
+    /** Workspace root (`resolveWorkspace().root`). */
+    readonly workspaceRoot: string;
+    /** The capability set doctor resolved (mirrors the server's gate input). */
+    readonly enabledCapabilities: ReadonlySet<Capability>;
+    /** Extra plugin names declared via the config store
+     *  (`set_config({plugins})`) — unioned with `plugins.json` exactly the
+     *  way `startPluginRuntime` unions them. File entries win on collision. */
+    readonly extraDeclared?: ReadonlyArray<string>;
+}
+/**
+ * Build the doctor checks for the plugin surface. Pure inspection — reads
+ * the declaration, the lock, and installed `package.json` manifests; never
+ * executes plugin code.
+ */
+export declare function pluginChecks(opts: PluginChecksOptions): Check[];