ruvnet--ruflo/plugins/ruflo-browser/README.md

ruflo-browser

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

Substrate alignment (ADR-122). This plugin is the user-facing skill layer; the substrate primitives — signed trajectories (Ed25519 + RVF), causal-graph self-healing, AIDefence-attested cookie vault, federated MCTS, Session Capsules, Workflow Compiler — ship in the @claude-flow/browser@3.0.0-alpha.4 npm package. See the substrate announcement and tracking issue #2041.

Install

/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-browser@ruflo

How sessions work

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.

Commands

/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

Skills

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.

Memory layer (AgentDB)

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 gates (mandatory)

1. Pre-storage scan — every scraped string passes aidefence_has_pii before AgentDB store.
2. Cookie sanitization — aidefence_scan flags high-entropy strings; vault them in browser-cookies.
3. Prompt-injection check — extracted text returning to an LLM passes aidefence_is_safe. Hits get quarantined to findings.md. With aidefence@2.3.0 (ADR-118) the check now catches role-hijack (you are now … / act as … / pretend to be …) and jailbreak markers (DAN mode / developer mode / god mode / root mode) in addition to the canonical ignore all previous instructions family — high-leverage upgrade for browser-scraped pages.

MCP surface

18 existing mcp__claude-flow__browser_* interaction primitives (in browser-tools.ts: open/close/click/type/fill/select/check/uncheck/hover/press/scroll/screenshot/snapshot/eval/wait/reload/back/forward) + 5 new browser_session_* lifecycle tools (implemented in v0.2.0) for a total of 23:

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 ruvector@0.2.25 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.

Verification

Two complementary checks:

Structural smoke (fast, offline)

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.

Replay spike (interactive, online — pre-Accept gate)

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), ruvector@0.2.25 (auto-fetched via npx), and network access. It is not part of the smoke test — running it is a deliberate audit step.

Architecture Decisions

• ADR-0001 — Adopt session-as-skill architecture for ruflo-browser

Related Plugins

• ruflo-ruvector — trajectory hooks, SONA pattern distillation, MCP tools
• ruflo-agentdb — controllers backing browser-sessions, browser-selectors, browser-templates, browser-cookies
• ruflo-aidefence — PII / prompt-injection gates
• ruflo-federation — cross-installation session sharing via RVF export

License

MIT