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(memory,cli): keep the CLI's better-sqlite3 handles on AgentDB's copy

Dragan Spiridonovd4458abdffbe
diff --git a/v3/@claude-flow/cli/__tests__/graph-writer-shared-sqlite-3693.test.ts b/v3/@claude-flow/cli/__tests__/graph-writer-shared-sqlite-3693.test.ts
index 2a18a1de09..77a082d4b4 100644
--- a/v3/@claude-flow/cli/__tests__/graph-writer-shared-sqlite-3693.test.ts
+++ b/v3/@claude-flow/cli/__tests__/graph-writer-shared-sqlite-3693.test.ts
@@ -141,6 +141,38 @@ describe('#3693 graph writer idle close vs live AgentDB handle', () => {
expect(resolveAgentdbBetterSqlite3(agentdbEntry)).toBe(HolderCtor);
});
+ // @claude-flow/memory >= 3.0.3 opens AgentDB's handle with ITS better-sqlite3
+ // (agentdb-native-driver.js), so that copy is the holder the CLI must share.
+ it('owner is @claude-flow/memory when it routes AgentDB through its own driver', async () => {
+ if (!native) return;
+ const memDist = join(root, 'node_modules', '@claude-flow', 'memory', 'dist');
+ const memNm = join(root, 'node_modules', '@claude-flow', 'memory', 'node_modules');
+ mkdirSync(memDist, { recursive: true });
+ mkdirSync(memNm, { recursive: true });
+ writeFileSync(join(memDist, 'index.js'), '');
+ writeFileSync(join(memDist, 'agentdb-native-driver.js'), '');
+ cpSync(dirname(req.resolve('better-sqlite3/package.json')), join(memNm, 'better-sqlite3'), { recursive: true });
+ for (const dep of ['bindings', 'file-uri-to-path']) {
+ try { symlinkSync(dirname(req.resolve(`${dep}/package.json`)), join(memNm, dep)); } catch { /* optional */ }
+ }
+ const memEntry = join(memDist, 'index.js');
+ const MemoryCtor = createRequire(memEntry)('better-sqlite3');
+ const { resolveSqliteOwnerEntry, resolveAgentdbBetterSqlite3 } = await import('../src/memory/shared-sqlite.js');
+
+ expect(resolveSqliteOwnerEntry(memEntry)).toBe(memEntry);
+ expect(resolveAgentdbBetterSqlite3(memEntry)).toBe(MemoryCtor);
+ expect(MemoryCtor).not.toBe(HolderCtor);
+ });
+
+ it('owner falls back to agentdb when @claude-flow/memory has no driver (memory <= 3.0.2)', async () => {
+ const oldMemDist = join(root, 'old-memory', 'dist');
+ mkdirSync(oldMemDist, { recursive: true });
+ writeFileSync(join(oldMemDist, 'index.js'), '');
+ const { resolveSqliteOwnerEntry } = await import('../src/memory/shared-sqlite.js');
+
+ expect(resolveSqliteOwnerEntry(join(oldMemDist, 'index.js'))).toBe(req.resolve('agentdb'));
+ });
+
it("control: a different native copy DOES strip the live holder's sidecars (the hazard)", async () => {
if (!native) return;
const r = await scenario(false);
diff --git a/v3/@claude-flow/cli/__tests__/shared-sqlite-host-driver.test.ts b/v3/@claude-flow/cli/__tests__/shared-sqlite-host-driver.test.ts
new file mode 100644
index 0000000000..93ba7e6c32
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/shared-sqlite-host-driver.test.ts
@@ -0,0 +1,36 @@
+/**
+ * #3693/#3883 single-copy invariant after @claude-flow/memory started opening
+ * AgentDB with its own better-sqlite3 (Node 24 Statement-GC abort): the CLI's
+ * shared loader must hand out the exact constructor AgentDB's handle uses.
+ */
+import { describe, expect, it } from 'vitest';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+
+const req = createRequire(import.meta.url);
+// This package's vitest config externalizes both; import the resolved files natively.
+const importInstalled = (name: string): Promise<any> => import(pathToFileURL(req.resolve(name)).href);
+
+describe('shared-sqlite follows @claude-flow/memory getHostSqliteDriver()', () => {
+ it('resolves the owner to the installed @claude-flow/memory', async () => {
+ const { resolveSqliteOwnerEntry } = await import('../src/memory/shared-sqlite.js');
+
+ expect(resolveSqliteOwnerEntry()).toBe(req.resolve('@claude-flow/memory'));
+ });
+
+ it("loadBetterSqlite3() is the constructor of AgentDB's handle", async () => {
+ const memory = await importInstalled('@claude-flow/memory');
+ const { AgentDB } = await importInstalled('agentdb');
+ const { loadBetterSqlite3 } = await import('../src/memory/shared-sqlite.js');
+ const agentdb = new AgentDB({ dbPath: ':memory:' });
+
+ expect(memory.useHostSqliteDriver(agentdb)).toBe(true);
+ const handle = await agentdb.initializeDatabase(':memory:');
+ try {
+ expect(await loadBetterSqlite3()).toBe(memory.getHostSqliteDriver());
+ expect(handle.constructor).toBe(await loadBetterSqlite3());
+ } finally {
+ handle.close();
+ }
+ });
+});
diff --git a/v3/@claude-flow/cli/src/memory/shared-sqlite.ts b/v3/@claude-flow/cli/src/memory/shared-sqlite.ts
index 08f9a9b1c0..9a56bee649 100644
--- a/v3/@claude-flow/cli/src/memory/shared-sqlite.ts
+++ b/v3/@claude-flow/cli/src/memory/shared-sqlite.ts
@@ -10,25 +10,51 @@
* like "last connection" to that copy and deletes the -wal/-shm sidecars out
* from under AgentDB's still-open handle.
*
- * Resolve the constructor from the same place AgentDB resolves it, so both
- * share one SQLite instance (and its connection bookkeeping). Falls back to the
- * CLI's own copy when agentdb cannot be resolved.
+ * Resolve the constructor from the same place AgentDB's handle is opened with,
+ * so both share one SQLite instance (and its connection bookkeeping):
+ * - @claude-flow/memory >= 3.0.3 opens AgentDB with its own better-sqlite3
+ * (agentdb-native-driver.js, getHostSqliteDriver) to keep agentdb's nested
+ * 11.x — compiled from source on Node 24, which aborts in Statement GC —
+ * out of the process. Resolve from memory's location then.
+ * - Older memory lets AgentDB load its own copy: resolve from agentdb.
+ * Falls back to the CLI's own copy when neither can be resolved.
*/
import { createRequire } from 'node:module';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
type DbCtor = new (path: string, opts?: Record<string, unknown>) => any;
let cached: DbCtor | null | undefined;
+/**
+ * Entry file whose better-sqlite3 AgentDB's handle uses: @claude-flow/memory
+ * when it routes AgentDB through its own driver, else agentdb.
+ * Test seam: `memoryEntry` stands in for the resolved @claude-flow/memory entry.
+ */
+export function resolveSqliteOwnerEntry(memoryEntry?: string): string | null {
+ const own = createRequire(import.meta.url);
+ try {
+ const entry = memoryEntry ?? own.resolve('@claude-flow/memory');
+ if (existsSync(join(dirname(entry), 'agentdb-native-driver.js'))) return entry;
+ } catch { /* memory not installed */ }
+ try {
+ return own.resolve('agentdb');
+ } catch {
+ return null;
+ }
+}
+
/** Test seam: pass `from` to resolve relative to another entry file. */
export function resolveAgentdbBetterSqlite3(from?: string): DbCtor | null {
if (!from && cached !== undefined) return cached;
let found: DbCtor | null = null;
try {
- const own = createRequire(import.meta.url);
- const agentdbEntry = from ?? own.resolve('agentdb');
- const mod = createRequire(agentdbEntry)('better-sqlite3');
- found = (mod?.default ?? mod) as DbCtor;
+ const ownerEntry = from ?? resolveSqliteOwnerEntry();
+ if (ownerEntry) {
+ const mod = createRequire(ownerEntry)('better-sqlite3');
+ found = (mod?.default ?? mod) as DbCtor;
+ }
} catch {
found = null;
}
diff --git a/v3/@claude-flow/memory/src/agentdb-native-driver.test.ts b/v3/@claude-flow/memory/src/agentdb-native-driver.test.ts
index a50818e8e1..845975d316 100644
--- a/v3/@claude-flow/memory/src/agentdb-native-driver.test.ts
+++ b/v3/@claude-flow/memory/src/agentdb-native-driver.test.ts
@@ -6,12 +6,13 @@
* package's better-sqlite3, so the source-built 11.x addon is never loaded.
*/
-import { describe, it, expect } from 'vitest';
-import { mkdtempSync, rmSync } from 'node:fs';
+import { afterAll, afterEach, describe, it, expect, vi } from 'vitest';
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
import Database from 'better-sqlite3';
-import { useHostSqliteDriver } from './agentdb-native-driver.js';
+import { getHostSqliteDriver, useHostSqliteDriver } from './agentdb-native-driver.js';
function fakeAgentDB(config: { forceWasm?: boolean } = {}) {
const calls: string[] = [];
@@ -66,9 +67,14 @@ describe('useHostSqliteDriver', () => {
expect(calls).toEqual([':memory:']);
});
- it('ignores objects without initializeDatabase', () => {
- expect(() => useHostSqliteDriver(null)).not.toThrow();
- expect(() => useHostSqliteDriver({})).not.toThrow();
+ it('reports objects without initializeDatabase instead of throwing', () => {
+ expect(useHostSqliteDriver(null)).toBe(false);
+ expect(useHostSqliteDriver({})).toBe(false);
+ expect(useHostSqliteDriver(fakeAgentDB().agentdb)).toBe(true);
+ });
+
+ it('getHostSqliteDriver is the better-sqlite3 this package resolves', () => {
+ expect(getHostSqliteDriver()).toBe(Database);
});
it('hands the real AgentDB.initialize() a working handle', async () => {
@@ -88,3 +94,133 @@ describe('useHostSqliteDriver', () => {
(opened as Database.Database | undefined)?.close();
}, 60_000);
});
+
+/**
+ * A nested agentdb copy of better-sqlite3 — the installed layout that aborts on
+ * Node 24. pnpm dedupes the workspace onto one copy, so build a second native
+ * copy under a temp `node_modules/agentdb`, like graph-writer-shared-sqlite-3693.
+ */
+describe('useHostSqliteDriver with a nested agentdb copy', () => {
+ const req = createRequire(import.meta.url);
+ const root = mkdtempSync(join(tmpdir(), 'cf-agentdb-nested-'));
+ const agentdbDir = join(root, 'node_modules', 'agentdb');
+ let NestedCtor: any;
+ let FakeAgentDB: any;
+ try {
+ const nm = join(agentdbDir, 'node_modules');
+ mkdirSync(nm, { recursive: true });
+ cpSync(dirname(req.resolve('better-sqlite3/package.json')), join(nm, 'better-sqlite3'), { recursive: true });
+ for (const dep of ['bindings', 'file-uri-to-path']) {
+ try { symlinkSync(dirname(req.resolve(`${dep}/package.json`)), join(nm, dep)); } catch { /* optional */ }
+ }
+ // Same shape as AgentDB.initializeDatabase(): load better-sqlite3 from agentdb's own location.
+ writeFileSync(join(agentdbDir, 'index.cjs'), `
+ class AgentDB {
+ constructor(config = {}) { this.config = config; this.usingWasm = true; }
+ async initializeDatabase(dbPath) {
+ const Database = require('better-sqlite3');
+ const db = new Database(dbPath);
+ db.pragma('journal_mode = WAL');
+ this.usingWasm = false;
+ return db;
+ }
+ async initialize() { this.db = await this.initializeDatabase(this.config.dbPath || ':memory:'); }
+ get database() { return this.db; }
+ }
+ module.exports = { AgentDB, NestedDatabase: require('better-sqlite3') };
+ `);
+ ({ AgentDB: FakeAgentDB, NestedDatabase: NestedCtor } = createRequire(join(agentdbDir, 'index.cjs'))('./index.cjs'));
+ } catch { NestedCtor = null; }
+
+ afterAll(() => { rmSync(root, { recursive: true, force: true }); });
+
+ it.skipIf(!NestedCtor)('control: without the helper AgentDB opens its handle with the nested copy', async () => {
+ expect(NestedCtor).not.toBe(Database);
+ const agentdb = new FakeAgentDB({ dbPath: ':memory:' });
+ await agentdb.initialize();
+
+ expect(agentdb.database).toBeInstanceOf(NestedCtor);
+ agentdb.database.close();
+ });
+
+ it.skipIf(!NestedCtor)('with the helper the handle comes from getHostSqliteDriver(), not the nested copy', async () => {
+ const agentdb = new FakeAgentDB({ dbPath: ':memory:' });
+ useHostSqliteDriver(agentdb);
+ await agentdb.initialize();
+
+ expect(agentdb.database).toBeInstanceOf(getHostSqliteDriver());
+ expect(agentdb.database).not.toBeInstanceOf(NestedCtor);
+ agentdb.database.close();
+ });
+});
+
+/** Fake agentdb module whose AgentDB records the handle its initialize() opened. */
+function agentdbModuleRecordingHandle() {
+ const opened: unknown[] = [];
+ class AgentDB {
+ config: Record<string, unknown>;
+ usingWasm = true;
+ database: unknown = null;
+ constructor(config: Record<string, unknown> = {}) { this.config = config; }
+ async initializeDatabase(_dbPath: string): Promise<unknown> { return { agentdbOwnLoader: true }; }
+ async initialize() {
+ this.database = await this.initializeDatabase((this.config.dbPath as string) || ':memory:');
+ opened.push(this.database);
+ }
+ }
+ return { opened, module: { AgentDB, default: AgentDB } };
+}
+
+describe('AgentDB construction sites apply useHostSqliteDriver', () => {
+ afterEach(() => {
+ vi.doUnmock('agentdb');
+ vi.resetModules();
+ });
+
+ it('ControllerRegistry.initAgentDB', async () => {
+ const fake = agentdbModuleRecordingHandle();
+ vi.resetModules();
+ vi.doMock('agentdb', () => fake.module);
+ const { ControllerRegistry } = await import('./controller-registry.js');
+
+ await (new ControllerRegistry() as any).initAgentDB({ dbPath: ':memory:' });
+
+ expect(fake.opened).toHaveLength(1);
+ expect(fake.opened[0]).toBeInstanceOf(Database);
+ (fake.opened[0] as Database.Database).close();
+ });
+
+ it('AgentDBBackend.initialize', async () => {
+ const fake = agentdbModuleRecordingHandle();
+ vi.resetModules();
+ vi.doMock('agentdb', () => fake.module);
+ const { AgentDBBackend } = await import('./agentdb-backend.js');
+ const errors = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ // Schema setup after initialize() may fail against the fake; the handle is what matters.
+ await new AgentDBBackend({ dbPath: ':memory:' } as any).initialize();
+ errors.mockRestore();
+
+ expect(fake.opened).toHaveLength(1);
+ expect(fake.opened[0]).toBeInstanceOf(Database);
+ (fake.opened[0] as Database.Database).close();
+ });
+});
+
+/**
+ * Drift guard: useHostSqliteDriver replaces AgentDB.initializeDatabase(). If
+ * agentdb renames it or stops routing initialize() through it, the helper would
+ * silently do nothing — fail here instead.
+ */
+describe('agentdb AgentDB contract the helper depends on', () => {
+ it('initialize() opens its handle through initializeDatabase(dbPath) with native better-sqlite3', async () => {
+ const { AgentDB } = (await import('agentdb')) as any;
+ const source = readFileSync(createRequire(import.meta.url).resolve('agentdb').replace(/index\.js$/, 'core/AgentDB.js'), 'utf8');
+
+ expect(typeof AgentDB.prototype.initializeDatabase).toBe('function');
+ expect(useHostSqliteDriver(new AgentDB({ dbPath: ':memory:' }))).toBe(true);
+ expect(source).toMatch(/this\.db\s*=\s*await\s+this\.initializeDatabase\(dbPath\)/);
+ expect(source).toMatch(/import\('better-sqlite3'\)/);
+ expect(source).toMatch(/pragma\('journal_mode = WAL'\)/);
+ });
+});
diff --git a/v3/@claude-flow/memory/src/agentdb-native-driver.ts b/v3/@claude-flow/memory/src/agentdb-native-driver.ts
index 65097a46ff..95dc3e1dd3 100644
--- a/v3/@claude-flow/memory/src/agentdb-native-driver.ts
+++ b/v3/@claude-flow/memory/src/agentdb-native-driver.ts
@@ -15,7 +15,14 @@
* handle through it keeps the source-built 11.x addon out of the process.
* `overrides` cannot do this: npm ignores them in a dependency's package.json,
* which is where ours sit for anyone installing ruflo.
+ *
+ * getHostSqliteDriver() is the single source of the constructor: the CLI's
+ * shared-sqlite loader (#3693/#3883) resolves better-sqlite3 from this file's
+ * location too, so every handle on memory.db shares one native copy.
*/
+import { createRequire } from 'node:module';
+
+type DbCtor = new (path: string, opts?: Record<string, unknown>) => { pragma(sql: string): unknown };
type AgentDBLike = {
config?: { forceWasm?: boolean };
@@ -23,21 +30,36 @@ type AgentDBLike = {
initializeDatabase?: (dbPath: string) => Promise<unknown>;
};
+let hostDriver: DbCtor | null | undefined;
+
+/** The better-sqlite3 constructor this package resolves, or null when it is not installed. */
+export function getHostSqliteDriver(): DbCtor | null {
+ if (hostDriver !== undefined) return hostDriver;
+ try {
+ const mod = createRequire(import.meta.url)('better-sqlite3');
+ hostDriver = (mod?.default ?? mod) as DbCtor;
+ } catch {
+ hostDriver = null;
+ }
+ return hostDriver;
+}
+
/**
* Replace `agentdb.initializeDatabase` so `initialize()` opens the database
- * with our better-sqlite3. Must be called before `agentdb.initialize()`.
+ * with getHostSqliteDriver(). Must be called before `agentdb.initialize()`.
* Falls back to AgentDB's own loader when ours cannot open the file, and
- * leaves `forceWasm` instances alone.
+ * leaves `forceWasm` instances alone. Returns whether the loader was replaced.
*/
-export function useHostSqliteDriver(agentdb: AgentDBLike | null | undefined): void {
- if (!agentdb || typeof agentdb.initializeDatabase !== 'function') return;
- if (agentdb.config?.forceWasm) return;
+export function useHostSqliteDriver(agentdb: AgentDBLike | null | undefined): boolean {
+ if (!agentdb || typeof agentdb.initializeDatabase !== 'function') return false;
+ if (agentdb.config?.forceWasm) return false;
const agentdbLoader = agentdb.initializeDatabase.bind(agentdb);
agentdb.initializeDatabase = async (dbPath: string) => {
- let db: { pragma(sql: string): unknown };
+ const Database = getHostSqliteDriver();
+ if (!Database) return agentdbLoader(dbPath);
+ let db: InstanceType<DbCtor>;
try {
- const Database = (await import('better-sqlite3')).default;
db = new Database(dbPath);
} catch {
return agentdbLoader(dbPath);
@@ -47,4 +69,5 @@ export function useHostSqliteDriver(agentdb: AgentDBLike | null | undefined): vo
agentdb.usingWasm = false;
return db;
};
+ return true;
}
diff --git a/v3/@claude-flow/memory/src/index.ts b/v3/@claude-flow/memory/src/index.ts
index a0083911fd..e9ec506d44 100644
--- a/v3/@claude-flow/memory/src/index.ts
+++ b/v3/@claude-flow/memory/src/index.ts
@@ -201,6 +201,7 @@ export {
export type { LockInspection, LockState, LockGuardOptions } from './agentdb-lock-guard.js';
export { AgentDBBackend } from './agentdb-backend.js';
export type { AgentDBBackendConfig } from './agentdb-backend.js';
+export { getHostSqliteDriver, useHostSqliteDriver } from './agentdb-native-driver.js';
export {
AgentDbRetrievalGuard,
createAgentDbRetrievalGuard,