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

feat(swarm): inter-agent message compressor — IB+VQ MVP (#2727 dream)

ruv3280cf423eca
diff --git a/v3/@claude-flow/cli/__tests__/message-compressor-2727.test.ts b/v3/@claude-flow/cli/__tests__/message-compressor-2727.test.ts
new file mode 100644
index 0000000000..44c00a74aa
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/message-compressor-2727.test.ts
@@ -0,0 +1,100 @@
+/**
+ * Regression guard for #2727 dream-cycle IB+VQ-inspired message
+ * compressor (v1 MVP — TF-IDF sparsification with must-preserve span
+ * extraction; v2 will land a real VQ codec).
+ *
+ * Compressor must:
+ * 1. Preserve code fences, inline code, URLs, and file paths verbatim.
+ * 2. Reduce size when budgetTokens < original tokens.
+ * 3. Reassemble kept sentences in original order (not score order).
+ * 4. Report accurate stats.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { compressMessage, estimateTokens } from '../src/swarm/message-compressor.js';
+
+const LONG_MESSAGE = [
+ 'The authentication module is currently unstable under high concurrency.',
+ 'When more than 20 concurrent sessions attempt token refresh, the JWT verifier throws.',
+ 'We think this is a race condition in the token cache eviction path.',
+ 'The relevant file is src/auth/jwt-verifier.ts and it uses the JWT library from npm.',
+ 'A code excerpt: ```ts\nconst t = verify(token, PUBLIC_KEY);\n```',
+ 'You can reproduce by running the load test at https://internal.example.com/loadtest/jwt.',
+ 'The problem does not appear with fewer than 10 concurrent sessions.',
+ 'We suspect the LRU cache does not lock on concurrent writes.',
+ 'One workaround is to switch to a mutex-protected cache implementation.',
+ 'The impact is that under peak load, roughly 3% of auth requests fail.',
+ 'Failed requests return a 500 with a generic error message.',
+ 'Users see a login prompt again which resets their session.',
+ 'The failure rate is unacceptable for production traffic.',
+ 'We need to prioritize this fix in the current sprint.',
+ 'The estimated engineering time is two person-days.',
+].join(' ');
+
+describe('#2727 message compressor', () => {
+ it('preserves a code fence verbatim in the output', () => {
+ const r = compressMessage(LONG_MESSAGE, { budgetTokens: 100 });
+ expect(r.compressed).toContain('```ts');
+ expect(r.compressed).toContain('verify(token, PUBLIC_KEY)');
+ expect(r.stats.preservedSpans).toBeGreaterThan(0);
+ });
+
+ it('preserves URLs verbatim', () => {
+ const r = compressMessage(LONG_MESSAGE, { budgetTokens: 100 });
+ expect(r.compressed).toContain('https://internal.example.com/loadtest/jwt');
+ });
+
+ it('preserves file paths verbatim', () => {
+ const r = compressMessage(LONG_MESSAGE, { budgetTokens: 100 });
+ expect(r.compressed).toContain('src/auth/jwt-verifier.ts');
+ });
+
+ it('reduces token count when budget is < original', () => {
+ const r = compressMessage(LONG_MESSAGE, { budgetTokens: 80 });
+ expect(r.stats.compressedTokens).toBeLessThan(r.stats.originalTokens);
+ expect(r.stats.compressionRatio).toBeLessThan(1);
+ });
+
+ it('reports accurate sentence counts', () => {
+ const r = compressMessage(LONG_MESSAGE, { budgetTokens: 60 });
+ expect(r.stats.sentencesTotal).toBeGreaterThan(5);
+ expect(r.stats.sentencesKept).toBeGreaterThan(0);
+ expect(r.stats.sentencesKept).toBeLessThanOrEqual(r.stats.sentencesTotal);
+ });
+
+ it('reassembles kept sentences in original order (not score order)', () => {
+ const src = [
+ 'A quick short intro.',
+ 'This is the load-bearing middle sentence that mentions authentication and JWT and race.',
+ 'A trailing note.',
+ ].join(' ');
+ const r = compressMessage(src, { budgetTokens: 40 });
+ // If kept, "quick short intro" must appear before "trailing note" (order preserved).
+ if (r.compressed.includes('quick short intro') && r.compressed.includes('trailing note')) {
+ const introIdx = r.compressed.indexOf('quick short intro');
+ const trailIdx = r.compressed.indexOf('trailing note');
+ expect(introIdx).toBeLessThan(trailIdx);
+ }
+ });
+
+ it('is a no-op when budget already exceeds original size', () => {
+ const short = 'Just a short handoff message with no compression needed.';
+ const r = compressMessage(short, { budgetTokens: 1000 });
+ expect(r.compressed).toContain('short handoff message');
+ expect(r.stats.compressionRatio).toBeGreaterThanOrEqual(0.9);
+ });
+
+ it('estimateTokens matches the ~4-chars-per-token rule', () => {
+ expect(estimateTokens('')).toBe(0);
+ expect(estimateTokens('abcd')).toBe(1);
+ expect(estimateTokens('abcdefgh')).toBe(2);
+ });
+
+ it('honors mode=keyword vs mode=sentence (may produce different outputs)', () => {
+ const rk = compressMessage(LONG_MESSAGE, { budgetTokens: 60, mode: 'keyword' });
+ const rs = compressMessage(LONG_MESSAGE, { budgetTokens: 60, mode: 'sentence' });
+ // Both should be under the original size (main invariant).
+ expect(rk.stats.compressionRatio).toBeLessThan(1);
+ expect(rs.stats.compressionRatio).toBeLessThan(1);
+ });
+});
diff --git a/v3/@claude-flow/cli/src/commands/swarm.ts b/v3/@claude-flow/cli/src/commands/swarm.ts
index 8b8a370a3b..f44a972c1f 100644
--- a/v3/@claude-flow/cli/src/commands/swarm.ts
+++ b/v3/@claude-flow/cli/src/commands/swarm.ts
@@ -896,10 +896,76 @@ const coordinateCommand: Command = {
};
// Main swarm command
+// #2727 dream-cycle — inter-agent message compressor (IB+VQ-inspired
+// MVP). Advisory tool: takes a message + token budget, returns a
+// compressed variant that preserves must-see spans (code, URLs, paths)
+// and keeps the top-scored sentences by TF-IDF-ish keyword density.
+// v2 wires a real VQ codec once a training pipeline exists.
+const compressMessageCommand: Command = {
+ name: 'compress-message',
+ description: 'Compress an inter-agent message to a token budget (IB+VQ-inspired, dream-cycle #2727)',
+ options: [
+ { name: 'message', short: 'm', type: 'string', description: 'Message text (or use --message-file)' },
+ { name: 'message-file', type: 'string', description: 'Path to a file whose contents will be compressed' },
+ { name: 'budget-tokens', short: 'b', type: 'number', default: 200, description: 'Target token budget (approximate, ~4 chars per token)' },
+ { name: 'mode', type: 'string', choices: ['keyword', 'sentence', 'hybrid'], default: 'hybrid', description: 'Scoring mode' },
+ ],
+ examples: [
+ { command: 'claude-flow swarm compress-message -m "…" --budget-tokens 100', description: 'Compress inline message to 100 tokens' },
+ { command: 'claude-flow swarm compress-message --message-file ./msg.md -b 300 --format json', description: 'JSON for pipelines' },
+ ],
+ action: async (ctx: CommandContext): Promise<CommandResult> => {
+ const inlineMsg = ctx.flags.message as string | undefined;
+ const msgFile = ctx.flags.messageFile as string | undefined;
+ const budgetTokens = (ctx.flags.budgetTokens as number) || 200;
+ const mode = (ctx.flags.mode as string) || 'hybrid';
+
+ let message = inlineMsg ?? '';
+ if (msgFile) {
+ try {
+ const fsMod = await import('node:fs');
+ const pathMod = await import('node:path');
+ message = fsMod.readFileSync(pathMod.resolve(msgFile), 'utf-8');
+ } catch (err) {
+ output.printError(`Failed to read ${msgFile}: ${err instanceof Error ? err.message : String(err)}`);
+ return { success: false, exitCode: 1 };
+ }
+ }
+
+ if (!message) {
+ output.printError('No message provided. Use --message "..." or --message-file <path>.');
+ return { success: false, exitCode: 1 };
+ }
+
+ const { compressMessage } = await import('../swarm/message-compressor.js');
+ const result = compressMessage(message, { budgetTokens, mode: mode as 'keyword' | 'sentence' | 'hybrid' });
+
+ if (ctx.flags.format === 'json') {
+ output.printJson(result);
+ return { success: true, data: result };
+ }
+
+ output.writeln();
+ output.printBox(
+ `Original: ${result.stats.originalTokens} tokens · Compressed: ${result.stats.compressedTokens} tokens\n` +
+ `Ratio: ${(result.stats.compressionRatio * 100).toFixed(1)}%\n` +
+ `Sentences kept: ${result.stats.sentencesKept}/${result.stats.sentencesTotal} · Preserved spans: ${result.stats.preservedSpans}\n` +
+ `Info retained (top-quartile): ${(result.stats.infoRetainedEstimate * 100).toFixed(1)}%`,
+ 'Message Compressor (#2727 IB+VQ MVP)'
+ );
+ output.writeln();
+ output.writeln(output.bold('Compressed message'));
+ output.writeln(output.dim('─'.repeat(60)));
+ output.writeln(result.compressed);
+ output.writeln(output.dim('─'.repeat(60)));
+ return { success: true, data: result };
+ },
+};
+
export const swarmCommand: Command = {
name: 'swarm',
description: 'Swarm coordination commands',
- subcommands: [initCommand, startCommand, statusCommand, stopCommand, scaleCommand, coordinateCommand],
+ subcommands: [initCommand, startCommand, statusCommand, stopCommand, scaleCommand, coordinateCommand, compressMessageCommand],
options: [],
examples: [
{ command: 'claude-flow swarm init --v3-mode', description: 'Initialize V3 swarm' },
diff --git a/v3/@claude-flow/cli/src/swarm/message-compressor.ts b/v3/@claude-flow/cli/src/swarm/message-compressor.ts
new file mode 100644
index 0000000000..ee77488cc0
Binary files /dev/null and b/v3/@claude-flow/cli/src/swarm/message-compressor.ts differ