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(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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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