agent-browser-priv 0.27.3-priv.8 → 0.28.0-priv.2

package/README.md

@@ -74,6 +74,12 @@ agent-browser upgrade
 
 Detects your installation method (npm, Homebrew, or Cargo) and runs the appropriate update command automatically.
 
+`agent-browser doctor` reports the installed Patchright backend version, the
+Patchright version pinned by the current `agent-browser` release, and npm latest
+when network checks are enabled. Patchright updates are release-controlled:
+after upgrading `agent-browser`, run `agent-browser install` to refresh the
+backend to the version pinned by that release.
+
 ### Requirements
 
 - **Patchright backend** - Run `agent-browser install` to install pinned Patchright and its browser artifacts for the default local backend. Requires Node.js and npm for install and runtime launch.
@@ -468,6 +474,7 @@ agent-browser upgrade                 # Upgrade agent-browser to the latest vers
 agent-browser doctor                  # Diagnose the install and auto-clean stale daemon files
 agent-browser doctor --fix            # Also run destructive repairs
 agent-browser doctor --offline --quick  # Skip network probes and the live launch test
+agent-browser mcp                     # Start an MCP stdio server
 ```
 
 `doctor` checks your environment, browser backend install, daemon state,
@@ -488,6 +495,74 @@ agent-browser skills path [name]      # Print skill directory path
 
 Serves bundled skill content that always matches the installed CLI version. AI agents use this to get current instructions rather than relying on cached copies. Set `AGENT_BROWSER_SKILLS_DIR` to override the skills directory path.
 
+### MCP Server
+
+```bash
+agent-browser mcp
+agent-browser mcp --tools all
+agent-browser mcp --tools core,network,react
+```
+
+Starts a Model Context Protocol server over stdio. MCP clients launch this command as a subprocess and exchange newline-delimited JSON-RPC on stdin and stdout. The server defaults to MCP protocol 2025-11-25 and accepts older supported client protocol versions during initialization.
+
+The default tools profile is `core`, which keeps MCP context small for everyday browser automation. Use `--tools all` for the full typed CLI parity surface, or combine profiles with commas, such as `--tools core,network,react`.
+
+Profiles:
+
+- `core` — Default. Navigation, snapshots, interaction, waits, reads, screenshots, JavaScript eval, close, tab basics, and profile discovery
+- `network` — Network routes, request inspection, HAR, headers, credentials, offline
+- `state` — Cookies, storage, auth, saved state, sessions, profiles, skills
+- `debug` — Console/errors, tracing, profiling, recording, clipboard, plugins, doctor, dashboard, install, upgrade, chat, diff, batch, confirm/deny
+- `tabs` — Back/forward/reload, tabs, windows, frames, dialogs
+- `react` — React tree/inspect/renders/suspense, vitals, pushstate
+- `mobile` — Viewport/device/geolocation/media, touch, swipe, mouse, keyboard
+- `all` — Every MCP tool, including the full typed CLI parity surface
+
+Common tools include:
+
+- `agent_browser_tools_profiles`
+- `agent_browser_open`
+- `agent_browser_snapshot`
+- `agent_browser_click`
+- `agent_browser_fill`
+- `agent_browser_type`
+- `agent_browser_press`
+- `agent_browser_wait_for_selector`
+- `agent_browser_screenshot`
+- `agent_browser_get_url`
+- `agent_browser_eval`
+- `agent_browser_close`
+
+Each tool has typed fields such as `url`, `selector`, `text`, `key`, and `session`, so MCP clients show meaningful approval prompts instead of raw command arrays. Each tool also accepts `extraArgs` for advanced CLI flags and exact CLI parity. Tool discovery is paginated and includes read-only/open-world annotations so modern MCP clients can load the large typed surface incrementally.
+
+Example MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "agent-browser": {
+      "command": "agent-browser",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Full parity MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "agent-browser": {
+      "command": "agent-browser",
+      "args": ["mcp", "--tools", "all"]
+    }
+  }
+}
+```
+
+Tool invocations use the same config files and environment variables as the CLI. Use `session` in the tool arguments, or set `AGENT_BROWSER_SESSION`, to isolate browser state.
+
 ## Authentication
 
 agent-browser provides multiple ways to persist login sessions so you don't re-authenticate every run.
@@ -646,6 +721,7 @@ agent-browser --session-name secure open example.com
 agent-browser includes security features for safe AI agent deployments. All features are opt-in, and existing workflows are unaffected until you explicitly enable a feature:
 
 - **Authentication Vault**: Store credentials locally (always encrypted), reference by name. The LLM never sees passwords. `auth login` navigates with `load` and then waits for login form selectors to appear (SPA-friendly, timeout follows the default action timeout). A key is auto-generated at `~/.agent-browser/.encryption-key` if `AGENT_BROWSER_ENCRYPTION_KEY` is not set: `echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin` then `agent-browser auth login github`
+- **Plugin System**: Extend agent-browser with external executable plugins. Plugins run out-of-process over the `agent-browser.plugin.v1` stdio JSON protocol and declare capabilities such as `credential.read`, `browser.provider`, `launch.mutate`, or `command.run`.
 - **Content Boundary Markers**: Wrap page output in delimiters so LLMs can distinguish tool output from untrusted content: `--content-boundaries`
 - **Domain Allowlist**: Restrict navigation to trusted domains (wildcards like `*.example.com` also match the bare domain): `--allowed-domains "example.com,*.example.com"`. Sub-resource requests (scripts, images, fetch) and WebSocket/EventSource connections to non-allowed domains are also blocked. Include any CDN domains your target pages depend on (e.g., `*.cdn.example.com`).
 - **Action Policy**: Gate destructive actions with a static policy file: `--action-policy ./policy.json`
@@ -660,9 +736,97 @@ agent-browser includes security features for safe AI agent deployments. All feat
 | `AGENT_BROWSER_ACTION_POLICY`       | Path to action policy JSON file          |
 | `AGENT_BROWSER_CONFIRM_ACTIONS`     | Action categories requiring confirmation |
 | `AGENT_BROWSER_CONFIRM_INTERACTIVE` | Enable interactive confirmation prompts  |
+| `AGENT_BROWSER_PLUGINS`             | JSON plugin registry override            |
 
 See [Security documentation](https://agent-browser.dev/security) for details.
 
+### Plugin System
+
+Plugins let third-party tools integrate without becoming built-in agent-browser dependencies. Add a plugin from npm or GitHub:
+
+```bash
+agent-browser plugin add agent-browser-plugin-captcha
+agent-browser plugin add @company/agent-browser-plugin-vault --name vault
+agent-browser plugin add org/agent-browser-plugin-cloud-browser
+```
+
+References are resolved by shape: `name` uses npm, `@scope/name` uses npm, and `owner/repo` uses GitHub. `plugin add` writes `./agent-browser.json` by default; use `--global` for `~/.agent-browser/config.json`.
+
+Plugin packages should support `plugin.manifest` so `plugin add` can discover their name and capabilities automatically. If a plugin does not support manifests, pass `--capability <name>` during add.
+
+Plugins can also be configured manually in `agent-browser.json`:
+
+```json
+{
+  "plugins": [
+    {
+      "name": "vault",
+      "command": "agent-browser-plugin-vault",
+      "capabilities": ["credential.read"]
+    },
+    {
+      "name": "cloud-browser",
+      "command": "agent-browser-plugin-cloud-browser",
+      "capabilities": ["browser.provider"]
+    },
+    {
+      "name": "stealth",
+      "command": "agent-browser-plugin-stealth",
+      "capabilities": ["launch.mutate"]
+    },
+    {
+      "name": "captcha",
+      "command": "agent-browser-plugin-captcha",
+      "capabilities": ["command.run", "captcha.solve"]
+    }
+  ]
+}
+```
+
+Inspect configured plugins:
+
+```bash
+agent-browser plugin list
+agent-browser plugin show vault
+```
+
+Use a credential provider plugin for one login:
+
+```bash
+agent-browser auth login my-app --credential-provider vault --item "My App"
+agent-browser auth login my-app --credential-provider vault --item "My App" --url https://app.example.com/login --username-selector "#email" --password-selector "#password" --submit-selector "button[type=submit]"
+```
+
+Use a browser provider plugin:
+
+```bash
+agent-browser --provider cloud-browser open https://example.com
+```
+
+Use a launch mutator plugin for stealth or local launch customization. The plugin can append Chrome args, extensions, and init scripts before the browser starts:
+
+```bash
+agent-browser open https://example.com
+```
+
+Use a generic plugin command for domain-specific tools such as CAPTCHA solvers:
+
+```bash
+agent-browser plugin run captcha captcha.solve --payload '{"siteKey":"...","url":"https://example.com"}'
+```
+
+The protocol request always includes `protocol`, `type`, `capability`, and `request`. A credential plugin receives `credential.resolve`, a browser provider receives `browser.launch`, a launch mutator receives `launch.mutate`, and generic commands receive the supplied request type. `plugin run` is for `command.run` and custom capabilities; core capabilities and protocol request types use their dedicated command paths. agent-browser keeps browser automation, redaction-sensitive output, and policy enforcement in core.
+
+Gate plugin access by capability action:
+
+```bash
+agent-browser --confirm-actions plugin:vault:credential.read auth login my-app --credential-provider vault --item "My App"
+agent-browser --confirm-actions plugin:cloud-browser:browser.provider --provider cloud-browser open https://example.com
+agent-browser --confirm-actions plugin:stealth:launch.mutate open https://example.com
+```
+
+Do not put vault tokens or passwords in plugin command args. Use the vault vendor's own login/session mechanism or environment outside agent-browser config.
+
 ## Snapshot Options
 
 The `snapshot` command supports filtering to reduce output size:
@@ -728,7 +892,7 @@ This is useful for multimodal AI models that can reason about visual layout, unl
 | `--ignore-https-errors` | Ignore HTTPS certificate errors (useful for self-signed certs) |
 | `--allow-file-access` | Allow file:// URLs to access local files (Chromium only) |
 | `--hide-scrollbars <bool>` | Hide native scrollbars in headless Chromium screenshots, enabled by default (or `AGENT_BROWSER_HIDE_SCROLLBARS` env) |
-| `-p, --provider <name>` | Cloud browser provider (or `AGENT_BROWSER_PROVIDER` env) |
+| `-p, --provider <name>` | Browser provider, including configured `browser.provider` plugins (or `AGENT_BROWSER_PROVIDER` env) |
 | `--device <name>` | iOS device name, e.g. "iPhone 15 Pro" (or `AGENT_BROWSER_IOS_DEVICE` env) |
 | `--json` | JSON output (for agents) |
 | `--annotate` | Annotated screenshot with numbered element labels (or `AGENT_BROWSER_ANNOTATE` env) |
@@ -859,7 +1023,14 @@ Create an `agent-browser.json` file to set persistent defaults instead of repeat
   "profile": "./browser-data",
   "userAgent": "my-agent/1.0",
   "hideScrollbars": false,
-  "ignoreHttpsErrors": true
+  "ignoreHttpsErrors": true,
+  "plugins": [
+    {
+      "name": "vault",
+      "command": "agent-browser-plugin-vault",
+      "capabilities": ["credential.read"]
+    }
+  ]
 }
 ```
 
@@ -870,7 +1041,7 @@ agent-browser --config ./ci-config.json open example.com
 AGENT_BROWSER_CONFIG=./ci-config.json agent-browser open example.com
 ```
 
-All options from the table above can be set in the config file using camelCase keys (e.g., `--executable-path` becomes `"executablePath"`, `--proxy-bypass` becomes `"proxyBypass"`). Unknown keys are ignored for forward compatibility.
+All options from the table above can be set in the config file using camelCase keys (e.g., `--executable-path` becomes `"executablePath"`, `--proxy-bypass` becomes `"proxyBypass"`). Plugins are configured with the `"plugins"` array shown above. Unknown keys are ignored for forward compatibility.
 
 A [JSON Schema](agent-browser.schema.json) is available for IDE autocomplete and validation. Add a `$schema` key to your config file to enable it:
 
@@ -1277,6 +1448,7 @@ The daemon starts automatically on first command and persists between commands f
 | Platform    | Binary      |
 | ----------- | ----------- |
 | macOS ARM64 | Native Rust |
+| macOS x64   | Native Rust |
 | Linux ARM64 | Native Rust |
 | Linux x64   | Native Rust |
 

package/bin/agent-browser.js

@@ -38,12 +38,7 @@ function getBinaryName() {
       osKey = 'darwin';
       break;
     case 'linux':
-      if (isMusl()) {
-        console.error('Error: agent-browser-priv does not publish musl Linux binaries.');
-        console.error('Use a glibc-based Linux environment or build locally with npm run build:native.');
-        process.exit(1);
-      }
-      osKey = 'linux';
+      osKey = isMusl() ? 'linux-musl' : 'linux';
       break;
     case 'win32':
       osKey = 'win32';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-browser-priv",
-  "version": "0.27.3-priv.8",
+  "version": "0.28.0-priv.2",
   "description": "Browser automation CLI for AI agents",
   "type": "module",
   "packageManager": "pnpm@11.1.3",
@@ -29,7 +29,9 @@
     "build:docker": "docker build --platform linux/amd64 -t agent-browser-builder -f docker/Dockerfile.build .",
     "release": "pnpm run version:sync && pnpm run build:all-platforms",
     "postinstall": "node scripts/postinstall.js",
-    "build:dashboard": "cd packages/dashboard && pnpm build"
+    "build:dashboard": "cd packages/dashboard && pnpm build",
+    "runtime:update-check": "node scripts/check-runtime-updates.mjs",
+    "runtime:update-patchright": "node scripts/update-patchright-version.mjs"
   },
   "keywords": [
     "browser",

package/scripts/build-all-platforms.sh

@@ -67,9 +67,18 @@ build_target "aarch64-unknown-linux-gnu" "aarch64-unknown-linux-gnu.2.28" "agent
 # is re-enabled:
 # build_target "x86_64-pc-windows-gnu" "x86_64-pc-windows-gnu" "agent-browser-priv-win32-x64.exe"
 
+# macOS x64 (via zig for cross-compilation)
+build_target "x86_64-apple-darwin" "x86_64-apple-darwin" "agent-browser-priv-darwin-x64"
+
 # macOS ARM64 (via zig for cross-compilation)
 build_target "aarch64-apple-darwin" "aarch64-apple-darwin" "agent-browser-priv-darwin-arm64"
 
+# Linux musl x64 (Alpine)
+build_target "x86_64-unknown-linux-musl" "x86_64-unknown-linux-musl" "agent-browser-priv-linux-musl-x64"
+
+# Linux musl ARM64 (Alpine)
+build_target "aarch64-unknown-linux-musl" "aarch64-unknown-linux-musl" "agent-browser-priv-linux-musl-arm64"
+
 echo ""
 echo -e "${GREEN}Build complete!${NC}"
 echo ""

package/scripts/check-runtime-updates.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const rootDir = join(dirname(fileURLToPath(import.meta.url)), '..');
+const installRsPath = join(rootDir, 'cli/src/install.rs');
+const trackingPath = join(rootDir, 'priv/version-tracking.json');
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+function readPatchrightPin() {
+  const source = readFileSync(installRsPath, 'utf8');
+  const match = source.match(/pub const PATCHRIGHT_VERSION:\s*&str\s*=\s*"([^"]+)"/);
+  if (!match) {
+    throw new Error('Could not find PATCHRIGHT_VERSION in cli/src/install.rs');
+  }
+  return match[1];
+}
+
+function npmLatest(packageName) {
+  return execFileSync('npm', ['view', packageName, 'version'], {
+    cwd: rootDir,
+    encoding: 'utf8',
+    timeout: 20_000,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
+}
+
+function upstreamTags() {
+  const output = execFileSync(
+    'git',
+    [
+      'ls-remote',
+      '--tags',
+      '--refs',
+      'https://github.com/vercel-labs/agent-browser.git',
+      'refs/tags/v*',
+    ],
+    {
+      cwd: rootDir,
+      encoding: 'utf8',
+      timeout: 20_000,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    },
+  );
+  return output
+    .trim()
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => line.split(/\s+/)[1]?.replace('refs/tags/', ''))
+    .filter(Boolean)
+    .filter((tag) => /^v\d+\.\d+\.\d+/.test(tag));
+}
+
+function parseVersion(version) {
+  const cleaned = version.replace(/^v/, '').split('-')[0];
+  const parts = cleaned.split('.').map((part) => Number.parseInt(part, 10));
+  return [parts[0] || 0, parts[1] || 0, parts[2] || 0];
+}
+
+function compareVersions(a, b) {
+  const pa = parseVersion(a);
+  const pb = parseVersion(b);
+  for (let i = 0; i < 3; i += 1) {
+    if (pa[i] !== pb[i]) return pa[i] - pb[i];
+  }
+  return a.localeCompare(b);
+}
+
+function latestTag(tags) {
+  if (tags.length === 0) return null;
+  return [...tags].sort(compareVersions).at(-1);
+}
+
+function buildReport() {
+  const tracking = readJson(trackingPath);
+  const patchrightPinned = readPatchrightPin();
+  const patchrightLatest = npmLatest('patchright');
+  const latestUpstreamTag = latestTag(upstreamTags());
+
+  return {
+    patchright: {
+      pinned: patchrightPinned,
+      latest: patchrightLatest,
+      outdated: patchrightPinned !== patchrightLatest,
+      tracking_matches_source: tracking.patchright_pin === patchrightPinned,
+    },
+    agent_browser: {
+      tracked_upstream_tag: tracking.agent_browser_upstream_tag,
+      latest_upstream_tag: latestUpstreamTag,
+      outdated: Boolean(
+        latestUpstreamTag &&
+          compareVersions(latestUpstreamTag, tracking.agent_browser_upstream_tag) > 0,
+      ),
+    },
+    tracking: {
+      path: 'priv/version-tracking.json',
+      policy: tracking.policy,
+    },
+  };
+}
+
+function printHuman(report) {
+  console.log('Runtime update check');
+  console.log('');
+  console.log(
+    `Patchright: pinned ${report.patchright.pinned}, npm latest ${report.patchright.latest}`,
+  );
+  console.log(
+    `  status: ${report.patchright.outdated ? 'outdated' : 'current'}`,
+  );
+  console.log(
+    `  tracking: ${report.patchright.tracking_matches_source ? 'matches source' : 'does not match source'}`,
+  );
+  console.log('');
+  console.log(
+    `agent-browser upstream: tracked ${report.agent_browser.tracked_upstream_tag}, latest ${report.agent_browser.latest_upstream_tag ?? 'unknown'}`,
+  );
+  console.log(
+    `  status: ${report.agent_browser.outdated ? 'sync available' : 'current'}`,
+  );
+}
+
+const report = buildReport();
+
+if (process.argv.includes('--json')) {
+  console.log(JSON.stringify(report, null, 2));
+} else {
+  printHuman(report);
+}
+
+if (!report.patchright.tracking_matches_source) {
+  process.exitCode = 1;
+}

package/scripts/update-patchright-version.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const rootDir = join(dirname(fileURLToPath(import.meta.url)), '..');
+const installRsPath = join(rootDir, 'cli/src/install.rs');
+const trackingPath = join(rootDir, 'priv/version-tracking.json');
+
+function usage() {
+  console.error('Usage: node scripts/update-patchright-version.mjs <version|latest>');
+}
+
+function npmLatest() {
+  return execFileSync('npm', ['view', 'patchright', 'version'], {
+    cwd: rootDir,
+    encoding: 'utf8',
+    timeout: 20_000,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
+}
+
+function validateVersion(version) {
+  if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version)) {
+    throw new Error(`Invalid Patchright version: ${version}`);
+  }
+}
+
+function buildPackageFiles(version) {
+  const packageJson = {
+    name: 'patchright',
+    private: true,
+    type: 'module',
+    dependencies: {
+      patchright: version,
+    },
+  };
+
+  const dir = mkdtempSync(join(tmpdir(), 'agent-browser-patchright-'));
+  try {
+    writeFileSync(join(dir, 'package.json'), `${JSON.stringify(packageJson, null, 2)}\n`);
+    execFileSync(
+      'npm',
+      [
+        'install',
+        '--package-lock-only',
+        '--ignore-scripts',
+        '--omit=dev',
+        '--no-audit',
+        '--fund=false',
+      ],
+      {
+        cwd: dir,
+        stdio: 'inherit',
+        timeout: 60_000,
+      },
+    );
+    const packageLock = JSON.parse(readFileSync(join(dir, 'package-lock.json'), 'utf8'));
+    if (packageLock.packages?.['']) {
+      delete packageLock.packages[''].name;
+    }
+    return {
+      packageJson: `${JSON.stringify(packageJson, null, 2)}\n`,
+      packageLock: `${JSON.stringify(packageLock, null, 2)}\n`,
+    };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function replaceRawString(source, name, value) {
+  const pattern = new RegExp(`let ${name} = r#"(.*?)"#;`, 's');
+  if (!pattern.test(source)) {
+    throw new Error(`Could not find raw string ${name} in cli/src/install.rs`);
+  }
+  return source.replace(pattern, `let ${name} = r#"${value}"#;`);
+}
+
+function updateInstallRs(version, packageJson, packageLock) {
+  let source = readFileSync(installRsPath, 'utf8');
+  source = source.replace(
+    /pub const PATCHRIGHT_VERSION:\s*&str\s*=\s*"[^"]+";/,
+    `pub const PATCHRIGHT_VERSION: &str = "${version}";`,
+  );
+  source = replaceRawString(source, 'package_json', packageJson);
+  source = replaceRawString(source, 'package_lock', packageLock);
+  writeFileSync(installRsPath, source);
+}
+
+function updateTracking(version) {
+  const tracking = JSON.parse(readFileSync(trackingPath, 'utf8'));
+  tracking.patchright_pin = version;
+  writeFileSync(trackingPath, `${JSON.stringify(tracking, null, 2)}\n`);
+}
+
+const requested = process.argv[2];
+if (!requested) {
+  usage();
+  process.exit(1);
+}
+
+const version = requested === 'latest' ? npmLatest() : requested;
+validateVersion(version);
+
+const { packageJson, packageLock } = buildPackageFiles(version);
+updateInstallRs(version, packageJson, packageLock);
+updateTracking(version);
+
+console.log(`Updated Patchright backend pin to ${version}`);

package/skill-data/core/SKILL.md

@@ -66,6 +66,29 @@ agent-browser screenshot result.png
 The browser stays running across commands so these feel like a single
 session. Use `agent-browser close` (or `close --all`) when you're done.
 
+## MCP integration
+
+For tools that support Model Context Protocol servers, start the stdio server:
+
+```bash
+agent-browser mcp
+agent-browser mcp --tools all
+agent-browser mcp --tools core,network,react
+```
+
+Configure the MCP client to launch `agent-browser` with `["mcp"]`. The server
+defaults to MCP protocol 2025-11-25 and accepts older supported client protocol
+versions during initialization. The default tools profile is `core`, which
+keeps MCP context small for everyday browser automation. Use `--tools all` for
+the full typed CLI parity surface, or combine profiles with commas, such as
+`--tools core,network,react`. Profiles are `core`, `network`, `state`, `debug`,
+`tabs`, `react`, `mobile`, and `all`; the `debug` profile includes plugin
+registry and command.run tools. Each tool accepts typed arguments plus
+`extraArgs` for advanced CLI flags and exact CLI parity. Tool discovery is
+paginated and includes read-only/open-world annotations so modern MCP clients
+can load the large typed surface incrementally. Use the tool `session` argument
+or `AGENT_BROWSER_SESSION` to isolate browser sessions.
+
 ## Reading a page
 
 ```bash
@@ -204,6 +227,27 @@ agent-browser auth save my-app --url https://app.example.com/login \
 agent-browser auth login my-app    # fills + clicks, waits for form
 ```
 
+If credentials live in an external vault, use a configured credential provider
+plugin instead of putting secrets in the command line:
+
+```bash
+agent-browser plugin add agent-browser-plugin-vault --name vault
+agent-browser plugin list
+agent-browser auth login my-app --credential-provider vault --item "My App"
+agent-browser auth login my-app --credential-provider vault --item "My App" --url https://app.example.com/login --username-selector "#email" --password-selector "#password"
+```
+
+Plugins can also provide browser providers, launch mutators such as stealth
+setup, and arbitrary namespaced commands:
+
+```bash
+agent-browser --provider cloud-browser open https://example.com
+agent-browser plugin run captcha captcha.solve --payload '{"siteKey":"...","url":"https://example.com"}'
+```
+
+`plugin run` is for `command.run` and custom capabilities. Core capabilities
+and protocol request types use their dedicated command paths.
+
 ### Persist session across runs
 
 ```bash
@@ -358,6 +402,8 @@ agent-browser doctor --json              # structured output for programmatic co
 ```
 
 `doctor` auto-cleans stale socket/pid/version sidecar files on every run.
+For the default Patchright backend, it also reports the installed Patchright
+version, the release pin, and npm latest when network checks are enabled.
 Destructive actions require `--fix`. Exit code is `0` if all checks pass
 (warnings OK), `1` if any fail.
 
@@ -484,7 +530,7 @@ That pulls in:
 
 - `references/commands.md` — every command, flag, alias
 - `references/snapshot-refs.md` — deep dive on the snapshot + ref model
-- `references/authentication.md` — auth vault, credential handling
+- `references/authentication.md` — auth vault, credential plugins, credential handling
 - `references/trust-boundaries.md` — safety rules for driving a real browser
 - `references/session-management.md` — persistence, multi-session workflows
 - `references/profiling.md` — Chrome DevTools tracing and profiling

package/skill-data/core/references/authentication.md

@@ -10,6 +10,7 @@ Login flows, session persistence, OAuth, 2FA, and authenticated browsing.
 - [Persistent Profiles](#persistent-profiles)
 - [Session Persistence](#session-persistence)
 - [Basic Login Flow](#basic-login-flow)
+- [Plugins](#plugins)
 - [Saving Authentication State](#saving-authentication-state)
 - [Restoring Authentication](#restoring-authentication)
 - [OAuth / SSO Flows](#oauth--sso-flows)
@@ -140,6 +141,80 @@ agent-browser wait --load networkidle
 agent-browser get url  # Should be dashboard, not login
 ```
 
+## Plugins
+
+Use credential provider plugins when credentials live in external vault software. Plugins are configured in `agent-browser.json` and run as external executables over the `agent-browser.plugin.v1` stdio JSON protocol.
+
+Add a plugin with `plugin add`. A plain `name` or `@scope/name` resolves from npm; `owner/repo` resolves from GitHub:
+
+```bash
+agent-browser plugin add agent-browser-plugin-vault --name vault
+agent-browser plugin add @company/agent-browser-plugin-vault --name vault
+agent-browser plugin add org/agent-browser-plugin-cloud-browser
+```
+
+```json
+{
+  "plugins": [
+    {
+      "name": "vault",
+      "command": "agent-browser-plugin-vault",
+      "capabilities": ["credential.read"]
+    },
+    {
+      "name": "cloud-browser",
+      "command": "agent-browser-plugin-cloud-browser",
+      "capabilities": ["browser.provider"]
+    },
+    {
+      "name": "stealth",
+      "command": "agent-browser-plugin-stealth",
+      "capabilities": ["launch.mutate"]
+    },
+    {
+      "name": "captcha",
+      "command": "agent-browser-plugin-captcha",
+      "capabilities": ["command.run", "captcha.solve"]
+    }
+  ]
+}
+```
+
+Inspect configured plugins before use:
+
+```bash
+agent-browser plugin list
+agent-browser plugin show vault
+```
+
+Resolve credentials just-in-time for one login:
+
+```bash
+agent-browser auth login my-app --credential-provider vault --item "My App"
+```
+
+Use a plugin as a browser provider or a generic domain command:
+
+```bash
+agent-browser --provider cloud-browser open https://example.com
+agent-browser plugin run captcha captcha.solve --payload '{"siteKey":"...","url":"https://example.com"}'
+```
+
+`plugin run` is for `command.run` and custom capabilities. Core capabilities
+and protocol request types use their dedicated command paths.
+
+Use `--url`, `--username-selector`, `--password-selector`, and `--submit-selector` on `auth login` to override plugin-provided metadata for the current login only.
+
+Gate plugin secret access separately from normal login automation:
+
+```bash
+agent-browser --confirm-actions plugin:vault:credential.read auth login my-app --credential-provider vault --item "My App"
+agent-browser --confirm-actions plugin:cloud-browser:browser.provider --provider cloud-browser open https://example.com
+agent-browser --confirm-actions plugin:stealth:launch.mutate open https://example.com
+```
+
+Do not put vault tokens or passwords in plugin command args. Use the vault vendor's own login/session mechanism or environment outside agent-browser config.
+
 ## Saving Authentication State
 
 After logging in, save state for reuse:

package/skill-data/core/references/commands.md

@@ -297,6 +297,36 @@ Array.from(links).map(a => a.href);
 EOF
 ```
 
+## Authentication and Plugins
+
+```bash
+agent-browser auth save <name> --url <url> --username <user> --password-stdin
+agent-browser auth login <name>          # Login using saved credentials
+agent-browser auth login <name> --credential-provider <plugin> [--item <ref>] [--url <url>]
+agent-browser auth login <name> --username-selector <s> --password-selector <s> [--submit-selector <s>]
+agent-browser auth list                  # List saved auth profiles
+agent-browser auth show <name>           # Show profile metadata, no passwords
+agent-browser auth delete <name>         # Delete a saved profile
+agent-browser plugin add <ref>           # Add a plugin from npm or GitHub
+agent-browser plugin list                # List configured plugins
+agent-browser plugin show <name>         # Show one configured plugin
+agent-browser plugin run <name> <type> --payload <json>
+                                          # Run an arbitrary plugin request
+```
+
+Credential provider plugins run out-of-process over the
+`agent-browser.plugin.v1` stdio JSON protocol and must declare
+`credential.read`. Use `--confirm-actions plugin:<name>:credential.read`
+to require explicit approval before a plugin resolves secrets.
+
+Other capabilities use the same protocol:
+- `browser.provider`: `agent-browser --provider <name> open <url>`
+- `launch.mutate`: append local launch args, extensions, or init scripts
+- `command.run`: `agent-browser plugin run <name> <type> --payload <json>`
+
+`plugin run` is for `command.run` and custom capabilities. Core capabilities
+and protocol request types use their dedicated command paths.
+
 ## State Management
 
 ```bash
@@ -304,6 +334,56 @@ agent-browser state save auth.json    # Save cookies, storage, auth state
 agent-browser state load auth.json    # Restore saved state
 ```
 
+## MCP Server
+
+```bash
+agent-browser mcp
+agent-browser mcp --tools all
+agent-browser mcp --tools core,network,react
+```
+
+Starts a stdio Model Context Protocol server. MCP clients should configure the
+server command as `agent-browser` with args `["mcp"]`. The server defaults to
+MCP protocol 2025-11-25 and accepts older supported client protocol versions
+during initialization.
+
+The default tools profile is `core`, which keeps MCP context small for everyday
+browser automation. Use `--tools all` for the full typed CLI parity surface, or
+combine profiles with commas, such as `--tools core,network,react`.
+
+Profiles:
+
+- `core` - Default. Navigation, snapshots, interaction, waits, reads, screenshots, JavaScript eval, close, tab basics, and profile discovery
+- `network` - Network routes, request inspection, HAR, headers, credentials, offline
+- `state` - Cookies, storage, auth, saved state, sessions, profiles, skills
+- `debug` - Console/errors, tracing, profiling, recording, clipboard, plugins, doctor, dashboard, install, upgrade, chat, diff, batch, confirm/deny
+- `tabs` - Back/forward/reload, tabs, windows, frames, dialogs
+- `react` - React tree/inspect/renders/suspense, vitals, pushstate
+- `mobile` - Viewport/device/geolocation/media, touch, swipe, mouse, keyboard
+- `all` - Every MCP tool, including the full typed CLI parity surface
+
+Common tools include:
+
+- `agent_browser_tools_profiles`
+- `agent_browser_open`
+- `agent_browser_snapshot`
+- `agent_browser_click`
+- `agent_browser_fill`
+- `agent_browser_type`
+- `agent_browser_press`
+- `agent_browser_wait_for_selector`
+- `agent_browser_screenshot`
+- `agent_browser_get_url`
+- `agent_browser_eval`
+- `agent_browser_close`
+
+Tool calls use the same config files and environment variables as the CLI. Each
+tool accepts typed arguments plus `extraArgs` for advanced CLI flags and exact
+CLI parity. Tool discovery is paginated and includes read-only/open-world
+annotations so modern MCP clients can load the large typed surface
+incrementally. Use the `session` tool argument or `AGENT_BROWSER_SESSION` to
+isolate browser state.
+
 ## Global Options
 
 ```bash
@@ -312,7 +392,7 @@ agent-browser --json ...              # JSON output for parsing
 agent-browser --headed ...            # Show browser window (not headless)
 agent-browser --cdp <port> ...        # Connect via Chrome DevTools Protocol
 agent-browser --backend <name> ...    # Local backend: patchright (default), chrome
-agent-browser -p <provider> ...       # Cloud browser provider (--provider)
+agent-browser -p <provider> ...       # Browser provider or configured provider plugin
 agent-browser --proxy <url> ...       # Use proxy server
 agent-browser --proxy-bypass <hosts>  # Hosts to bypass proxy
 agent-browser --wait-until <state>    # Navigation wait: none, domcontentloaded, load, networkidle
@@ -399,8 +479,9 @@ AGENT_BROWSER_EXTENSIONS="/ext1,/ext2"       # Comma-separated extension paths
 AGENT_BROWSER_INIT_SCRIPTS="/a.js,/b.js"     # Comma-separated init script paths
 AGENT_BROWSER_ENABLE="react-devtools"        # Comma-separated built-in init script features
 AGENT_BROWSER_HIDE_SCROLLBARS="false"        # Keep native scrollbars visible in headless Chromium screenshots
-AGENT_BROWSER_PROVIDER="browserbase"         # Cloud browser provider
+AGENT_BROWSER_PROVIDER="browserbase"         # Browser provider or configured provider plugin
 AGENT_BROWSER_STREAM_PORT="9223"             # Override WebSocket streaming port (default: OS-assigned)
 AGENT_BROWSER_CONFIG="./agent-browser.json"  # Custom config file
 AGENT_BROWSER_CDP="9222"                     # Connect daemon to CDP port or WebSocket URL
+AGENT_BROWSER_PLUGINS='[{"name":"vault","command":"agent-browser-plugin-vault","capabilities":["credential.read"]},{"name":"stealth","command":"agent-browser-plugin-stealth","capabilities":["launch.mutate"]}]'
 ```