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).

## Upstream coverage (do not restate)

These topics belong to the vendor. Read them at the source; do not copy them back into this skill.

| Topic | First-party source |
|-------|--------------------|
| CLI command reference, snapshot and ref loop, waits, auth options, eval, config file | `agent-browser` skill · https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md |
| Electron and desktop-app automation over CDP (`connect`, `--cdp`, webviews, tabs) | https://github.com/vercel-labs/agent-browser/blob/main/skill-data/electron/SKILL.md |
| Slack workspace navigation and extraction recipes | https://github.com/vercel-labs/agent-browser/blob/main/skill-data/slack/SKILL.md |
| Running headless in a Vercel Sandbox microVM (deps, snapshots, cron) | `vercel:vercel-sandbox` skill · https://github.com/vercel-labs/agent-browser/blob/main/skill-data/vercel-sandbox/SKILL.md |
| Exploratory QA sweep with repro evidence (issue taxonomy, report template) | `dogfood` skill · https://github.com/vercel-labs/agent-browser/blob/main/skill-data/dogfood/SKILL.md |
| Named `.localhost` dev URLs | `ork:portless` skill · https://github.com/vercel-labs/portless |

**Our delta over all of the above**: `references/ork-delta.md`, covering where the safety hook does and does not apply, the shared rate-limit budget, and the local-URL policy.

## 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 to 2026-08 (agent-browser 0.23 to 0.35.1)

**0.35.1:** `diff snapshot` ref numbering resets per diff, refs are invalidated across
navigations, and the previous refs survive a failed diff. The streaming `url` event
narrowed to the active tab's main frame: it now emits for full-document, History API and
fragment navigation, rebinds after an active-tab change, and ignores child-frame and
background-tab navigation.

**0.35.0:** `--ca-cert <path>` (also `AGENT_BROWSER_CA_CERT`, and `caCert` in config/MCP)
imports a PEM bundle or DER certificate into an isolated NSS trust store, the targeted
alternative to `--ignore-https-errors` behind an SSL-inspecting proxy: hostname, validity
and unrelated-authority checks stay on. The CA persists across commands in a session and
`--no-ca-cert` clears it. Linux-only, needs `certutil`, and is rejected with `--profile`,
`--cdp`, `--auto-connect`, providers, Lightpanda or `--ignore-https-errors`. Also adds the
bundled `protected-vercel-deployments` skill for reaching SSO-protected Vercel deployments
via short-lived Trusted Sources OIDC tokens instead of a static bypass secret.

**0.34.0:** persistent session-to-tab binding for shared Chrome sessions. Named
`--cdp`/`--auto-connect` sessions remember their CDP target across daemon restarts, CDP
target ids work as tab refs, and `--pin-tab` makes the binding strict so an externally
closed tab returns a stable `tab_gone` error instead of silently retargeting. JSON output
gains `data.targetId` and optional `data.lastUrl`. Also fixes parallel sessions hijacking
each other's tabs.

> Corrected 2026-08-28. This section previously credited 0.34.0 with `pushstate`,
> `removeinitscript`, `--enable react-devtools`, `profiler`, `plugin add|list|show|run`,
> `confirm`/`deny`, `--webgpu` and the MCP `--tools` surface. Checked against the upstream
> CHANGELOG, `pushstate` and `--init-script` landed in 0.27.0, the plugin system and the
> MCP `--tools <profiles>` surface in 0.28.0, and `--webgpu` in 0.31.2; `removeinitscript`
> and `confirm`/`deny` appear nowhere in it. Only `--pin-tab`/`--no-pin-tab` was actually
> 0.34.0. The rest of this file already dated `pushstate` to v0.27 in two other places,
> so the file contradicted itself.

**Accessibility audits (0.33.0):**
- **`agent-browser a11y [url]`** — axe-core accessibility audit as a CLI command and a matching MCP tool. Filter by WCAG tag, scope to a selector, and get iframe-aware text or JSON results. The audit engine is embedded, so it runs offline and is CSP-safe (no third-party script injection into the page under test).
- Pairs with the `accessibility-specialist` agent and the `testing-e2e` axe-core guidance: use this for a fast pre-commit sweep, and Playwright + axe for assertions inside a suite.

**Session restore + read (0.30 → 0.31.1):**
- **`agent-browser read [url]` (0.30.0)** — agent-readable text extraction as a CLI command and MCP tool. URL reads prefer Markdown (try `.md` and nearby `llms.txt`), support outlines, filters, raw and JSON output, headers, and domain/output safeguards; omit the URL to read the rendered active-tab DOM with current browser state.
- **Restore workflow (0.31.0)** — `--restore` / `--restore-save`, restore-validation flags, worktree-scoped `session id` / `session info`, and `--namespace` give agent runs stable, isolated, auto-re