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(sona): default the learning mode from RUFLO_INTELLIGENCE_MODE (#3334)

rUv90889f477223
diff --git a/scripts/audit-env-var-precedence.mjs b/scripts/audit-env-var-precedence.mjs
index de385569c3..dd3ebf3787 100644
--- a/scripts/audit-env-var-precedence.mjs
+++ b/scripts/audit-env-var-precedence.mjs
@@ -99,6 +99,13 @@ const KNOWN_ESCAPE_HATCHES = new Set([
'CLAUDE_FLOW_MCP_COMPOSITION_BLOCK', // Opt-in strict mode for the Composition Inspector (evaluateToolComposition) β€” default warn+log, '1'/'true' switches a flagged tool chain to blocked. Deploy/CI ops posture toggle read fresh per scan, not a per-invocation CLI flag; no interactive CLI command owns a single MCP tool-composition scan's lifetime.
'CLAUDE_FLOW_SECURITY_CHANNEL_GATE', // Kill switch for the ChannelGuard inter-agent message sanitization gate (guardChannelMessage, wired into SwarmCommunication.sendMessage) β€” default enabled, '0' disables for trusted internal environments. Same escape-hatch shape as CLAUDE_FLOW_DISABLE_BRIDGE above; the gate runs inside the swarm-communication hot path, not behind a user-typed command.
+ // ── SONA fleet-wide learning-mode default (feat/sona-mode-from-env) ─────────
+ // Read inside @claude-flow/integration/src/sona-adapter.ts (sonaModeFromEnv,
+ // exported) and @claude-flow/memory/src/learning-bridge.ts (sonaModeFromEnv,
+ // module-private) β€” both outside this audit's SCAN_ROOTS today, registered
+ // anyway per the same requirement as CLAUDE_FLOW_MCP_COMPOSITION_BLOCK above.
+ 'RUFLO_INTELLIGENCE_MODE', // Fleet-wide default SONA learning mode ('real-time'|'balanced'|'research'|'edge'|'batch') for a managed deployment that wants every session to learn in a given profile without threading `mode`/`sonaMode` through every call site. Read fresh per SONAAdapter construction / mergeConfig() call and per LearningBridge construction β€” never cached at module load. An explicit per-call mode/sonaMode always wins; an unset or unrecognised value falls through to the caller's own default ('balanced'), never silently selecting a profile. Deploy/ops config, not a per-invocation CLI flag.
+
// ── Feature flags (set by init into settings.json, not user-typed CLI) ──────
'CLAUDE_FLOW_V3_ENABLED',
'CLAUDE_FLOW_HOOKS_ENABLED',
diff --git a/v3/@claude-flow/integration/src/__tests__/sona-adapter.test.ts b/v3/@claude-flow/integration/src/__tests__/sona-adapter.test.ts
new file mode 100644
index 0000000000..f08de68cc1
--- /dev/null
+++ b/v3/@claude-flow/integration/src/__tests__/sona-adapter.test.ts
@@ -0,0 +1,93 @@
+/**
+ * SONAAdapter Test Suite
+ *
+ * Covers sonaModeFromEnv() / RUFLO_INTELLIGENCE_MODE precedence and timing,
+ * since this module previously had no dedicated test coverage.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { SONAAdapter, sonaModeFromEnv } from '../sona-adapter.js';
+
+const ENV_KEY = 'RUFLO_INTELLIGENCE_MODE';
+
+describe('sonaModeFromEnv', () => {
+ let originalEnv: string | undefined;
+
+ beforeEach(() => {
+ originalEnv = process.env[ENV_KEY];
+ });
+
+ afterEach(() => {
+ if (originalEnv === undefined) delete process.env[ENV_KEY];
+ else process.env[ENV_KEY] = originalEnv;
+ });
+
+ it('returns undefined when unset', () => {
+ delete process.env[ENV_KEY];
+ expect(sonaModeFromEnv()).toBeUndefined();
+ });
+
+ it('returns the mode for a recognised value', () => {
+ process.env[ENV_KEY] = 'research';
+ expect(sonaModeFromEnv()).toBe('research');
+ });
+
+ it('trims whitespace around the value', () => {
+ process.env[ENV_KEY] = ' edge ';
+ expect(sonaModeFromEnv()).toBe('edge');
+ });
+
+ it('returns undefined for an unrecognised value (never silently picks a mode)', () => {
+ process.env[ENV_KEY] = 'not-a-real-mode';
+ expect(sonaModeFromEnv()).toBeUndefined();
+ });
+
+ it('is re-read fresh on every call, not cached at module load', () => {
+ delete process.env[ENV_KEY];
+ expect(sonaModeFromEnv()).toBeUndefined();
+
+ process.env[ENV_KEY] = 'batch';
+ expect(sonaModeFromEnv()).toBe('batch');
+ });
+});
+
+describe('SONAAdapter mode resolution', () => {
+ let originalEnv: string | undefined;
+
+ beforeEach(() => {
+ originalEnv = process.env[ENV_KEY];
+ });
+
+ afterEach(() => {
+ if (originalEnv === undefined) delete process.env[ENV_KEY];
+ else process.env[ENV_KEY] = originalEnv;
+ });
+
+ it('falls back to balanced when RUFLO_INTELLIGENCE_MODE is unset', () => {
+ delete process.env[ENV_KEY];
+ const adapter = new SONAAdapter();
+ expect(adapter.getMode()).toBe('balanced');
+ });
+
+ it('picks up RUFLO_INTELLIGENCE_MODE when no explicit mode is passed', () => {
+ process.env[ENV_KEY] = 'research';
+ const adapter = new SONAAdapter();
+ expect(adapter.getMode()).toBe('research');
+ });
+
+ it('an explicit config.mode wins over RUFLO_INTELLIGENCE_MODE', () => {
+ process.env[ENV_KEY] = 'research';
+ const adapter = new SONAAdapter({ mode: 'edge' });
+ expect(adapter.getMode()).toBe('edge');
+ });
+
+ it('reads RUFLO_INTELLIGENCE_MODE freshly on each construction', () => {
+ delete process.env[ENV_KEY];
+ const before = new SONAAdapter();
+ expect(before.getMode()).toBe('balanced');
+
+ process.env[ENV_KEY] = 'edge';
+ const after = new SONAAdapter();
+ expect(after.getMode()).toBe('edge');
+ });
+});
diff --git a/v3/@claude-flow/integration/src/sona-adapter.ts b/v3/@claude-flow/integration/src/sona-adapter.ts
index f176bdda9b..cdfc3ea956 100644
--- a/v3/@claude-flow/integration/src/sona-adapter.ts
+++ b/v3/@claude-flow/integration/src/sona-adapter.ts
@@ -95,6 +95,21 @@ const MODE_CONFIGS: Record<SONALearningMode, Partial<SONAConfiguration>> = {
},
};
+/**
+ * The default SONA learning mode from the environment, if the operator set one.
+ *
+ * A deployment (e.g. a managed desktop fleet) may want every session to learn in
+ * a specific profile β€” `research` for +55% quality, `edge` for constrained hosts β€”
+ * without threading `mode` through every call site. `RUFLO_INTELLIGENCE_MODE`
+ * sets that fleet-wide default. An unset or unrecognised value returns undefined,
+ * so the caller falls through to its own default: a typo can never silently pick
+ * a profile nobody asked for.
+ */
+export function sonaModeFromEnv(): SONALearningMode | undefined {
+ const raw = process.env.RUFLO_INTELLIGENCE_MODE?.trim();
+ return raw && raw in MODE_CONFIGS ? (raw as SONALearningMode) : undefined;
+}
+
/**
* SONAAdapter - SONA Learning System Integration
*
@@ -615,7 +630,7 @@ export class SONAAdapter extends EventEmitter {
private mergeConfig(config: Partial<SONAConfiguration>): SONAConfiguration {
return {
- mode: config.mode || 'balanced',
+ mode: config.mode || sonaModeFromEnv() || 'balanced',
learningRate: config.learningRate ?? 0.001,
similarityThreshold: config.similarityThreshold ?? 0.7,
maxPatterns: config.maxPatterns ?? 10000,
diff --git a/v3/@claude-flow/memory/src/learning-bridge.test.ts b/v3/@claude-flow/memory/src/learning-bridge.test.ts
index 8a569cb7a9..e555f56627 100644
--- a/v3/@claude-flow/memory/src/learning-bridge.test.ts
+++ b/v3/@claude-flow/memory/src/learning-bridge.test.ts
@@ -160,6 +160,7 @@ describe('LearningBridge', () => {
consolidationThreshold: 20,
});
expect(custom.getStats().totalTrajectories).toBe(0);
+ expect(custom.getSonaMode()).toBe('research');
custom.destroy();
});
@@ -174,6 +175,64 @@ describe('LearningBridge', () => {
});
});
+ // ===== sonaMode resolution (RUFLO_INTELLIGENCE_MODE) =====
+
+ describe('sonaMode resolution', () => {
+ const ENV_KEY = 'RUFLO_INTELLIGENCE_MODE';
+ let originalEnv: string | undefined;
+
+ beforeEach(() => {
+ originalEnv = process.env[ENV_KEY];
+ });
+
+ afterEach(() => {
+ if (originalEnv === undefined) delete process.env[ENV_KEY];
+ else process.env[ENV_KEY] = originalEnv;
+ });
+
+ it('falls back to balanced when RUFLO_INTELLIGENCE_MODE is unset', () => {
+ delete process.env[ENV_KEY];
+ const b = new LearningBridge(backend);
+ expect(b.getSonaMode()).toBe('balanced');
+ b.destroy();
+ });
+
+ it('reads RUFLO_INTELLIGENCE_MODE set before construction', () => {
+ process.env[ENV_KEY] = 'research';
+ const b = new LearningBridge(backend);
+ expect(b.getSonaMode()).toBe('research');
+ b.destroy();
+ });
+
+ it('reads RUFLO_INTELLIGENCE_MODE freshly on each construction, not just at module load', () => {
+ // Regression test: the env var must be re-read per-instance, not captured
+ // once into a module-scope default the first time this file is imported.
+ delete process.env[ENV_KEY];
+ const before = new LearningBridge(backend);
+ expect(before.getSonaMode()).toBe('balanced');
+ before.destroy();
+
+ process.env[ENV_KEY] = 'research';
+ const after = new LearningBridge(backend);
+ expect(after.getSonaMode()).toBe('research');
+ after.destroy();
+ });
+
+ it('ignores an unrecognised RUFLO_INTELLIGENCE_MODE value', () => {
+ process.env[ENV_KEY] = 'not-a-real-mode';
+ const b = new LearningBridge(backend);
+ expect(b.getSonaMode()).toBe('balanced');
+ b.destroy();
+ });
+
+ it('an explicit config.sonaMode wins over RUFLO_INTELLIGENCE_MODE', () => {
+ process.env[ENV_KEY] = 'research';
+ const b = new LearningBridge(backend, { sonaMode: 'edge' });
+ expect(b.getSonaMode()).toBe('edge');
+ b.destroy();
+ });
+ });
+
// ===== onInsightRecorded =====
describe('onInsightRecorded', () => {
diff --git a/v3/@claude-flow/memory/src/learning-bridge.ts b/v3/@claude-flow/memory/src/learning-bridge.ts
index bd2eaf2121..f7d01a3c34 100644
--- a/v3/@claude-flow/memory/src/learning-bridge.ts
+++ b/v3/@claude-flow/memory/src/learning-bridge.ts
@@ -90,6 +90,25 @@ type ResolvedConfig = Required<Omit<LearningBridgeConfig, 'neuralLoader'>> & {
neuralLoader?: NeuralLoader;
};
+const VALID_SONA_MODES: readonly SONAMode[] = [
+ 'real-time',
+ 'balanced',
+ 'research',
+ 'edge',
+ 'batch',
+];
+
+/**
+ * The SONA mode from `RUFLO_INTELLIGENCE_MODE`, if the operator set a recognised
+ * one β€” the fleet-wide default (e.g. `research` for higher accuracy) without a
+ * per-call `sonaMode`. An unset or unknown value returns undefined so the caller
+ * keeps its own default; a typo never silently selects a profile.
+ */
+function sonaModeFromEnv(): SONAMode | undefined {
+ const raw = (process.env.RUFLO_INTELLIGENCE_MODE?.trim() ?? '') as SONAMode;
+ return VALID_SONA_MODES.includes(raw) ? raw : undefined;
+}
+
const DEFAULT_CONFIG: ResolvedConfig = {
sonaMode: 'balanced',
confidenceDecayRate: 0.005,
@@ -136,7 +155,17 @@ export class LearningBridge extends EventEmitter {
constructor(backend: IMemoryBackend, config?: LearningBridgeConfig) {
super();
this.backend = backend;
- this.config = { ...DEFAULT_CONFIG, ...config };
+ // sonaMode is resolved here, not baked into the module-scope DEFAULT_CONFIG
+ // above: DEFAULT_CONFIG is evaluated once, the first time this module is
+ // imported, so capturing sonaModeFromEnv() there would permanently miss any
+ // RUFLO_INTELLIGENCE_MODE set afterward in the same process (tests included).
+ // Resolving it per-instance keeps this in step with sona-adapter.ts's
+ // mergeConfig(), which reads the same env var fresh on every call.
+ this.config = {
+ ...DEFAULT_CONFIG,
+ ...config,
+ sonaMode: config?.sonaMode ?? sonaModeFromEnv() ?? DEFAULT_CONFIG.sonaMode,
+ };
}
// ===== Public API =====
@@ -363,6 +392,11 @@ export class LearningBridge extends EventEmitter {
};
}
+ /** Return the resolved SONA mode (explicit config > RUFLO_INTELLIGENCE_MODE > default) */
+ getSonaMode(): SONAMode {
+ return this.config.sonaMode;
+ }
+
/** Tear down the bridge. Subsequent method calls become no-ops. */
destroy(): void {
this.destroyed = true;