interactive-browser

interactive-browser

Thin adapter for browser-fetch-router interactive-browser. Action classification, approvals, and provider preconditions live in the CLI — never reimplement here.

Required env

• BFR_AGENT=<agent-name> (e.g. claude, codex, gemini, kimi, opencode, pi)
• BFR_SESSION_ID=<uuid-or-ulid> — one per task, reused across all CLI calls in that task.

Command

BFR_AGENT=<agent-name> BFR_SESSION_ID="$session_id" \
  browser-fetch-router interactive-browser "<task description>" --json

Optional flags (this mode is the highest-trust — set the safety/cost limits explicitly):

• --provider {local,browserbase,cloud} — pick the browser backend; local keeps execution on the user's machine, the others use a hosted browser and require --allow-hosted-browser.
• --allow-hosted-browser — required to opt into hosted-browser providers (browserbase, cloud).
• --confirm-irreversible TOKEN — required when the action-tier classifier flags the task as irreversible (e.g. submit, purchase, delete). The TOKEN is supplied by the CLI on the first attempt; pass it back on retry to confirm.
• --max-steps N — hard cap on action steps in the task. Defaults are conservative; raise only with explicit user direction.
• --max-duration-sec N — hard wall-clock cap on the task.
• --max-cost-usd N — hard spend cap (matters most for browserbase / cloud providers).

When to escalate to this from read-* modes

Only when:

• The task requires submitting a form, clicking a button, or any state-changing action.
• read-user-tabs cannot satisfy a read-only task (e.g. content is loaded by interaction the user has not yet performed).

If the task is read-only, prefer read-web (public) or read-user-tabs (logged-in) — they are cheaper and lower-risk.

Diagnostics

If a CLI call fails with exit code 3 (tool_setup_failed) or 70 (internal_error), run browser-fetch-router doctor --json — provider-config and browser-runtime issues surface there.

Exit codes

Code	Meaning
0	ok
1	content blocked / not found / paywalled / insufficient
2	approval_required or approval_denied
3	tool_setup_failed
4	unsafe_url_blocked
5	cost_cap_exceeded or rate_limited
64	usage_error
70	internal_error

Rules

• Do not call raw HTTP to bypass action-tier approvals.
• Do not chain multiple side-effecting actions in one task without explicit user confirmation.
• Do not use this mode when read-web or read-user-tabs would suffice — escalation has a real cost (approval friction, audit volume, action-tier gating).
• Do not store secrets in this skill — pass them via the CLI's documented env vars only.
• Hosted paid routes require explicit CLI flags such as --allow-hosted-browser where relevant.