π 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
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.cjsindex 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.cjsindex 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.cjsindex 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.jsonindex 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.cjsindex 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.cjssimilarity index 95%rename from v3/@claude-flow/cli/.claude/helpers/memory.jsrename to v3/@claude-flow/cli/.claude/helpers/memory.cjsindex 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.cjssimilarity index 98%rename from v3/@claude-flow/cli/.claude/helpers/session.jsrename to v3/@claude-flow/cli/.claude/helpers/session.cjsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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); // #3555return 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.tsindex 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 scriptshelpers['daemon-manager.ps1'] = generateWindowsDaemonManager();