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

perf(agentbbs): dedup PeerHello spam, dedup watch replays, O(1) seq append (#3257)

rUv9cb9c8448e72
diff --git a/v3/@claude-flow/cli/__tests__/agentbbs-tools.test.ts b/v3/@claude-flow/cli/__tests__/agentbbs-tools.test.ts
index 306f8341e8..bb7a0fb0f2 100644
--- a/v3/@claude-flow/cli/__tests__/agentbbs-tools.test.ts
+++ b/v3/@claude-flow/cli/__tests__/agentbbs-tools.test.ts
@@ -10,12 +10,18 @@
* matching the metaharness / agenticow / testgen contract.
*/
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { mkdtempSync, rmSync, existsSync, readFileSync } from 'node:fs';
+import { mkdtempSync, rmSync, existsSync, readFileSync, appendFileSync } from 'node:fs';
import { join } from 'node:path';
import { tmpdir } from 'node:os';
import { execFileSync } from 'node:child_process';
-import { agentbbsTools } from '../src/mcp-tools/agentbbs-tools.js';
+import {
+ agentbbsTools,
+ nextSeq,
+ lastPeerHelloMs,
+ shouldEmitHello,
+ dedupEnvelopes,
+} from '../src/mcp-tools/agentbbs-tools.js';
function findTool(name: string) {
const t = agentbbsTools.find(t => t.name === name);
@@ -200,3 +206,65 @@ describe('agentbbs MCP tools β€” happy path (real package)', () => {
expect(expiresAt - before).toBeGreaterThanOrEqual(120 * 1000 - 1000);
});
});
+
+describe('agentbbs β€” dedup + seq optimizations (ADR-164, PeerHello spam fix)', () => {
+ let dir: string;
+ beforeAll(() => { dir = mkdtempSync(join(tmpdir(), 'bbs-opt-')); });
+ afterAll(() => { rmSync(dir, { recursive: true, force: true }); });
+
+ it('shouldEmitHello: a genuinely new registration always emits', () => {
+ expect(shouldEmitHello(false, 1_000, -Infinity, 60)).toBe(true);
+ });
+
+ it('shouldEmitHello: re-register within the window is suppressed (kills the 8-hello spam)', () => {
+ // last hello 10s ago, 60s window -> suppress the retry
+ expect(shouldEmitHello(true, 60_000, 50_000, 60)).toBe(false);
+ });
+
+ it('shouldEmitHello: re-register past the window refreshes the heartbeat', () => {
+ // last hello 61s ago, 60s window -> emit a fresh heartbeat
+ expect(shouldEmitHello(true, 61_000, 0, 60)).toBe(true);
+ });
+
+ it('dedupEnvelopes: collapses duplicate envelopeIds, preserves order (first wins)', () => {
+ const out = dedupEnvelopes([
+ { envelopeId: 'a' }, { envelopeId: 'b' }, { envelopeId: 'a' }, { envelopeId: 'c' },
+ ]);
+ expect(out.map(e => e.envelopeId)).toEqual(['a', 'b', 'c']);
+ });
+
+ it('nextSeq: monotonic across 500 appends (tail-read stays exact)', () => {
+ const p = join(dir, 'room-seq.jsonl');
+ expect(nextSeq(p)).toBe(1); // no file yet
+ let seq = 0;
+ for (let i = 0; i < 500; i++) {
+ seq = nextSeq(p);
+ appendFileSync(p, JSON.stringify({ envelopeId: `e${i}`, roomId: 'r', seq, msgType: 'X', payload: {}, timestamp: new Date().toISOString() }) + '\n');
+ }
+ expect(seq).toBe(500);
+ expect(nextSeq(p)).toBe(501);
+ });
+
+ it('nextSeq: exact even when the log exceeds the tail read window (partial first line)', () => {
+ const p = join(dir, 'room-big.jsonl');
+ const pad = 'x'.repeat(2000); // ~2KB/line * 60 lines ~= 120KB > 64KB tail window
+ let seq = 0;
+ for (let i = 0; i < 60; i++) {
+ seq = nextSeq(p);
+ appendFileSync(p, JSON.stringify({ envelopeId: `e${i}`, roomId: 'r', seq, msgType: 'X', payload: { pad }, timestamp: new Date().toISOString() }) + '\n');
+ }
+ expect(seq).toBe(60);
+ expect(nextSeq(p)).toBe(61);
+ });
+
+ it('lastPeerHelloMs: most-recent PeerHello timestamp, ignoring other msgTypes', () => {
+ const p = join(dir, 'room-hello.jsonl');
+ expect(lastPeerHelloMs(p)).toBe(-Infinity); // no file
+ const t1 = '2026-09-10T00:00:00.000Z';
+ const t2 = '2026-09-10T00:05:00.000Z';
+ appendFileSync(p, JSON.stringify({ envelopeId: 'h1', roomId: 'r', seq: 1, msgType: 'PeerHello', payload: {}, timestamp: t1 }) + '\n');
+ appendFileSync(p, JSON.stringify({ envelopeId: 'x1', roomId: 'r', seq: 2, msgType: 'pod-status', payload: {}, timestamp: '2026-09-10T00:10:00.000Z' }) + '\n');
+ appendFileSync(p, JSON.stringify({ envelopeId: 'h2', roomId: 'r', seq: 3, msgType: 'PeerHello', payload: {}, timestamp: t2 }) + '\n');
+ expect(lastPeerHelloMs(p)).toBe(Date.parse(t2));
+ });
+});
diff --git a/v3/@claude-flow/cli/src/mcp-tools/agentbbs-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/agentbbs-tools.ts
index 474e6a0fa9..4e7b98ba47 100644
--- a/v3/@claude-flow/cli/src/mcp-tools/agentbbs-tools.ts
+++ b/v3/@claude-flow/cli/src/mcp-tools/agentbbs-tools.ts
@@ -35,7 +35,7 @@
* @module @claude-flow/cli/mcp-tools/agentbbs
*/
-import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync, statSync, openSync, readSync, closeSync } from 'node:fs';
import { resolve, isAbsolute, join } from 'node:path';
import { randomBytes, createHash } from 'node:crypto';
import { execFileSync } from 'node:child_process';
@@ -156,12 +156,85 @@ function readEnvelopes(path: string): BbsEnvelope[] {
return out;
}
-function nextSeq(path: string): number {
+// Tail of the log we scan to find the last seq. Envelopes are small; one line
+// always fits well inside this. Reading only the tail keeps append O(1) instead
+// of O(n) as a room log grows (ADR-164 Β§3.2.2 requires monotonic seq, and a
+// full re-parse on every publish was the cost).
+const SEQ_TAIL_BYTES = 65536;
+
+/** Last envelope's seq by scanning only the file tail; full-read fallback keeps it exact. */
+export function nextSeq(path: string): number {
+ if (!existsSync(path)) return 1;
+ try {
+ const size = statSync(path).size;
+ if (size === 0) return 1;
+ const start = Math.max(0, size - SEQ_TAIL_BYTES);
+ const fd = openSync(path, 'r');
+ let text: string;
+ try {
+ const buf = Buffer.alloc(size - start);
+ readSync(fd, buf, 0, buf.length, start);
+ text = buf.toString('utf-8');
+ } finally {
+ closeSync(fd);
+ }
+ // If we started mid-file the first fragment may be a partial line β€” drop it.
+ const lines = text.split(/\r?\n/).filter(l => l.trim());
+ const candidates = start > 0 && lines.length > 1 ? lines.slice(1) : lines;
+ for (let i = candidates.length - 1; i >= 0; i--) {
+ try {
+ const e = JSON.parse(candidates[i]);
+ if (typeof e.seq === 'number') return e.seq + 1;
+ } catch { /* keep scanning upward for the last parseable line */ }
+ }
+ } catch { /* fall through to the exact full-read path */ }
+ // Fallback: whole-file parse (rare β€” huge single line, or a tail with no seq).
const env = readEnvelopes(path);
if (env.length === 0) return 1;
return (env[env.length - 1].seq ?? env.length) + 1;
}
+/** Window within which a fresh PeerHello is suppressed as a duplicate (heartbeat, not spam). */
+const HELLO_WINDOW_SECS = Number(process.env.FEDERATION_BBS_HELLO_WINDOW_SECS ?? 60);
+
+/** Timestamp (ms) of the most recent PeerHello for a room, or -Infinity if none. */
+export function lastPeerHelloMs(logPath: string): number {
+ if (!existsSync(logPath)) return -Infinity;
+ const env = readEnvelopes(logPath);
+ for (let i = env.length - 1; i >= 0; i--) {
+ if (env[i].msgType === 'PeerHello') {
+ const t = Date.parse(env[i].timestamp);
+ return Number.isNaN(t) ? -Infinity : t;
+ }
+ }
+ return -Infinity;
+}
+
+/**
+ * Whether a `register` call should append a PeerHello: only for a genuinely new
+ * registration, or once the heartbeat window has elapsed since the last one.
+ * A re-register within the window is a retry and must NOT spam a near-identical
+ * hello. Pure β€” the decision the handler makes, exported for test.
+ */
+export function shouldEmitHello(
+ alreadyRegistered: boolean,
+ nowMs: number,
+ lastHelloMs: number,
+ windowSecs: number,
+): boolean {
+ return !alreadyRegistered || nowMs - lastHelloMs >= windowSecs * 1000;
+}
+
+/** Collapse duplicate envelopeIds, preserving order (first occurrence wins). Pure. */
+export function dedupEnvelopes<T extends { envelopeId: string }>(list: T[]): T[] {
+ const seen = new Set<string>();
+ return list.filter(e => {
+ if (seen.has(e.envelopeId)) return false;
+ seen.add(e.envelopeId);
+ return true;
+ });
+}
+
/**
* Ephemeral per-process Ed25519 keypair for human-join token signing.
* Phase 1 contract: keys are NOT persisted across process restart β€” every
@@ -240,6 +313,7 @@ export const agentbbsTools: MCPTool[] = [
existsSync(registryPath) ? JSON.parse(readFileSync(registryPath, 'utf-8')) : {};
// Idempotent β€” re-registering the same label updates timestamp but keeps id stable.
+ const alreadyRegistered = roomId in registry;
const entry = {
roomId,
roomLabel,
@@ -249,17 +323,27 @@ export const agentbbsTools: MCPTool[] = [
registry[roomId] = entry;
writeFileSync(registryPath, JSON.stringify(registry, null, 2));
- // Emit a synthetic PeerHello envelope into the room log so watchers see the join.
+ // Emit a PeerHello only when it carries information: a genuinely new
+ // registration, or a heartbeat refresh once HELLO_WINDOW_SECS has elapsed.
+ // A re-register within the window is a retry/no-op β€” appending a
+ // near-identical hello every call is the spam ADR-164 dedup guards against
+ // (observed live: one node published 8 near-identical PeerHellos).
const logPath = roomLogPath(basePath, roomId);
- const env: BbsEnvelope = {
- envelopeId: base64url(randomBytes(12)),
- roomId,
- seq: nextSeq(logPath),
- msgType: 'PeerHello',
- payload: { roomLabel, trustLevel: 'attested' },
- timestamp: entry.registeredAt,
- };
- appendFileSync(logPath, JSON.stringify(env) + '\n');
+ const nowMs = Date.parse(entry.registeredAt);
+ const helloEmitted = shouldEmitHello(
+ alreadyRegistered, nowMs, lastPeerHelloMs(logPath), HELLO_WINDOW_SECS,
+ );
+ if (helloEmitted) {
+ const env: BbsEnvelope = {
+ envelopeId: base64url(randomBytes(12)),
+ roomId,
+ seq: nextSeq(logPath),
+ msgType: 'PeerHello',
+ payload: { roomLabel, trustLevel: 'attested' },
+ timestamp: entry.registeredAt,
+ };
+ appendFileSync(logPath, JSON.stringify(env) + '\n');
+ }
// nodeId: deterministic per (cwd, roomId) so re-registers reuse identity.
const nodeId = createHash('sha256')
@@ -272,6 +356,7 @@ export const agentbbsTools: MCPTool[] = [
roomId,
nodeId,
trustLevel: 'attested' as const,
+ helloEmitted,
};
},
},
@@ -392,13 +477,16 @@ export const agentbbsTools: MCPTool[] = [
const idx = all.findIndex(e => e.envelopeId === sinceEnvelopeId);
slice = idx >= 0 ? all.slice(idx + 1) : all;
}
- const envelopes = slice.slice(-limit);
+ // Dedup by envelopeId before applying the limit β€” a relay replay or a
+ // double-append must not surface the same envelope twice to a watcher.
+ const deduped = dedupEnvelopes(slice);
+ const envelopes = deduped.slice(-limit);
return {
success: true,
roomId,
envelopes,
count: envelopes.length,
- hasMore: slice.length > envelopes.length,
+ hasMore: deduped.length > envelopes.length,
};
},
},