π 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(performance): #3562 MessageBus event-driven dispatch replaces unconditional 10ms poll
Claude4904075db690
diff --git a/v3/@claude-flow/swarm/__tests__/message-bus.event-driven.test.ts b/v3/@claude-flow/swarm/__tests__/message-bus.event-driven.test.tsnew file mode 100644index 0000000000..18bcd5858b--- /dev/null+++ b/v3/@claude-flow/swarm/__tests__/message-bus.event-driven.test.ts@@ -0,0 +1,155 @@+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';+import { MessageBus, createMessageBus } from '../src/message-bus.js';++// Dream Cycle 2026-09-30 (performance): MessageBus.processQueues() used to be+// driven purely by a fixed setInterval(processingIntervalMs) poll, so both+// delivery latency and retry redelivery were bounded by whatever interval a+// caller configured β both production callers (UnifiedSwarmCoordinator,+// SwarmHub) configure 10ms, meaning 100 wakeups/sec per active swarm even+// with zero traffic. Dispatch is now event-driven (triggered from+// enqueue()/retry re-queuing via scheduleProcessing()); the configured+// interval is floored to a >=250ms backstop that should rarely, if ever,+// actually fire under normal traffic. These tests use a deliberately slow+// configured interval (5000ms) to prove delivery/retry no longer depend on+// it, and a production-matching interval (10ms) to prove wakeup count drops.++describe('MessageBus - event-driven dispatch (dream-cycle 2026-09-30)', () => {+ let bus: MessageBus;++ afterEach(async () => {+ await bus.shutdown();+ });++ it('delivers a healthy subscriber near-instantly even with a slow configured backstop interval', async () => {+ bus = createMessageBus({+ processingIntervalMs: 5000,+ ackTimeoutMs: 1000,+ });+ await bus.initialize();++ let deliveredEvents = 0;+ bus.on('message.delivered', () => {+ deliveredEvents++;+ });++ bus.subscribe('agent-good', () => {});++ await bus.send({+ type: 'direct',+ from: 'agent-sender',+ to: 'agent-good',+ payload: { hello: 'world' },+ priority: 'normal',+ requiresAck: false,+ ttlMs: 60000,+ });++ // With a 5000ms configured interval, a poll-only baseline would still be+ // waiting for the first tick here β event-driven dispatch should not be.+ await new Promise((resolve) => setTimeout(resolve, 100));++ expect(deliveredEvents).toBe(1);+ });++ it('retries a failing subscriber promptly, independent of a slow configured backstop interval', async () => {+ bus = createMessageBus({+ processingIntervalMs: 5000,+ retryAttempts: 3,+ ackTimeoutMs: 1000,+ });+ await bus.initialize();++ let callbackInvocations = 0;+ let failedEvents = 0;+ let retryEvents = 0;++ bus.on('message.failed', () => {+ failedEvents++;+ });+ bus.on('message.retry', () => {+ retryEvents++;+ });++ bus.subscribe('agent-bad', () => {+ callbackInvocations++;+ throw new Error('simulated handler crash');+ });++ await bus.send({+ type: 'direct',+ from: 'agent-good',+ to: 'agent-bad',+ payload: { hello: 'world' },+ priority: 'normal',+ requiresAck: false,+ ttlMs: 60000,+ });++ // Baseline (interval-only dispatch) would deliver nothing at all within+ // this window since the configured interval (5000ms) hasn't ticked yet.+ await new Promise((resolve) => setTimeout(resolve, 300));++ expect(callbackInvocations).toBe(3);+ expect(retryEvents).toBe(2);+ expect(failedEvents).toBe(1);+ });++ it('floors an aggressive configured interval to a low-frequency idle backstop instead of busy-polling', async () => {+ bus = createMessageBus({+ // Matches both production callers (UnifiedSwarmCoordinator,+ // SwarmHub), which explicitly configure 10ms today.+ processingIntervalMs: 10,+ });++ const processQueuesSpy = vi.spyOn(bus as unknown as { processQueues: () => void }, 'processQueues');++ await bus.initialize();++ // No messages sent β this is the idle-window case the hypothesis+ // targets. A pure 10ms poll would fire ~26 times in 260ms; a >=250ms+ // backstop fires at most once or twice.+ await new Promise((resolve) => setTimeout(resolve, 260));++ expect(processQueuesSpy.mock.calls.length).toBeLessThanOrEqual(3);+ });++ it('delivers a message that was enqueued before its subscriber arrived, promptly, not just at the next backstop tick', async () => {+ // Adversarial-critic finding (2026-09-30): a coordinator can send() to an+ // agentId it just spawned before that agent's subscribe() call lands.+ // processQueues() skips any queue with no matching subscription, so+ // without subscribe() itself triggering a pass, that message would only+ // surface at the next backstop tick.+ bus = createMessageBus({+ processingIntervalMs: 5000,+ ackTimeoutMs: 1000,+ });+ await bus.initialize();++ let deliveredEvents = 0;+ bus.on('message.delivered', () => {+ deliveredEvents++;+ });++ await bus.send({+ type: 'direct',+ from: 'agent-sender',+ to: 'agent-late',+ payload: { hello: 'world' },+ priority: 'normal',+ requiresAck: false,+ ttlMs: 60000,+ });++ // Simulate a realistic gap between send() and the target agent's own+ // subscribe() call (e.g. spawn latency) β long enough that any+ // in-flight scheduleProcessing() pass from send() itself has already+ // run and found no subscriber.+ await new Promise((resolve) => setTimeout(resolve, 20));++ bus.subscribe('agent-late', () => {});++ await new Promise((resolve) => setTimeout(resolve, 100));++ expect(deliveredEvents).toBe(1);+ });+});diff --git a/v3/@claude-flow/swarm/__tests__/message-bus.perf.test.ts b/v3/@claude-flow/swarm/__tests__/message-bus.perf.test.tsnew file mode 100644index 0000000000..79b45c8c9e--- /dev/null+++ b/v3/@claude-flow/swarm/__tests__/message-bus.perf.test.ts@@ -0,0 +1,117 @@+import { describe, it, expect, vi } from 'vitest';+import { MessageBus, createMessageBus } from '../src/message-bus.js';++// Dream Cycle 2026-09-30 (performance) real wall-clock evidence for the+// MessageBus event-driven dispatch fix. These are sanity/regression bounds,+// not the baseline-vs-candidate discriminator (that's+// message-bus.event-driven.test.ts, run stash-isolated against baseline).+// Numbers are logged so they can be copied into the dream-cycle gist/issue.++describe('MessageBus - performance evidence (dream-cycle 2026-09-30)', () => {+ it('idle-window processQueues() wakeups stay near the backstop floor at a production-matching interval', async () => {+ const bus = createMessageBus({ processingIntervalMs: 10 }); // matches UnifiedSwarmCoordinator/SwarmHub+ const spy = vi.spyOn(bus as unknown as { processQueues: () => void }, 'processQueues');+ await bus.initialize();++ const windowMs = 2000;+ await new Promise((resolve) => setTimeout(resolve, windowMs));+ await bus.shutdown();++ const calls = spy.mock.calls.length;+ const naiveBaselineCalls = Math.floor(windowMs / 10); // what the old 10ms poll would produce+ const reduction = 1 - calls / naiveBaselineCalls;++ console.log(+ `[perf] idle-window (${windowMs}ms, processingIntervalMs=10): candidate=${calls} calls, ` ++ `pre-fix-poll-equivalent=${naiveBaselineCalls} calls, reduction=${(reduction * 100).toFixed(1)}%`+ );++ expect(calls).toBeLessThanOrEqual(Math.ceil(windowMs / 250) + 1);+ expect(reduction).toBeGreaterThan(0.9);+ });++ it('single-message delivery latency is near-instant (event-driven) at a production-matching interval', async () => {+ const bus = createMessageBus({ processingIntervalMs: 10 });+ await bus.initialize();+ bus.subscribe('agent-good', () => {});++ const samples: number[] = [];+ const N = 20;+ for (let i = 0; i < N; i++) {+ const start = performance.now();+ await new Promise<void>((resolve) => {+ bus.once('message.delivered', () => resolve());+ void bus.send({+ type: 'direct',+ from: 'agent-sender',+ to: 'agent-good',+ payload: { i },+ priority: 'normal',+ requiresAck: false,+ ttlMs: 60000,+ });+ });+ samples.push(performance.now() - start);+ }+ await bus.shutdown();++ const mean = samples.reduce((a, b) => a + b, 0) / N;+ const max = Math.max(...samples);+ console.log(+ `[perf] single-message delivery latency (N=${N}, processingIntervalMs=10): mean=${mean.toFixed(3)}ms max=${max.toFixed(3)}ms`+ );++ // Old interval-driven dispatch averaged ~half the 10ms tick (~5ms) with+ // worst case near 10ms; event-driven dispatch should land well under that.+ expect(mean).toBeLessThan(5);+ });++ it('saturated-load throughput does not regress vs. the pre-fix batched-poll baseline', async () => {+ const bus = createMessageBus({ processingIntervalMs: 10 });+ await bus.initialize();++ let delivered = 0;+ bus.subscribe('agent-good', () => {+ delivered++;+ });++ const TOTAL = 2000;+ const start = performance.now();+ const sendPromises: Promise<string>[] = [];+ for (let i = 0; i < TOTAL; i++) {+ sendPromises.push(+ bus.send({+ type: 'direct',+ from: 'agent-sender',+ to: 'agent-good',+ payload: { i },+ priority: 'normal',+ requiresAck: false,+ ttlMs: 60000,+ })+ );+ }+ await Promise.all(sendPromises);++ // Drain: wait for delivery to catch up (event loop needs to process the+ // setImmediate-scheduled processQueues()/deliverMessage() chain).+ const deadline = performance.now() + 10000;+ while (delivered < TOTAL && performance.now() < deadline) {+ await new Promise((resolve) => setTimeout(resolve, 5));+ }+ const elapsed = performance.now() - start;+ await bus.shutdown();++ const throughput = TOTAL / (elapsed / 1000);+ console.log(+ `[perf] saturated throughput (N=${TOTAL}, processingIntervalMs=10): delivered=${delivered}/${TOTAL} ` ++ `elapsed=${elapsed.toFixed(1)}ms throughput=${throughput.toFixed(0)} msg/s`+ );++ expect(delivered).toBe(TOTAL);+ // Module header targets 1000+ msgs/sec; regression threshold from the+ // frozen hypothesis (<=5% vs baseline) is checked via the stash-isolated+ // comparison recorded in the PR/issue β this is the standalone sanity floor.+ expect(throughput).toBeGreaterThan(1000);+ });+});diff --git a/v3/@claude-flow/swarm/src/message-bus.ts b/v3/@claude-flow/swarm/src/message-bus.tsindex 4a76c4e1b4..22d51a4045 100644--- a/v3/@claude-flow/swarm/src/message-bus.ts+++ b/v3/@claude-flow/swarm/src/message-bus.ts@@ -227,6 +227,8 @@ export class MessageBus extends EventEmitter implements IMessageBus {private pendingAcks: Map<string, { message: Message; timeout: NodeJS.Timeout }> = new Map();private processingInterval?: NodeJS.Timeout;private statsInterval?: NodeJS.Timeout;+ private processScheduled: boolean = false;+ private isShutdown: boolean = false;private messageCounter: number = 0;private stats: MessageBusStats;private startTime: Date = new Date();@@ -234,6 +236,11 @@ export class MessageBus extends EventEmitter implements IMessageBus {private messageHistory: { timestamp: number; count: number }[] = [];private messageHistoryIndex: number = 0;private static readonly MAX_HISTORY_SIZE = 60;+ // processQueues() is now primarily triggered event-driven (see+ // scheduleProcessing()); the interval below is a low-frequency backstop+ // only, so a caller-configured processingIntervalMs is floored here+ // rather than driving per-tick dispatch directly (dream-cycle 2026-09-30).+ private static readonly MIN_BACKSTOP_INTERVAL_MS = 250;constructor(config: Partial<MessageBusConfig> = {}) {super();@@ -261,12 +268,20 @@ export class MessageBus extends EventEmitter implements IMessageBus {this.config = { ...this.config, ...config };}+ this.isShutdown = false;this.startProcessing();this.startStatsCollection();this.emit('initialized');}async shutdown(): Promise<void> {+ // Guards scheduleProcessing() against scheduling a new setImmediate+ // after teardown (e.g. a straggler delivery failure retrying right as+ // shutdown() runs) β harmless before this flag existed (processQueues()+ // just iterated the now-empty queues Map), but it's cleaner to not+ // schedule work post-shutdown at all.+ this.isShutdown = true;+if (this.processingInterval) {clearInterval(this.processingInterval);this.processingInterval = undefined;@@ -336,6 +351,7 @@ export class MessageBus extends EventEmitter implements IMessageBus {this.updateLatencyStats(latency);this.emit('message.enqueued', { messageId: message.id, to: message.to });+ this.scheduleProcessing();return message.id;}@@ -370,8 +386,16 @@ export class MessageBus extends EventEmitter implements IMessageBus {});// Initialize queue for this agent- if (!this.queues.has(agentId)) {+ const queue = this.queues.get(agentId);+ if (!queue) {this.queues.set(agentId, new PriorityMessageQueue());+ } else if (queue.length > 0) {+ // Messages can be enqueued for an agentId before that agent's+ // subscribe() call lands (e.g. a coordinator sending to an agent it+ // just spawned) β processQueues() skips any queue with no matching+ // subscription, so without this those messages would otherwise only+ // surface at the next backstop tick instead of immediately.+ this.scheduleProcessing();}this.emit('subscription.added', { agentId });@@ -403,13 +427,48 @@ export class MessageBus extends EventEmitter implements IMessageBus {}private startProcessing(): void {+ // Dispatch is event-driven via scheduleProcessing() (triggered from+ // enqueue() and from retry re-queuing); this interval is only a+ // low-frequency backstop for whatever it might miss, so a small+ // caller-configured processingIntervalMs no longer forces a busy-poll β+ // it's floored at MIN_BACKSTOP_INTERVAL_MS.+ const backstopIntervalMs = Math.max(+ this.config.processingIntervalMs,+ MessageBus.MIN_BACKSTOP_INTERVAL_MS+ );this.processingInterval = setInterval(() => {this.processQueues();- }, this.config.processingIntervalMs);+ }, backstopIntervalMs);+ }++ // Coalesces bursts of synchronous enqueue()/retry calls within the same+ // tick into a single processQueues() pass on the next macrotask, instead+ // of polling on a fixed interval regardless of whether any queue holds a+ // message.+ private scheduleProcessing(): void {+ if (this.processScheduled || this.isShutdown) {+ return;+ }+ this.processScheduled = true;+ setImmediate(() => {+ this.processScheduled = false;+ if (this.isShutdown) {+ return;+ }+ this.processQueues();+ });}private processQueues(): void {const now = Date.now();+ // Each agent is capped at a 10-message batch per pass (below); if a+ // burst left more than that queued, drain the rest on the next+ // macrotask instead of stalling until the backstop interval fires β+ // otherwise a large synchronous burst (many enqueue() calls coalesced+ // by scheduleProcessing() into one pass) would only ever drain its+ // first 10-per-agent messages promptly and leave the remainder to+ // trickle in at the >=250ms backstop rate.+ let hasRemainingWork = false;for (const [agentId, queue] of this.queues) {const subscription = this.subscriptions.get(agentId);@@ -444,6 +503,14 @@ export class MessageBus extends EventEmitter implements IMessageBus {for (const entry of batch) {this.deliverMessage(subscription, entry);}++ if (queue.length > 0) {+ hasRemainingWork = true;+ }+ }++ if (hasRemainingWork) {+ this.scheduleProcessing();}}@@ -504,6 +571,7 @@ export class MessageBus extends EventEmitter implements IMessageBus {// message.failed) are silently lost. Only the direct-message path// is bounded by this fix.this.addToQueue(message.to, message, entry.attempts);+ this.scheduleProcessing();this.emit('message.retry', {messageId: message.id,attempt: entry.attempts