🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
docs(ruflo-console): fix the live smoke, audit tool coverage (ADR-420), 9:11 portrait tour GIF
ruvcf162f00baa3
diff --git a/README.md b/README.mdindex 10b4e61162..01609003d8 100644--- a/README.md+++ b/README.md@@ -50,9 +50,9 @@ User --> Ruflo (CLI/MCP) --> Router --> Swarm --> Agents --> Memory --> LLM Prov----+<p align="center"><img src="docs/assets/ruflo-console-tour-9x11.gif" alt="The ruflo console inside Claude Code: Missions, Overview and the Optimizer, swarm, Hive-Mind, claims, Learning, MetaHarness, Memory Lab, Timeline, Events, x.ruv.io and AgentBBS, Cost, Automation, Settings, the Plugin Catalog and Dev Tools" width="480"></p>-<sub>The <code>/ruflo</code> console running in Claude Code (Claude on the left third, the cockpit on the right two thirds; drag the divider to resize): agents spawned and tasks created from the prompt show up live in the swarm, claims and memory views. <code>npx ruflo init</code>, restart Claude Code, then <code>/ruflo</code>.</sub>+<sub>The <code>/ruflo</code> console running in Claude Code (a 9:11 portrait terminal: Claude above, the cockpit docked below; in a wide terminal the dock can be dragged to give the cockpit two thirds): every section is a key or a click, and each one can launch its plugin commands in Claude or ask Claude about what you see. A <a href="docs/assets/ruflo-console-tour.gif">wide-terminal tour</a> is also kept. <code>npx ruflo init</code>, restart Claude Code, then <code>/ruflo</code>.</sub>**Install the mods from the ruflo marketplace** (Claude Code 2.1.287 or later; mods run with your account's permissions and are not sandboxed, so read the code first):diff --git a/docs/assets/ruflo-console-tour-9x11.gif b/docs/assets/ruflo-console-tour-9x11.gifnew file mode 100644index 0000000000..48955e0e22Binary files /dev/null and b/docs/assets/ruflo-console-tour-9x11.gif differdiff --git a/plugins/ruflo-console/scripts/e2e-smoke.sh b/plugins/ruflo-console/scripts/e2e-smoke.shindex 81e21b52d9..a1a348be18 100755--- a/plugins/ruflo-console/scripts/e2e-smoke.sh+++ b/plugins/ruflo-console/scripts/e2e-smoke.sh@@ -50,10 +50,15 @@ BAD='TypeError|ReferenceError|Cannot read prop|\[object |ui\.render hook skippedfor entry in "${VIEWS[@]}"; doid="${entry%%|*}"label="${entry#*|}"+ # The Terminal and Skills views hold a focused field: Escape first, so the next slash command reaches Claude's own prompt.+ tmux_keys Escape+ sleep 1tmux_cmd "/ruflo $id"sleep 2- tmux_shot "../screens/$id"+ tmux_shot "screens/$id"shot="$OUT/screens/$id.txt"+ # A capture that was not written is a failure, never a pass: grep on a missing file finds no error text.+ if [[ ! -s "$shot" ]]; then fail "V-$id" "/ruflo $id was captured" "screens/$id.txt"; continue; fiif grep -qiF -- "${label%% *}" "$shot"; then pass "V-$id" "/ruflo $id draws $label" "screens/$id.txt"; else fail "V-$id" "/ruflo $id draws $label" "screens/$id.txt"; fiif grep -qE "$BAD" "$shot"; then fail "V-$id" "no render error on screen ($id)" "screens/$id.txt"; else pass "V-$id" "no render error on screen ($id)" "screens/$id.txt"; fidonediff --git a/v3/docs/adr/ADR-420-console-tool-coverage-audit-and-live-smoke.md b/v3/docs/adr/ADR-420-console-tool-coverage-audit-and-live-smoke.mdnew file mode 100644index 0000000000..c12ed72f23--- /dev/null+++ b/v3/docs/adr/ADR-420-console-tool-coverage-audit-and-live-smoke.md@@ -0,0 +1,53 @@+# ADR 420: A tool-coverage audit of the whole console, and a live smoke that cannot pass on nothing++Status: Accepted++Date: 2026 10 03++Decision owner: Ruflo maintainers++Scope: `plugins/ruflo-console`: `scripts/e2e-smoke.sh`; the README tour GIF (`docs/assets/ruflo-console-tour-9x11.gif`).++Extends: ADR 407, ADR 411 (the plugin map), ADR 413 (the regression system), ADR 419 (the first audit).++## 1. Context++ADR 419 audited the Memory Lab and Automation. The roadmap still listed dedicated surfaces for federation and connectors, for agents and runtimes, and for the domain plugins. Before building any, every MCP tool name in `v3/@claude-flow/cli/src/mcp-tools` was compared with the tool names the console's hooks reference.++## 2. Audit++A tool name that is not referenced is not necessarily unreachable: autopilot, swarm, hive-mind, claims, hooks, memory, config and metaharness are driven through the `ruflo` CLI commands (`ruflo autopilot status`, `ruflo swarm init`, and so on), so a name search reads them as missing when they are covered. What remains, after taking those out:++| Family | State |+|---|---|+| federation, x_federation, managed_agent, terminal, github, analyze | Fully reached (the two exceptions below are deliberate) |+| `federation_bbs_human_join`, `x_federation_invite_mint` | Deliberately not offered: each mints a bearer secret, which the console never shows (ADR 417); the invite row types its command into the terminal |+| `wasm_agent_*` (13 of 14), `browser_*` sessions | Not reachable through `mcp exec`: these tools keep their agents or sessions inside the MCP server process that answers, and `mcp exec` starts a fresh process per call, so an agent created by one call is gone for the next. The console reaches what is stateless (the gallery, list); the rest belongs to a long-running MCP connection, which Claude Code already has |+| `agenticow_speculate/ingest/query`, `transfer_store-*`, `daa_workflow_execute`, `ruvllm_*` adapt/route | Gated or spending (model or network calls); reached from the Launch rows and the Plugin Catalog, which ask first |+| `agentdb_feedback/batch/*-delete`, `memory_*` raw store and delete | Covered by the Memory Lab's own entries and the learning loop; the deletes are terminal-only (ADR 419) |+| `business_pod_*`, the domain plugins (iot-cognitum, market-data, music, neural-trader) | Catalog-only by design (ADR 411): device writes, spend, or live trading, never from a button |++Conclusion: there is no further tool family worth a new surface. The plugin map already places every plugin directory, enforced by `plugin-coverage.spec.ts`.++## 3. Decision++1. **No new surfaces.** The audit is recorded here so it is not repeated.+2. **The live smoke is fixed.** `scripts/e2e-smoke.sh` had three defects that made it pass or fail for the wrong reasons:+ - it captured each view to `$OUT/../screens/<id>`, outside the run directory, so every capture was lost and every "draws" check failed;+ - its "no render error on screen" check passed when the capture did not exist (a grep on a missing file finds no error text), so a missing capture looked healthy; a missing or empty capture is now its own failure;+ - the Terminal and Skills views hold a focused field, so the slash commands typed after them reached the view and not Claude's prompt, and four later views failed to open; Escape is sent first.+ Run live against Claude Code 2.1.287 with the installed 0.21.0 build, all 28 views draw and no hook failure is logged.+3. **The README tour is a 9:11 portrait GIF**, recorded from the installed plugin cache (not a worktree) in a 96x49 terminal plus a caption row, rendered with `agg` and cropped and padded to exactly 1179x1441. In a portrait terminal the console docks at the bottom of the screen with Claude above it; the wide split tour stays in `docs/assets/ruflo-console-tour.gif` and is linked from the README.++## 4. Alternatives considered++- **A WASM-agent surface backed by a persistent MCP connection.** Rejected for the console: it would need a second long-lived server beside the one Claude Code already runs.+- **Treating the smoke's SKIP-without-credentials as enough.** Rejected: a smoke that can pass without capturing anything is worse than none.++## 5. Safety++The smoke and the recording copy the person's Claude login (`~/.claude/.credentials.json`) into a throwaway `CLAUDE_CONFIG_DIR` with mode 0600 and shred it on exit; they never point the real `~/.claude` at a test, take no model turn, and write no ruflo state.++## 6. Tests++`RUFLO_E2E_LIVE=1 bash plugins/ruflo-console/scripts/e2e-smoke.sh` (28 views, plus the debug-log check): 0 failures after the fixes. Without `RUFLO_E2E_LIVE=1` it still prints SKIP and exits 0, which `smoke.sh` step 15 checks.