π 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
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.mdnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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 });+ }}}