Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

dream(swarm): harden pool-add fix + research gist (post-critique round 2)

Claude6d5699e8521d
diff --git a/docs/dream-cycle/dream-gist-2026-09-29.md b/docs/dream-cycle/dream-gist-2026-09-29.md
new file mode 100644
index 0000000000..85d8ee77f8
--- /dev/null
+++ b/docs/dream-cycle/dream-gist-2026-09-29.md
@@ -0,0 +1,64 @@
+# Swarm SOTA Report β€” 2026-09-29
+
+TL;DR: Ruflo's own `@claude-flow/swarm` package ships real Raft/Byzantine/gossip consensus and a domain-based agent-pool router, ahead of every LLM-orchestration competitor surveyed on multi-agent liveness/consensus β€” but `UnifiedSwarmCoordinator.spawnAgent()`'s plain agentic-flow-compatible call path (no `domain`/`agentNumber` given) silently never added the new agent to its domain's `AgentPool`, so `assignTaskToDomain()` either scale-up-created a *different*, duplicate agent or queued forever, while the original agent sat idle and permanently unused. Fixed with a 6-line, single-file change; independent adversarial critique found one real edge-case regression the fix introduced (a new uncaught throw when an auto-domain spawn pushes a small/full domain pool over capacity), closed same session with a try/catch + a new event. 4 new discriminating tests, baseline-fails/candidate-passes, full 241/241 package suite green, `tsc --noEmit` clean.
+
+## What's New in 2026
+
+| Finding | Source | Confidence |
+|---|---|---|
+| Microsoft Agent Framework reached 1.0 GA (Apr 2026), converging AutoGen + Semantic Kernel; AutoGen itself moved to maintenance mode Oct 2025 | Official Microsoft devblogs + learn.microsoft.com, cross-checked | B |
+| LangGraph ships real per-node `RetryPolicy`/idle-timeout liveness (2026-06-04 blog); Temporal's Activity Heartbeats are the closest production analog to Ruflo's own heartbeat-timeout health checks | Official LangChain + Temporal docs, both read directly | A |
+| No LLM-orchestration framework surveyed (LangGraph, Microsoft Agent Framework, CrewAI, OpenAI Agents SDK) implements cross-agent voting/quorum/BFT β€” each has exactly one authoritative decision-maker per turn | Official docs for all 4, read directly | A |
+| A 2026 arXiv position paper proposes SWIM/Fireflies-style gossip failure-suspicion for agentic multi-agent systems β€” architecturally exactly what Ruflo's already-shipped `GossipConsensusEngine` could be repurposed for, but currently isn't (used only for consensus, not liveness) | Single arXiv position paper, not independently reproduced | C |
+| "Centralized orchestration has limited scalability (3-7 agents) and low fault tolerance" is a widely-repeated 2026 blog claim, but no primary benchmark was cited or independently reproduced | Single dev.to synthesis post | C |
+
+## Ruflo Current Capability
+
+`@claude-flow/swarm/src/{consensus/{raft,byzantine,gossip}.ts, unified-coordinator.ts, agent-pool.ts, topology-manager.ts, federation-hub.ts, message-bus.ts}` implement real Raft election/heartbeat, Byzantine voting, and gossip dissemination, plus a domain-sharded `AgentPool` (min/max size, auto scale-up/down) that `assignTaskToDomain()` draws from via `pool.acquire()`. Tonight's fix closes a wiring gap in the third of `spawnAgent()`'s three branches β€” the two domain-aware branches (`agentNumber`/`domain` given) already call `pool.add()` via `registerAgentWithDomain()`; the auto-domain branch (`unified-coordinator.ts:1685-1690`) did not.
+
+## Competitor Comparison
+
+| Framework | Coordination/Consensus mechanism | Liveness/health mechanism | Gap type vs Ruflo | Grade |
+|---|---|---|---|---|
+| LangGraph | Single-writer supervisor/swarm handoff, no voting | Per-node `RetryPolicy` + idle-timeout, scoped to one process | Solved differently β€” single authoritative thread substitutes checkpoint-resume for consensus | A |
+| Microsoft Agent Framework (AutoGen successor, GA 2026-04) | Centralized group-chat orchestrator picks next speaker; no cross-agent vote | Undocumented β€” no heartbeat/health policy for a stuck participant | Open gap, not deliberately avoided | A |
+| CrewAI | Hierarchical manager delegates by role, no voting mechanism | `max_iterations` only; no worker health/liveness signal documented | Open gap β€” closest to "no liveness at all" among surveyed frameworks | A (mechanism) / B (production-gap claim) |
+| OpenAI Agents SDK | LLM-driven tool-call handoffs; "no consensus or voting mechanism" by design | Not documented β€” one LLM call in flight at a time, liveness not a first-class question | Open gap by design omission | A |
+| Temporal (distributed-systems-adjacent) | Single authoritative service, not peer voting | Activity Heartbeats + Schedule/Start-To-Close timeouts β€” real, production-proven pattern | Solved, but centralizes trust in one service rather than tolerating the coordinator itself failing | A |
+
+No competitor attempts Ruflo's actual hardest problem (agreement that survives the coordinator itself failing); Ruflo's differentiation is real at the algorithm-library level, though β€” per tonight's own research β€” its top-level `SwarmCoordinator.reachConsensus()` convenience API (a *different*, DDD-application-layer class from the fixed `UnifiedSwarmCoordinator`) is still a `Math.random()` stub with zero production callers, a good candidate for a future night.
+
+## Hypothesis
+
+> Given `UnifiedSwarmCoordinator.spawnAgent()` called with no `domain`/`agentNumber` (the plain agentic-flow-compatible call shape), when the auto-domain branch is fixed to call `pool.add(agent)` after `registerAgent()` β€” mirroring `registerAgentWithDomain()`'s existing pattern β€” then `assignTaskToDomain(taskId, domain)` should route work to the agent `spawnAgent()` actually returned, relative to baseline where it silently acquires/creates a different orphaned agent (if the pool isn't at `maxSize`) or queues forever (if it is), subject to: (1) the two existing domain-aware branches are unaffected; (2) all existing `@claude-flow/swarm` tests remain green; (3) $0, deterministic, zero LLM calls.
+
+Frozen before evaluation; not modified after seeing results.
+
+## Benchmarks / Evaluation
+
+**evaluated: accepted (post-hardening).** Real evaluator: Vitest 4.1.8, deterministic, $0, zero LLM calls, against a freshly `pnpm install`-ed `v3/` workspace. New file `v3/@claude-flow/swarm/__tests__/spawn-agent-domain-pool.test.ts` (4 tests). Baseline (`git stash` isolated to `unified-coordinator.ts` only): 2/3 fail exactly as predicted β€” pool stats report `total: 0` after spawn, and `assignTaskToDomain()` returns a different, freshly scale-up-created agent id (`core-domain-pool_agent_1`) instead of the one `spawnAgent()` returned (`agent_swarm_..._1`). Candidate (round 1): 3/3 pass; full `@claude-flow/swarm` package suite 237/237 (13 files) β†’ 240/240 (14 files, +3 new), zero regressions, `tsc --noEmit` 0 errors β€” independently re-reproduced by an adversarial critic subagent with byte-identical results.
+
+**Post-critique hardening**: the critic found that `pool.add()` throws once a domain pool is at its small fixed `maxSize` (e.g. `queen` caps at 1 β€” `agentTypeToDomain()` maps `queen`/`coordinator` there), and the new call wasn't wrapped in try/catch β€” a second auto-domain `queen`/`coordinator` spawn now threw `Pool queen-domain-pool is at maximum capacity`, a regression versus baseline's silent (if buggy) success, and at least one caller (`v3/mcp/tools/swarm-tools.ts`'s scale-up loop) doesn't try/catch individual `spawnAgent()` calls. Reproduced independently against the patched code before fixing. Closed same session: `pool.add()` wrapped in try/catch, emitting a new `agent.domain_pool_full` event on the caught path instead of throwing β€” the agent stays registered/idle either way, degrading to the pre-fix pool-invisible state rather than failing the caller. New 4th test: manually reverted just the try/catch, confirmed it reproduces the critic's exact throw, restored, reconfirmed green. Full suite (with hardening): **241/241** (14 files), `tsc --noEmit` 0 errors.
+
+## Darwin Results
+
+Skipped β€” binary wiring/correctness fix (an agent is pool-visible or it isn't), no continuous/categorical parameter with a fitness gradient for Darwin's real interface (`npx ruvector harness darwin <config> --execute`, confirmed available, v0.9.2) to search over. Same skip class as nearly every accepted dream-cycle night since 2026-08-18.
+
+## SOTA Proof & Witness
+
+Reward-hack check (manual checklist, no standalone reward-hack CLI reachable β€” confirmed via `npx ruvector harness --help`): no test weakened (new file only, existing 237 tests untouched); no gold data touched (none exists on this path); no cherry-picking (full suite disclosed at every stage, both ways); no seed manipulation; zero cost; no undocumented caching; no error suppression hiding a real failure (the hardening's `catch` re-emits an observable event rather than silently swallowing). Security review: not security-sensitive β€” pure in-process `Map`/`Set` bookkeeping on an internally-generated `agentId`, no new I/O/network/credential/filesystem surface (independently confirmed by the critic).
+
+**Independent adversarial critique** (separate subagent, no authoring context): **CONFIRMED-WITH-CAVEATS** on round 1 (fix mechanism verified correct via its own independent stash/pop reproduction; one real edge-case regression found β€” see Evaluation above); the caveat was closed same session and re-verified.
+
+| Field | Value |
+|---|---|
+| Session commit | `PENDING` |
+| Gist SHA-256 (pre-witness content) | `PENDING` |
+| Witness stamp | `PENDING` |
+
+## Recommended Next Steps
+
+1. **This fix**: human review and merge β€” two small source edits (the pool-add wiring plus its own hardening) and one new test file, one conceptual change, zero regressions, matches the precedent class of #3357/#3378.
+2. **Future `swarm`/`security` night**: wire `SwarmCoordinator.reachConsensus()` (`v3/src/coordination/application/SwarmCoordinator.ts:368-394`) off its `Math.random() > 0.5` stub β€” it is a live, exported public API (from `v3/src/index.ts`) with a currently non-discriminating test, though zero in-repo production callers today.
+3. **Future `swarm` night**: port the event-driven-wait pattern (#3378/#3443) into the 4 sibling busy-polls still live in `consensus/{raft,byzantine,gossip}.ts`'s `awaitConsensus()` and `federation-hub.ts`'s `waitForAgentCompletion()` β€” all four already emit the exact event being polled for at 10-100ms granularity, on every real consensus decision and cross-swarm ephemeral spawn.
+4. **Future `swarm` night**: `FederationHub.terminateAgent()` is not idempotent (double-counts `completedAgents`/`totalAgentLifespanMs` when called twice, e.g. from `shutdown()` racing `unregisterSwarm()`) β€” zero test coverage today, ~3-line fix.
diff --git a/v3/@claude-flow/swarm/__tests__/spawn-agent-domain-pool.test.ts b/v3/@claude-flow/swarm/__tests__/spawn-agent-domain-pool.test.ts
index 851aba2574..e9895dba17 100644
--- a/v3/@claude-flow/swarm/__tests__/spawn-agent-domain-pool.test.ts
+++ b/v3/@claude-flow/swarm/__tests__/spawn-agent-domain-pool.test.ts
@@ -91,6 +91,34 @@ describe('spawnAgent() auto-domain branch β€” domain pool visibility', () => {
expect(task?.assignedTo?.id).toBe(agentId);
});
+ it('does not throw when an auto-domain spawn pushes a full domain pool over capacity', async () => {
+ // 'queen'/'coordinator' both map to the 'queen' domain, whose pool is
+ // capped at maxSize 1 (DOMAIN_CONFIGS: agentNumbers: [1]). A second
+ // auto-domain spawn into that domain must not reject spawnAgent() itself
+ // (callers like the MCP scale-up loop don't wrap this call in try/catch)
+ // β€” it should degrade to the pre-fix pool-invisible state instead.
+ const first = await coordinator.spawnAgent({ type: 'queen' });
+ expect(first.domain).toBe('queen');
+
+ let poolFullEvent: unknown;
+ coordinator.once('agent.domain_pool_full', (event) => {
+ poolFullEvent = event;
+ });
+
+ const second = await coordinator.spawnAgent({ type: 'coordinator' });
+ expect(second.domain).toBe('queen');
+ expect(second.spawned).toBe(true);
+
+ // The second agent is still registered and idle, just not pool-visible.
+ const secondAgent = coordinator.getAgent(second.agentId);
+ expect(secondAgent?.status).toBe('idle');
+ expect(secondAgent).toBeDefined();
+
+ const pool = coordinator.getDomainPool('queen');
+ expect(pool!.getPoolStats().total).toBe(1);
+ expect(poolFullEvent).toBeDefined();
+ });
+
it('still works correctly via the domain-aware branches (regression guard)', async () => {
// registerAgentWithDomain()'s own pool.add() call path must be
// unaffected by this fix.
diff --git a/v3/@claude-flow/swarm/src/types.ts b/v3/@claude-flow/swarm/src/types.ts
index edc7b921a1..b8952ea457 100644
--- a/v3/@claude-flow/swarm/src/types.ts
+++ b/v3/@claude-flow/swarm/src/types.ts
@@ -357,6 +357,7 @@ export type SwarmEventType =
| 'agent.status_changed'
| 'agent.heartbeat'
| 'agent.domain_assigned'
+ | 'agent.domain_pool_full'
| 'task.created'
| 'task.assigned'
| 'task.started'
diff --git a/v3/@claude-flow/swarm/src/unified-coordinator.ts b/v3/@claude-flow/swarm/src/unified-coordinator.ts
index 53ab8b62f5..145a08a476 100644
--- a/v3/@claude-flow/swarm/src/unified-coordinator.ts
+++ b/v3/@claude-flow/swarm/src/unified-coordinator.ts
@@ -1691,10 +1691,20 @@ export class UnifiedSwarmCoordinator extends EventEmitter implements IUnifiedSwa
// Add to domain pool so assignTaskToDomain() can route work to this
// agent (mirrors registerAgentWithDomain()'s pool.add() above; without
// this the agent is registered/idle but invisible to pool.acquire()).
+ // pool.add() throws once a domain pool is at its (small, fixed)
+ // maxSize (e.g. the 'queen' domain caps at 1) β€” the agent stays
+ // registered either way, so a full pool degrades back to today's
+ // pre-fix state (pool-invisible) instead of failing spawnAgent()
+ // itself for callers (e.g. a scale-up loop) that don't expect it to
+ // throw.
const pool = this.domainPools.get(domain);
const agent = this.state.agents.get(agentId);
if (pool && agent) {
- await pool.add(agent);
+ try {
+ await pool.add(agent);
+ } catch {
+ this.emitEvent('agent.domain_pool_full', { agentId, domain });
+ }
}
}