browser-tools

# Browser Tools — Security Wrapper

OrchestKit security wrapper for `agent-browser`. **For command reference and usage patterns, use the upstream `agent-browser` skill directly.** This skill adds safety guardrails only.

> **Command docs**: Refer to the upstream `agent-browser` skill for the full command reference (50+ commands: interaction, wait, capture, extraction, storage, semantic locators, tabs, debug, mobile, network, cookies, state, vault).

## Decision Tree

```bash
# Fallback decision tree for web content
# 1. Try WebFetch first (fast, no browser overhead)
# 2. If empty/partial -> Try Tavily extract/crawl
# 3. If SPA or interactive -> use agent-browser
# 4. If login required -> authentication flow + state save
# 5. If dynamic -> wait @element or wait --text
```

## Local Dev URLs

Use **Portless** (`npm i -g portless`) for stable local dev URLs instead of guessing ports. When Portless is running, navigate to `myapp.localhost` instead of `localhost:3000`. Our safety hook already allows `*.localhost` subdomains via `ORCHESTKIT_AGENT_BROWSER_ALLOW_LOCALHOST`.

```bash
# With Portless: stable, named URLs
agent-browser open "https://myapp.localhost"

# Without: fragile port guessing
agent-browser open "http://localhost:3000"  # which app is this?
```

## New in 2026-04 → 2026-06 (agent-browser 0.23 → 0.29.1)

**Sandbox helpers (0.29):**
- **`@agent-browser/sandbox`** — companion helper package for running agent-browser headless inside a Vercel Sandbox / eve ephemeral env (provisions Chrome + the native daemon for you, no host browser needed). Hook's URL/rate/robots checks still apply to whatever the sandboxed session navigates to.

**Built-in MCP server (0.28):**
- **`agent-browser --mcp`** — runs agent-browser as a Model Context Protocol server over stdio, exposing typed tools (open/snapshot/find/click/extract/...) with paginated capability discovery. Lets you wire browser automation MCP-native — directly into an MCP client — without going through the CLI Bash wrapper. Note: MCP-native sessions bypass the `agent-browser-safety` PreToolUse Bash hook (the hook only intercepts `agent-browser` Bash commands), so apply URL/rate/robots policy at the MCP-client layer when using this path.

**React introspection + perf observability (0.27):**
- **`react tree` / `react inspect <fiberId>` / `react renders start|stop` / `react suspense`** — first-class React DevTools integration via a vendored MIT-licensed hook embedded in the binary (zero runtime deps). Component-tree visibility, per-fiber props/hooks/state inspection, render profiling with mount/re-render counts and change details, Suspense boundary classification with root-cause grouping. Hook treats fiber state dumps as sensitive — gitignore captures.
- **`vitals [url]`** — reports Core Web Vitals (LCP, CLS, TTFB, FCP, INP) plus React hydration phases for any page. Useful for perf gates in CI.
- **`pushstate <url>`** — client-side SPA navigation without a full page load. Pairs with `react renders` to measure SPA route transitions without resetting profiling state.
- **`--init-script <path>` (repeatable, env `AGENT_BROWSER_INIT_SCRIPTS`)** + **`--enable <feature>` (repeatable, env `AGENT_BROWSER_ENABLE`)** — register scripts before first navigation; `--enable react-devtools` is built-in. Hook treats arbitrary init scripts as code-execution surface — same trust model as `skills get`.
- **`network route --resource-type <csv>`** — filter intercepted requests by CDP resource type (document, script, xhr, fetch, image, ...). Lets you mock only API calls without breaking page assets.
- **`cookies set --curl <file>`** — auto-detects JSON, cURL, and Cookie-header formats for bulk cookie import. Hook still treats cookie-set as auth-state injection.
- **Dashboard behind a reverse proxy** — observability dashboard now works from proxied origins via same-origin proxy. Enables path-based routing for shared dev environments.
- Fixed `doctor` generating duplicate check IDs when invoked multiple times in the same process.
- npm publishing moved to GitHub Actions OIDC trusted publishing — no manually managed npm tokens upstream.

**Diagnostic tooling + stable IDs (0.26):**
- `agent-browser doctor` — one-shot environment + Chrome + daemon + config + security + provider + network check. Flags: `--offline`, `--quick`, `--fix`, `--json`. Run before opening an issue to attach a structured snapshot.
- **Stable tab identifiers** — tabs now use stable string IDs (`t1`, `t2`, ...) with optional memorable labels via `--label`. Survives daemon restart; replaces brittle index-based references.
- **`core` skill expanded** — comprehensive built-in usage guide covering snapshot-ref-act loops, reading, interaction, waiting, and troubleshooting.
- **Config JSON Schema** — `$schema` reference enables IDE auto-completion and validation against `https://agent-browser.dev/schema.json`.
- Fixed `--state` flag not loading saved cookies/localStorage at launch; `--help` now leads with the skills section.

**Skill discovery & chat (0.25):**
- `agent-browser skills list/get <name>` — discover and install capability packs on-demand. Hook treats first-party skills as trusted; warns on arbitrary third-party skill fetches.
- `agent-browser chat` — single-shot or REPL natural-language driving over the same daemon. Hook pipes transcripts through the same URL/rate/robots checks as scripted commands.

**Accessibility-first locators (0.24):**
- `find` / `getByRole` — semantic locator via CDP accessibility tree (role + name) instead of brittle CSS/ref selectors. Prefer these in new scripts; they survive markup churn and are the locator path assumed by `chat`.
- `snapshot --urls` — emits resolved URLs alongside refs, removing a round-trip for link-extraction flows.
- `--annotate` — overlays ref IDs / role labels on screenshots for debugging.

**Cloud providers (0.25):**
- `--provider agentcore` — AWS Bedrock AgentCore cloud browser. Hook treats remote providers as egress surfaces — same URL/ro