plugins/ruflo-browser/README.md
Session-as-skill browser automation. Playwright-backed via 23 mcp__claude-flow__browser_* tools, with each session captured as a first-class RVF cognitive container holding manifest + trajectory + screenshots + sanitized cookies + findings, indexed in AgentDB and gated by AIDefence.
v0.2.0 architecture — every browser session is now an addressable, replayable, federatable artifact. Status is Proposed per ADR-0001; the load-bearing replay assumption requires a pre-Accept spike (see ADR Verification §4).
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-browser@ruflo
A browser session is allocated an RVF container at session-start and committed at session-end:
<rvf-id>/
├── manifest.yaml # URL, viewport, profile, runner, lineage
├── trajectory.ndjson # one line per action via ruvector hooks trajectory-step
├── screenshots/<step>.png
├── snapshots/<step>.json # accessibility trees indexed by navigation
├── dom/ # optional, when --with-dom
├── cookies.json # AIDefence-sanitized
└── findings.md # test verdicts, scrape outputs, injection quarantine
Re-open with rvf ingest <id>, fork with rvf derive, federate with rvf export.
/ruflo-browser is a verb dispatcher:
/ruflo-browser ls [--query <text>] # list sessions, AgentDB-indexed
/ruflo-browser show <session-id> # manifest + trajectory + verdict
/ruflo-browser replay <session-id> # re-drive trajectory
/ruflo-browser export <session-id> # rvf export → tar.zst
/ruflo-browser fork <session-id> # rvf derive → new lineage-tracked session
/ruflo-browser purge <session-id> # destroy, keep redacted manifest
/ruflo-browser doctor # check Playwright, MCP, AgentDB, AIDefence
| Skill | Purpose |
|---|---|
browser-record | Open a named, traced session into an RVF container. Primitive others compose. |
browser-replay | Replay a stored trajectory, optionally on a different URL or with mutated inputs. |
browser-extract | Run a stored browser-templates recipe or one-shot extraction. PII-scanned. |
browser-login | Drive an auth flow once, sanitize+vault cookies for reuse. |
browser-form-fill | Form interaction with field-name → value mapping. |
browser-screenshot-diff | Pixel + DOM diff between two session screenshots (visual regression). |
browser-auth-flow | Probe an auth flow for redirect leaks, missing CSRF, weak session cookies. |
browser-test | UI test recipe — composes browser-record + browser-replay. |
browser-scrape is a deprecation shim that delegates to browser-extract. Removed in v0.3.0.
| Namespace | Key | Value | Purpose |
|---|---|---|---|
browser-sessions | <rvf-id> | manifest summary + verdict + tags | session index for /ruflo-browser ls |
browser-selectors | <host>:<intent> | {selector, ref, snapshot-hash, last-success} | survives DOM drift via embedding similarity |
browser-templates | <template-name> | scrape recipe with selector chain + post-process | replaces ad-hoc memory strings |
browser-cookies | <host> | claims-gated cookie blob + expiry + AIDefence verdict | cookie reuse without re-auth |
Raw cookies and tokens never enter AgentDB unwrapped — see ADR §3.
aidefence_has_pii before AgentDB store.aidefence_scan flags high-entropy strings; vault them in browser-cookies.aidefence_is_safe. Hits get quarantined to findings.md.23 existing mcp__claude-flow__browser_* tools (interaction primitive) + 5 new browser_session_* lifecycle tools (implemented in v0.2.0):
| Tool | Purpose |
|---|---|
browser_session_record | RVF allocate + ruvector trajectory-begin + agent-browser open. Returns session id + rvf path. |
browser_session_end | trajectory-end with verdict + rvf compact + AgentDB index in browser-sessions. |
browser_session_replay | RVF derive child container + load trajectory steps for caller-level dispatch. |
browser_template_apply | Fetch a recipe from browser-templates AgentDB namespace. |
browser_cookie_use | Fetch an opaque vault handle from browser-cookies; raw values never returned. |
Implementation: v3/@claude-flow/cli/src/mcp-tools/browser-session-tools.ts, registered in mcp-client.ts. Each handler shells out to the pinned [email protected] CLI for trajectory + RVF, the existing agent-browser CLI for browser actions, and the bridged claude-flow memory for AgentDB. Missing dependencies degrade with structured success: false errors instead of crashing.
browser_session_replay is deliberately a primitive: it derives a child RVF container and surfaces the source trajectory so the caller dispatches each step through the appropriate browser_* tool. That keeps the replay engine out of the MCP layer and makes the load-bearing assumption (replay-fidelity across DOM drift) testable via the spike harness below rather than buried in tool internals.
Two complementary checks:
bash plugins/ruflo-browser/scripts/smoke.sh
# Expected on green: "13 passed, 0 failed"
Verifies plugin structural soundness — file inventory, frontmatter validity, ADR cross-references, AgentDB namespace coverage in the agent, allowed-tools enumeration in skills, and that the 5 lifecycle MCP tools are present in the CLI source.
bash plugins/ruflo-browser/scripts/replay-spike.sh
Records + replays a baseline session against each URL in scripts/SITES.txt (10 sites by default, varying drift profiles). Writes spike-results/<timestamp>/STATUS.md with per-site verdicts and the aggregate replay rate. The ADR threshold is ≥80%; meeting it is the gate to flip ADR-0001 from Proposed → Accepted. Below the threshold, the proposal degrades to "session as audit log" (replay and screenshot-diff become best-effort).
The spike requires agent-browser (or npx --yes agent-browser), [email protected] (auto-fetched via npx), and network access. It is not part of the smoke test — running it is a deliberate audit step.
ruflo-ruvector — trajectory hooks, SONA pattern distillation, MCP toolsruflo-agentdb — controllers backing browser-sessions, browser-selectors, browser-templates, browser-cookiesruflo-aidefence — PII / prompt-injection gatesruflo-federation — cross-installation session sharing via RVF exportMIT