π 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(adr): ADR-385 β streaming, interactive, long-horizon swarm execution (#3258)
rUva4f219935ff4
diff --git a/v3/docs/adr/ADR-385-streaming-interactive-long-horizon-swarm-execution.md b/v3/docs/adr/ADR-385-streaming-interactive-long-horizon-swarm-execution.mdnew file mode 100644index 0000000000..0d1f54cd7b--- /dev/null+++ b/v3/docs/adr/ADR-385-streaming-interactive-long-horizon-swarm-execution.md@@ -0,0 +1,62 @@+# ADR-385: Streaming, interactive, long-horizon swarm execution β model the console swarm on ruflo's research agents++**Status:** Proposed+**Date:** 2026-09-10+**Author:** Claude Code (for rUv), after the ruOS console Swarms page shipped a deploy that "set up then finished before anything useful happened."++**Relates to:** ADR-057 (agent tasks & swarms), ADR-069 (per-tenant LLM gateway β the key dependency), ADR-099 (dossier-investigator recursive parallel research), ADR-164 (agentbbs federation), ADR-101/ADR-325 (federated claims). Reference implementation model: the `ruflo-goals:deep-researcher`, `ruflo-goals:dossier-investigator`, `ruflo-goals:horizon-tracker`, and `ruflo-agent:nested-*` agents.++## Context β why the swarm does nothing useful++`ruflo swarm start` (`commands/swarm.ts:588β672`) **never executes the objective.** It prints the objective, prints a static Agent Deployment Plan table, calls MCP `swarm_init` (topology only), writes `.swarm/state.json`, and then prints, verbatim:++> "This CLI coordinates agent state. Execution happens via: Claude Code Agent tool (interactive) / claude -p (headless background) / hive-mind spawn --claude (autonomous)."++β¦and returns `success`. Nothing invokes any of those drivers. The console's Swarms deploy runs this over `/run` with a 30 s timeout and streams the CLI's stdout β so a user sees `[OK] Agent X spawned`, a plan table, `Total: 15 agents`, `SUCCESS in 44s`, a transcript path, and **no work, no artifacts, nothing to find/use/deploy.** The agents are registry rows with no running process (confirmed live in the #3253 investigation). This is by design: `swarm start` is set-up-and-defer, and the deferral target is never called.++rUv's three requirements:+1. **Actually collaborate + produce output** β agents do the objective, not just register.+2. **Stream like Claude Code**, and take **real-time guidance mid-run** β not fire-and-forget.+3. A **final overview**: what it did, where the output is, how to use/deploy it.+4. Do it as **multi-agent, multi-tool, federated, long-horizon agentic flows using ruflo's capabilities**, modelled on the **research agents**.++## Decision++**`swarm start` becomes a streaming, steerable, long-horizon agentic orchestrator that WIRES ruflo's existing execution primitives** β it stops deferring. It adopts the research-agent pattern that already works in-repo (recursive parallel fan-out, per-claim provenance, budget caps, streamed progress, horizon persistence) rather than inventing a new engine.++### D1 β Execute, don't defer (the core change)+`swarm start --execute` (and the console default) runs the objective. Each planned agent is a real agentic worker driven by an existing ruflo primitive β the same `claude -p` / nested-orchestrator path the research agents use (`ruflo-agent:nested-queen` β `nested-*-researcher`/`-reviewer`/`-leaf`). The coordinator decomposes the objective; workers fan out in parallel (the `dossier-investigator` recursive pattern, ADR-099); results reduce back through hive-mind consensus (raft) for anti-drift.++### D2 β Stream every token (like Claude Code)+Each worker's output streams to stdout as NDJSON events (`{agent, phase, kind:'token'|'tool'|'result', data, ts}`), interleaved with agent labels β exactly what the console's SSE `/run` already pipes through live. No new transport is needed for **output** streaming; the fix is that `swarm start` must *emit* the stream instead of a summary table. This alone converts "set then done" into "watchable work."++### D3 β Real-time guidance (the one new transport)+Output streaming is one-way; **steering the swarm mid-run needs a bidirectional channel.** The console's `/run` SSE cannot carry input back. Introduce a **swarm session**: `swarm start --session <id>` writes guidance-inbox at `.swarm/sessions/<id>/inbox.jsonl`; a `swarm guide <id> "<message>"` command (and a console input box) appends to it; the running coordinator polls the inbox between turns and injects guidance into the next worker prompt. Ruflo-native, file-based first (works over `/run`), upgradeable to a WebSocket in ruos-desktop later.++### D4 β Multi-tool, memory, hooks, federation, long-horizon (ruflo capabilities)+- **Multi-tool:** workers get the MCP tool surface (they already can via ToolSearch) β so a coder writes files, a tester runs them, a researcher fetches.+- **Memory:** objective + intermediate findings persist to AgentDB (HNSW recall) so a resumed session continues instead of restarting β the horizon-tracker pattern.+- **Hooks:** every worker turn records a trajectory step (self-learning), so the swarm improves across runs.+- **Federation (long-horizon, cross-node):** for objectives that outlive one machine or need external compute, workers claim work and publish results over agentbbs / x.ruv.io (ADR-164) β the federation coordination plane. Claims prevent duplicate work (ADR-325).+- **Long-horizon:** `horizon-tracker` persists milestones + drift detection so a multi-hour objective survives restarts and resumes mid-plan.++### D5 β A structured final overview+On completion the swarm emits a structured summary (`--format json` and a rendered card): objective, agent roster (role/type/model), topology + consensus + swarm id, **artifacts produced** (files created/changed with paths), **where to find/run/deploy** them, memory keys written, the transcript path, and **next steps**. The console renders this as a result card instead of dumping CLI noise. This is the "what it did / where it is / how to deploy" overview.++## Hard dependencies (stated plainly)+1. **Agents cannot run without a model key.** D1 needs the per-tenant LLM gateway (ADR-069, PR #120) deployed and `RUOS_LLM_GATE_SECRET` set β otherwise `claude -p` on the desktop falls through to whatever login exists (the 2026-09-09 failure). Streaming a swarm that has no key just streams auth errors. **ADR-069 is a prerequisite for the console path.**+2. **Real-time guidance needs the bidirectional channel** (D3). File-inbox works over `/run` today; true low-latency steering wants a WebSocket session in ruos-desktop.++## Increments+- **I1 β Streaming execution.** `swarm start --execute` runs the objective via the nested-orchestrator/`claude -p` path and streams NDJSON. (ruflo, clean repo; gated on a key at runtime.)+- **I2 β Final overview.** Structured JSON summary + console result card (D5).+- **I3 β Guidance inbox.** `swarm guide` + coordinator poll + console input box (D3).+- **I4 β Federation + long-horizon.** agentbbs claim/publish + horizon-tracker persistence (D4) for cross-node, multi-hour objectives.++## Acceptance test+Deploy a swarm with a real objective ("add a /health endpoint with a test") from the console; watch worker output stream token-by-token; send a mid-run guidance message ("also return build SHA") and see the next turn honour it; on completion see a result card naming the file(s) created, how to run the test, and the transcript β then find those files on the desktop. (Mirrors the research-agent + ADR-069 e2e already exercised this session.)++## Consequences+- `swarm start`'s current defer-message becomes a fallback only when no key is configured (honest degradation, not a silent no-op).+- This supersedes the "coordination-only" reading of ADR-057's swarm surface: the swarm now executes.+- The console Swarms page's deploy verdict (ruos-desktop #122) is the seam the D5 overview card plugs into.