🌊 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(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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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): voagentdb.usingWasm = false;return db;};+ return true;}diff --git a/v3/@claude-flow/memory/src/index.ts b/v3/@claude-flow/memory/src/index.tsindex 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,