# Browser Control Addon

**Status: DRAFT** — scaffolded post-PoC, implementation pending. See `.aiwg/intake/browser-control-intake.md` for the formal intake form and `.aiwg/architecture/adr-remote-browser-control.md` for the architectural decision.

Drive a real, user-installed Chromium-derived browser from an AIWG agent. Handles the painful parts: which browser to use, how the Playwright MCP Bridge extension fits in, how the per-install token is captured and stored, how it gets injected into the AIWG MCP registry, and how the agent stays inside an allow-list with audit trail.

## Why

The naive setup path (`@playwright/mcp` + the Web Store extension + token in env var) is real but takes ~10 session restarts and deep knowledge of:

- Which Chromium-derived browsers `--extension` actually supports (Chrome and Edge only — not Chromium, Brave, Vivaldi, Arc, etc.)
- That tokens are per-install secrets generated by the extension UI
- That env var inheritance through Claude Code → MCP-server-child depends on shell-init semantics
- That `.claude/settings.local.json` injection is silently overridden by `--mcp-config` wrappers (e.g., `claude-role`)

This addon encapsulates that.

## Components

| Type | Name | Role |
|---|---|---|
| Skill | `browser-setup` | Interactive wizard: detect browsers, install extension, capture token, register MCP, inject, verify |
| Skill | `browser-doctor` | Health check across browser, extension, token file, registry, injection, allow-list |
| Skill | `browser-reset` | Rotate token, switch browser, clean up |
| Agent | `browser-driver` | Persona that respects allow-list + sensitive-domain gates + activity-log discipline |
| Rule | `browser-control-safety` | Token security, allow-list enforcement, capability denial |
| Template | `browser-allowlist.yaml.tmpl` | Per-workspace allow-list scaffold |

## Setup (planned UX)

```bash
# Deploy the addon
aiwg use browser-control

# Run the wizard (interactive)
aiwg run skill browser-setup

# Health check anytime
aiwg run skill browser-doctor

# Rotate or reconfigure
aiwg run skill browser-reset
```

After `browser-setup` completes:
- `~/.config/playwright-mcp/token` exists (mode 600)
- `~/.aiwg/mcp-servers.json` has `playwright` registered with `--extension` and env block
- Active provider config (e.g., `.claude/settings.local.json`) has `playwright` in `mcpServers`
- `.aiwg/browser-allowlist.yaml` scaffolded (optional)
- Restart provider → agent can drive the configured browser

## Security model summary

See `rules/browser-control-safety.md` for the full set. Headlines:

- Token at mode 600 in user home; never echoed, never committed
- Per-workspace allow-list; off-allow-list navigation requires human authorization
- Sensitive-domain pattern match (banking, identity, payment, admin) requires authorization regardless of allow-list state
- Activity-log entry per MCP tool invocation
- `--allow-unrestricted-file-access` never enabled
- `--caps devtools` opt-in only (CVE-2026-8018 precedent)

## Dependencies

External:
- `@playwright/mcp` (npm, pinned by addon version)
- [Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm) installed in target browser

Internal:
- AIWG MCP CLI (`aiwg mcp add/inject/profile`)
- `human-authorization` rule (existing)
- `activity-log` rule (existing)
- `token-security` rule (existing)

## Open core dependency

Token currently sits in plaintext in `~/.aiwg/mcp-servers.json`. This is a recognized gap; final addon release blocks on AIWG core supporting `${file:...}` substitution in MCP registry env blocks. See ADR "Open follow-ups" §1.

## Status notes

- 2026-05-22 — Addon scaffolded from PoC findings. Implementation pending Inception phase outputs.
- PoC log: `.aiwg/working/playwright-mcp-poc.md` (test plan), `.aiwg/activity.log` (timeline)

## References

- `.aiwg/intake/browser-control-intake.md` — formal intake
- `.aiwg/working/browser-control-feature-plan.md` — design + lessons
- `.aiwg/architecture/adr-remote-browser-control.md` — architectural decision
- [microsoft/playwright-mcp](https://github.com/microsoft/playwright-mcp)