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

fix(helpers): ship session and memory helpers as .cjs too (#3555)

ruvef99017d45fa
diff --git a/.claude/helpers/hook-handler.cjs b/.claude/helpers/hook-handler.cjs
index 8536355063..401b7594ed 100755
--- a/.claude/helpers/hook-handler.cjs
+++ b/.claude/helpers/hook-handler.cjs
@@ -233,8 +233,8 @@ function safeRequire(modulePath) {
}
const router = safeRequire(path.join(helpersDir, 'router.cjs'));
-const session = safeRequire(path.join(helpersDir, 'session.js'));
-const memory = safeRequire(path.join(helpersDir, 'memory.js'));
+const session = safeRequire(path.join(helpersDir, 'session.cjs'));
+const memory = safeRequire(path.join(helpersDir, 'memory.cjs'));
const intelligence = safeRequire(path.join(helpersDir, 'intelligence.cjs'));
// ── Intelligence timeout protection (fixes #1530, #1531) ───────────────────
@@ -603,4 +603,7 @@ if (require.main === module) {
});
}
-module.exports = { runWithTimeout, INTELLIGENCE_TIMEOUT_MS };
+// Which sibling helpers loaded (all CommonJS, shipped as .cjs β€” #3555).
+const loadedHelpers = { router: !!router, session: !!session, memory: !!memory, intelligence: !!intelligence };
+
+module.exports = { runWithTimeout, INTELLIGENCE_TIMEOUT_MS, loadedHelpers };
diff --git a/.claude/helpers/memory.cjs b/.claude/helpers/memory.cjs
index 467fde3f2f..cf0ece3e76 100644
--- a/.claude/helpers/memory.cjs
+++ b/.claude/helpers/memory.cjs
@@ -79,6 +79,6 @@ if (require.main === module) {
if (command && commands[command]) {
commands[command](key, value);
} else {
- console.log('Usage: memory.js <get|set|delete|clear|keys> [key] [value]');
+ console.log('Usage: memory.cjs <get|set|delete|clear|keys> [key] [value]');
}
}
diff --git a/.claude/helpers/session.cjs b/.claude/helpers/session.cjs
index 8c21959d04..ffe53a9b2a 100644
--- a/.claude/helpers/session.cjs
+++ b/.claude/helpers/session.cjs
@@ -118,7 +118,7 @@ if (require.main === module) {
if (command && commands[command]) {
commands[command](...args);
} else {
- console.log('Usage: session.js <start|restore|end|status|metric>');
+ console.log('Usage: session.cjs <start|restore|end|status|metric>');
console.log(`Platform: ${platform}`);
console.log(`Data dir: ${SESSION_DIR}`);
}
diff --git a/v3/@claude-flow/cli/.claude/helpers/helpers.manifest.json b/v3/@claude-flow/cli/.claude/helpers/helpers.manifest.json
index 260d7751f4..db493d98c5 100644
--- a/v3/@claude-flow/cli/.claude/helpers/helpers.manifest.json
+++ b/v3/@claude-flow/cli/.claude/helpers/helpers.manifest.json
@@ -3,12 +3,12 @@
"version": "3.48.0",
"files": {
"auto-memory-hook.mjs": "c8d218526a3c34034c2a69de23f507f0eb0f70d59c16426a8edc849e6ac22529",
- "hook-handler.cjs": "e758881c9aed5bc07ee18c3d98f6a32025fdf62f75f153cd3ec80e284b6e88c3",
+ "hook-handler.cjs": "d4bc05ebb39e259f5e9dfb67f92fc1bde47549e675fab713439e0b3933f9922c",
"intelligence.cjs": "30e42ed7ec4ca5a94ac54fdb1330d2d47ac5f3fdeeef207753574723a9e77b5c",
"statusline.cjs": "4a48353b4f1566fa4379b00fd0321b6676a22b6cc91fbbd8380ac5183d619468",
"router.cjs": "16648b3c0d73b6681ac2d8d13def6a68286c57f5a11004de5b19a0fa088c833d"
}
},
- "signature": "E+bAF8yyhdWgZ63QoW32z0zdJ7Tq5n5sFrXUk6EDLynp+vzckYh3ZLfyQ1DNHTlXHbYQKszWjmHk7SnXoQjZDQ==",
+ "signature": "gNoQsp1czhjhg/eQMB5gFx6JeijDNqyA4aZNHQB4ytADbcA86AGPvcVEIAKf0x3ZTnXdnao7PPmF025/h3fZBA==",
"algorithm": "ed25519"
}
diff --git a/v3/@claude-flow/cli/.claude/helpers/hook-handler.cjs b/v3/@claude-flow/cli/.claude/helpers/hook-handler.cjs
index 8536355063..401b7594ed 100755
--- a/v3/@claude-flow/cli/.claude/helpers/hook-handler.cjs
+++ b/v3/@claude-flow/cli/.claude/helpers/hook-handler.cjs
@@ -233,8 +233,8 @@ function safeRequire(modulePath) {
}
const router = safeRequire(path.join(helpersDir, 'router.cjs'));
-const session = safeRequire(path.join(helpersDir, 'session.js'));
-const memory = safeRequire(path.join(helpersDir, 'memory.js'));
+const session = safeRequire(path.join(helpersDir, 'session.cjs'));
+const memory = safeRequire(path.join(helpersDir, 'memory.cjs'));
const intelligence = safeRequire(path.join(helpersDir, 'intelligence.cjs'));
// ── Intelligence timeout protection (fixes #1530, #1531) ───────────────────
@@ -603,4 +603,7 @@ if (require.main === module) {
});
}
-module.exports = { runWithTimeout, INTELLIGENCE_TIMEOUT_MS };
+// Which sibling helpers loaded (all CommonJS, shipped as .cjs β€” #3555).
+const loadedHelpers = { router: !!router, session: !!session, memory: !!memory, intelligence: !!intelligence };
+
+module.exports = { runWithTimeout, INTELLIGENCE_TIMEOUT_MS, loadedHelpers };
diff --git a/v3/@claude-flow/cli/.claude/helpers/memory.js b/v3/@claude-flow/cli/.claude/helpers/memory.cjs
similarity index 95%
rename from v3/@claude-flow/cli/.claude/helpers/memory.js
rename to v3/@claude-flow/cli/.claude/helpers/memory.cjs
index 7bd7dfbca9..45945fac78 100644
--- a/v3/@claude-flow/cli/.claude/helpers/memory.js
+++ b/v3/@claude-flow/cli/.claude/helpers/memory.cjs
@@ -77,7 +77,7 @@ const value = valueParts.join(' ');
if (command && commands[command]) {
commands[command](key, value);
} else {
- console.log('Usage: memory.js <get|set|delete|clear|keys> [key] [value]');
+ console.log('Usage: memory.cjs <get|set|delete|clear|keys> [key] [value]');
}
module.exports = commands;
diff --git a/v3/@claude-flow/cli/.claude/helpers/session.js b/v3/@claude-flow/cli/.claude/helpers/session.cjs
similarity index 98%
rename from v3/@claude-flow/cli/.claude/helpers/session.js
rename to v3/@claude-flow/cli/.claude/helpers/session.cjs
index 7447533292..2e42c8118b 100644
--- a/v3/@claude-flow/cli/.claude/helpers/session.js
+++ b/v3/@claude-flow/cli/.claude/helpers/session.cjs
@@ -151,7 +151,7 @@ const [,, command, ...args] = process.argv;
if (command && commands[command]) {
commands[command](...args);
} else {
- console.log('Usage: session.js <start|restore|end|status|update|metric> [args]');
+ console.log('Usage: session.cjs <start|restore|end|status|update|metric> [args]');
}
module.exports = commands;
diff --git a/v3/@claude-flow/cli/__tests__/router-cjs-esm-3555.test.ts b/v3/@claude-flow/cli/__tests__/router-cjs-esm-3555.test.ts
index 84c0f7ac93..2a8153ee9c 100644
--- a/v3/@claude-flow/cli/__tests__/router-cjs-esm-3555.test.ts
+++ b/v3/@claude-flow/cli/__tests__/router-cjs-esm-3555.test.ts
@@ -8,13 +8,17 @@
* exactly the projects most new Node code uses.
*/
import { describe, it, expect } from 'vitest';
-import { mkdtempSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, cpSync } from 'node:fs';
import { join, dirname } from 'node:path';
import { tmpdir } from 'node:os';
import { fileURLToPath } from 'node:url';
import { spawnSync } from 'node:child_process';
+import { generateKeyPairSync, sign as edSign } from 'node:crypto';
-import { CRITICAL_HELPERS } from '../src/init/helper-refresh.js';
+import {
+ CRITICAL_HELPERS, HELPERS_STAMP_FILE, autoRefreshHelpersIfStale, getInstalledCliVersion,
+} from '../src/init/helper-refresh.js';
+import { canonicalManifestBytes, sha256Hex } from '../src/init/helper-signing.js';
import { generateHelpers, generateHookHandler } from '../src/init/helpers-generator.js';
const PKG_HELPERS_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', '.claude', 'helpers');
@@ -70,6 +74,75 @@ describe('#3555 β€” router helper loads in "type":"module" projects', () => {
expect(JSON.parse(r.stdout).agent).toBe('reviewer');
});
+ it('the generators emit session.cjs / memory.cjs and a hook-handler that requires them', () => {
+ const helpers = generateHelpers({ components: { helpers: true } } as never);
+ for (const name of ['session', 'memory']) {
+ expect(Object.keys(helpers)).toContain(`${name}.cjs`);
+ expect(Object.keys(helpers)).not.toContain(`${name}.js`);
+ expect(generateHookHandler()).toContain(`path.join(helpersDir, '${name}.cjs')`);
+ }
+ });
+
+ it('a fresh install of the packaged helpers loads every sibling helper in an ESM project', () => {
+ const { cwd, helpersDir } = esmProject();
+ cpSync(PKG_HELPERS_DIR, helpersDir, { recursive: true });
+ const r = node(cwd, [
+ '--input-type=commonjs', '-e',
+ "console.log(JSON.stringify(require('./.claude/helpers/hook-handler.cjs').loadedHelpers))",
+ ]);
+ expect(r.stderr).not.toMatch(/require is not defined/);
+ expect(JSON.parse(r.stdout.trim().split('\n').pop() ?? 'null'))
+ .toEqual({ router: true, session: true, memory: true, intelligence: true });
+ });
+
+ it('hook-handler session-restore / session-end drive the session helper in an ESM project', () => {
+ const { cwd, helpersDir } = esmProject();
+ cpSync(PKG_HELPERS_DIR, helpersDir, { recursive: true });
+ const current = join(cwd, '.claude-flow', 'sessions', 'current.json');
+
+ const restore = node(cwd, ['.claude/helpers/hook-handler.cjs', 'session-restore'], { RUFLO_NO_AUTO_ENABLE: '1' });
+ // The no-helper fallback prints a placeholder and writes nothing.
+ expect(restore.stdout).not.toContain('%SESSION_ID%');
+ expect(existsSync(current)).toBe(true);
+ const id = JSON.parse(readFileSync(current, 'utf-8')).id as string;
+
+ const end = node(cwd, ['.claude/helpers/hook-handler.cjs', 'session-end'], { RUFLO_NO_AUTO_ENABLE: '1' });
+ expect(end.stdout).toContain(`Session ended: ${id}`);
+ expect(existsSync(current)).toBe(false);
+ expect(existsSync(join(cwd, '.claude-flow', 'sessions', `${id}.json`))).toBe(true);
+ });
+
+ it('refreshing a pre-rename install adds the .cjs companions and ignores the stale .js copies', async () => {
+ const cwd = mkdtempSync(join(tmpdir(), 'router-esm-3555-refresh-'));
+ const helpersDir = join(cwd, '.claude', 'helpers');
+ mkdirSync(helpersDir, { recursive: true });
+ writeFileSync(join(helpersDir, 'hook-handler.cjs'), '// old hook-handler\n');
+ writeFileSync(join(helpersDir, 'session.js'), '// stale session.js\n');
+ writeFileSync(join(helpersDir, 'memory.js'), '// stale memory.js\n');
+ writeFileSync(join(helpersDir, HELPERS_STAMP_FILE), '0.0.1-old');
+
+ const sourceDir = mkdtempSync(join(tmpdir(), 'router-esm-3555-source-'));
+ const files: Record<string, string> = {};
+ for (const name of ['hook-handler.cjs', 'router.cjs']) {
+ const content = readFileSync(join(PKG_HELPERS_DIR, name));
+ writeFileSync(join(sourceDir, name), content);
+ files[name] = sha256Hex(content);
+ }
+ const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+ const manifest = { version: getInstalledCliVersion(), files };
+ const signature = edSign(null, canonicalManifestBytes(manifest), privateKey).toString('base64');
+ writeFileSync(join(sourceDir, 'helpers.manifest.json'), JSON.stringify({ manifest, signature, algorithm: 'ed25519' }));
+
+ const res = await autoRefreshHelpersIfStale(cwd, {
+ sourceDirOverride: sourceDir,
+ pubkeyPemOverride: publicKey.export({ type: 'spki', format: 'pem' }).toString(),
+ });
+ expect(res.refreshed).toBe(true);
+ expect(existsSync(join(helpersDir, 'session.cjs'))).toBe(true);
+ expect(existsSync(join(helpersDir, 'memory.cjs'))).toBe(true);
+ expect(readFileSync(join(helpersDir, 'session.js'), 'utf-8')).toBe('// stale session.js\n');
+ });
+
it('the packaged hook-handler routes through router.cjs in an ESM project', () => {
const { cwd, helpersDir } = esmProject();
for (const name of ['hook-handler.cjs', 'router.cjs']) {
diff --git a/v3/@claude-flow/cli/src/init/executor.ts b/v3/@claude-flow/cli/src/init/executor.ts
index a6d6242b34..0c6bd253da 100644
--- a/v3/@claude-flow/cli/src/init/executor.ts
+++ b/v3/@claude-flow/cli/src/init/executor.ts
@@ -31,6 +31,7 @@ import {
import { getInstalledCliVersion, HELPERS_STAMP_FILE } from './helper-refresh.js';
import { generateClaudeMd } from './claudemd-generator.js';
import { recordMemoryPackagePath } from './memory-package-resolver.js';
+import { ensureCommonJsCompanions } from './helper-companions.js';
import { scanSettingsForRisk, formatRiskFindingsAsWarnings } from './settings-risk-scanner.js';
/**
@@ -609,6 +610,12 @@ export async function executeUpgrade(targetDir: string, upgradeSettings = false)
}
}
+ // #3555: the refreshed hook-handler requires the .cjs companions; older
+ // installs only have session.js / memory.js, which can't load in ESM.
+ for (const name of await ensureCommonJsCompanions(path.join(targetDir, '.claude', 'helpers'))) {
+ result.created.push(`.claude/helpers/${name}`);
+ }
+
// Stamp the installed version so the startup auto-refresh treats these as
// current (no redundant re-copy on the next command).
try {
@@ -1416,9 +1423,9 @@ async function writeHelpers(
const helpers: Record<string, string> = {
'pre-commit': generatePreCommitHook(),
'post-commit': generatePostCommitHook(),
- 'session.js': generateSessionManager(),
+ 'session.cjs': generateSessionManager(),
'router.cjs': generateAgentRouter(),
- 'memory.js': generateMemoryHelper(),
+ 'memory.cjs': generateMemoryHelper(),
'hook-handler.cjs': generateHookHandler(),
'intelligence.cjs': generateIntelligenceStub(),
'auto-memory-hook.mjs': generateAutoMemoryHook(),
diff --git a/v3/@claude-flow/cli/src/init/helper-companions.ts b/v3/@claude-flow/cli/src/init/helper-companions.ts
new file mode 100644
index 0000000000..286ac36dd4
--- /dev/null
+++ b/v3/@claude-flow/cli/src/init/helper-companions.ts
@@ -0,0 +1,33 @@
+/**
+ * CommonJS companion helpers that `hook-handler.cjs` requires but that are not
+ * in the signed critical set (#3555).
+ *
+ * They are CommonJS, so they ship as `.cjs`: a `.js` copy cannot load in a
+ * `"type":"module"` project. Installs made before the rename have only the
+ * `.js` copies, which the refreshed hook-handler no longer requires, so the
+ * refresh writes any missing `.cjs` companion from the CLI's own compiled
+ * generators (the trust root; no external file to verify). Stale `.js` copies
+ * are left in place and ignored. Existing `.cjs` files are never overwritten.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+export const COMMONJS_COMPANION_HELPERS = ['session.cjs', 'memory.cjs'] as const;
+
+export async function ensureCommonJsCompanions(helpersDir: string): Promise<string[]> {
+ const missing = COMMONJS_COMPANION_HELPERS.filter((name) => !fs.existsSync(path.join(helpersDir, name)));
+ if (missing.length === 0) return [];
+ const gen = await import('./helpers-generator.js');
+ const content: Record<(typeof COMMONJS_COMPANION_HELPERS)[number], () => string> = {
+ 'session.cjs': gen.generateSessionManager,
+ 'memory.cjs': gen.generateMemoryHelper,
+ };
+ const written: string[] = [];
+ for (const name of missing) {
+ try {
+ fs.writeFileSync(path.join(helpersDir, name), content[name](), { encoding: 'utf-8', mode: 0o755 });
+ written.push(name);
+ } catch { /* best-effort: hook-handler degrades gracefully without it */ }
+ }
+ return written;
+}
diff --git a/v3/@claude-flow/cli/src/init/helper-refresh.ts b/v3/@claude-flow/cli/src/init/helper-refresh.ts
index 8d8a64a45a..a97be7bece 100644
--- a/v3/@claude-flow/cli/src/init/helper-refresh.ts
+++ b/v3/@claude-flow/cli/src/init/helper-refresh.ts
@@ -22,6 +22,7 @@ import * as semver from 'semver';
import {
verifyHelpersManifest, sha256Hex, HELPERS_MANIFEST_FILE, type HelpersManifest,
} from './helper-signing.js';
+import { ensureCommonJsCompanions } from './helper-companions.js';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -391,6 +392,7 @@ async function refreshOneHelpersDirLocked(
pubkeyPemOverride: opts.pubkeyPemOverride,
});
if (res.blocked) return { refreshed: false, blocked: res.blocked };
+ if (res.wrote) await ensureCommonJsCompanions(helpersDir); // #3555
return res.wrote ? { refreshed: true, from: stamped || '(unstamped)', to: version } : { refreshed: false };
}
diff --git a/v3/@claude-flow/cli/src/init/helpers-generator.ts b/v3/@claude-flow/cli/src/init/helpers-generator.ts
index 80077fae81..23f95a8904 100644
--- a/v3/@claude-flow/cli/src/init/helpers-generator.ts
+++ b/v3/@claude-flow/cli/src/init/helpers-generator.ts
@@ -247,7 +247,7 @@ const [,, command, ...args] = process.argv;
if (command && commands[command]) {
commands[command](...args);
} else {
- console.log('Usage: session.js <start|restore|end|status|update|metric> [args]');
+ console.log('Usage: session.cjs <start|restore|end|status|update|metric> [args]');
}
module.exports = commands;
@@ -434,7 +434,7 @@ const value = valueParts.join(' ');
if (command && commands[command]) {
commands[command](key, value);
} else {
- console.log('Usage: memory.js <get|set|delete|clear|keys> [key] [value]');
+ console.log('Usage: memory.cjs <get|set|delete|clear|keys> [key] [value]');
}
module.exports = commands;
@@ -513,8 +513,8 @@ export function generateHookHandler(): string {
'}',
'',
"const router = safeRequire(path.join(helpersDir, 'router.cjs'));",
- "const session = safeRequire(path.join(helpersDir, 'session.js'));",
- "const memory = safeRequire(path.join(helpersDir, 'memory.js'));",
+ "const session = safeRequire(path.join(helpersDir, 'session.cjs'));",
+ "const memory = safeRequire(path.join(helpersDir, 'memory.cjs'));",
"const intelligence = safeRequire(path.join(helpersDir, 'intelligence.cjs'));",
'',
'const [,, command, ...args] = process.argv;',
@@ -1371,7 +1371,7 @@ const [,, command, ...args] = process.argv;
if (command && commands[command]) {
commands[command](...args);
} else {
- console.log('Usage: session.js <start|restore|end|status>');
+ console.log('Usage: session.cjs <start|restore|end|status>');
console.log(\`Platform: \${platform}\`);
console.log(\`Data dir: \${SESSION_DIR}\`);
}
@@ -1392,9 +1392,9 @@ export function generateHelpers(options: InitOptions): Record<string, string> {
helpers['post-commit'] = generatePostCommitHook();
// Cross-platform Node.js scripts
- helpers['session.js'] = generateCrossPlatformSessionManager();
+ helpers['session.cjs'] = generateCrossPlatformSessionManager();
helpers['router.cjs'] = generateAgentRouter();
- helpers['memory.js'] = generateMemoryHelper();
+ helpers['memory.cjs'] = generateMemoryHelper();
// Windows-specific scripts
helpers['daemon-manager.ps1'] = generateWindowsDaemonManager();