π 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
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.mjsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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;