@ai-devkit/agent-manager 0.26.1 → 0.26.2

package/src/__tests__/utils/AgentRegistry.test.ts

@@ -33,29 +33,28 @@ describe('AgentRegistry', () => {
     });
 
     describe('register', () => {
-        it('creates the file and parent directory if missing', () => {
+        it('creates the SQLite database and parent directory if missing', () => {
             registry.register(makeEntry());
-            expect(fs.existsSync(regPath)).toBe(true);
-            const parsed = JSON.parse(fs.readFileSync(regPath, 'utf8'));
-            expect(parsed.entries).toHaveLength(1);
-            expect(parsed.entries[0].name).toBe('agent1');
+            expect(fs.existsSync(regPath.replace(/\.json$/, '.db'))).toBe(true);
+            expect(registry.list()[0].name).toBe('agent1');
         });
 
         it('appends a new entry when name is unique', () => {
             registry.register(makeEntry({ name: 'a' }));
-            registry.register(makeEntry({ name: 'b' }));
+            registry.register(makeEntry({ name: 'b', pid: process.ppid }));
             expect(registry.list()).toHaveLength(2);
         });
 
-        it('upserts in place when name already exists', () => {
-            registry.register(makeEntry({ name: 'a', pid: 100 }));
-            registry.register(makeEntry({ name: 'a', pid: 200 }));
+        it('upserts in place when type and pid already exist', () => {
+            registry.register(makeEntry({ name: 'a', pid: process.pid }));
+            registry.register(makeEntry({ name: 'fallback', pid: process.pid, tmuxSession: '' }));
             const all = registry.list();
             expect(all).toHaveLength(1);
-            expect(all[0].pid).toBe(200);
+            expect(all[0].pid).toBe(process.pid);
+            expect(all[0].name).toBe('a');
         });
 
-        it('writes atomically (no leftover .tmp on success)', () => {
+        it('does not write through the legacy fixed .tmp path', () => {
             registry.register(makeEntry());
             expect(fs.existsSync(`${regPath}.tmp`)).toBe(false);
         });
@@ -69,16 +68,18 @@ describe('AgentRegistry', () => {
 
         it('preserves existing tmuxSession when incoming is empty string', () => {
             registry.register(makeEntry({ name: 'a', tmuxSession: 'pinned' }));
-            registry.register(makeEntry({ name: 'a', tmuxSession: '', pid: 999 }));
+            registry.register(makeEntry({ name: 'fallback', tmuxSession: '', pid: process.pid }));
             const saved = registry.lookup('a');
             expect(saved?.tmuxSession).toBe('pinned');
-            expect(saved?.pid).toBe(999);
+            expect(saved?.pid).toBe(process.pid);
         });
 
-        it('replaces tmuxSession when incoming is non-empty', () => {
-            registry.register(makeEntry({ name: 'a', tmuxSession: 'old' }));
-            registry.register(makeEntry({ name: 'a', tmuxSession: 'new' }));
-            expect(registry.lookup('a')?.tmuxSession).toBe('new');
+        it('lets a managed start entry replace a generated fallback for the same pid', () => {
+            registry.register(makeEntry({ name: `ai-devkit-${process.pid}`, tmuxSession: '' }));
+            registry.register(makeEntry({ name: 'custom-name', tmuxSession: 'custom-name' }));
+            expect(registry.lookup('custom-name')?.tmuxSession).toBe('custom-name');
+            expect(registry.lookup(`ai-devkit-${process.pid}`)).toBeNull();
+            expect(registry.list()).toHaveLength(1);
         });
     });
 
@@ -88,28 +89,35 @@ describe('AgentRegistry', () => {
             expect(fs.existsSync(regPath)).toBe(false);
         });
 
-        it('upserts multiple entries with a single write', () => {
-            const writeSpy = vi.spyOn(fs, 'writeFileSync');
+        it('upserts multiple entries in a single batch', () => {
             registry.registerBatch([
                 makeEntry({ name: 'a' }),
-                makeEntry({ name: 'b' }),
-                makeEntry({ name: 'c' }),
+                makeEntry({ name: 'b', pid: process.pid + 1 }),
+                makeEntry({ name: 'c', pid: process.pid + 2 }),
             ]);
-            expect(writeSpy).toHaveBeenCalledTimes(1);
-            writeSpy.mockRestore();
             expect(registry.list()).toHaveLength(3);
         });
 
         it('applies the tmuxSession merge per entry', () => {
             registry.register(makeEntry({ name: 'a', tmuxSession: 'pinned' }));
             registry.registerBatch([
-                makeEntry({ name: 'a', tmuxSession: '', pid: 7 }),
-                makeEntry({ name: 'b', tmuxSession: '' }),
+                makeEntry({ name: 'fallback', tmuxSession: '', pid: process.pid }),
+                makeEntry({ name: 'b', tmuxSession: '', pid: process.pid + 1 }),
             ]);
             expect(registry.lookup('a')?.tmuxSession).toBe('pinned');
-            expect(registry.lookup('a')?.pid).toBe(7);
+            expect(registry.lookup('a')?.pid).toBe(process.pid);
             expect(registry.lookup('b')?.tmuxSession).toBe('');
         });
+
+        it('handles concurrent registry instances without duplicate pid rows', () => {
+            const other = new AgentRegistry(regPath);
+            registry.register(makeEntry({ name: `ai-devkit-${process.pid}`, tmuxSession: '' }));
+            other.register(makeEntry({ name: 'custom-name', tmuxSession: 'custom-name' }));
+            registry.register(makeEntry({ name: `ai-devkit-${process.pid}`, tmuxSession: '' }));
+
+            expect(registry.list()).toHaveLength(1);
+            expect(registry.lookup('custom-name')?.pid).toBe(process.pid);
+        });
     });
 
     describe('lookup', () => {
@@ -124,20 +132,20 @@ describe('AgentRegistry', () => {
     });
 
     describe('list', () => {
-        it('returns empty array when file does not exist', () => {
+        it('returns empty array when database does not contain entries', () => {
             expect(registry.list()).toEqual([]);
         });
 
-        it('returns empty array when file is malformed', () => {
+        it('ignores existing legacy agents.json entries', () => {
+            const legacyEntry = makeEntry({ name: 'legacy', tmuxSession: 'legacy' });
             fs.mkdirSync(path.dirname(regPath), { recursive: true });
-            fs.writeFileSync(regPath, 'not json', 'utf8');
-            expect(registry.list()).toEqual([]);
-        });
+            fs.writeFileSync(regPath, JSON.stringify({ entries: [legacyEntry] }), 'utf8');
 
-        it('coerces non-array entries to []', () => {
-            fs.mkdirSync(path.dirname(regPath), { recursive: true });
-            fs.writeFileSync(regPath, JSON.stringify({ entries: 'oops' }), 'utf8');
-            expect(registry.list()).toEqual([]);
+            const legacyRegistry = new AgentRegistry(regPath);
+
+            expect(legacyRegistry.lookup('legacy')).toBeNull();
+            expect(legacyRegistry.list()).toEqual([]);
+            expect(fs.existsSync(regPath.replace(/\.json$/, '.db'))).toBe(true);
         });
     });
 
@@ -163,10 +171,10 @@ describe('AgentRegistry', () => {
 
         it('is a no-op when all entries are alive', () => {
             registry.register(makeEntry({ pid: process.pid }));
-            const before = fs.readFileSync(regPath, 'utf8');
+            const before = registry.list();
             registry.prune();
-            const after = fs.readFileSync(regPath, 'utf8');
-            expect(after).toBe(before);
+            const after = registry.list();
+            expect(after).toEqual(before);
         });
 
         it('does nothing when file is missing', () => {
@@ -203,7 +211,7 @@ describe('AgentRegistry', () => {
 
         it('throws RenameConflictError when new name is already in use by a live entry', () => {
             registry.register(makeEntry({ name: 'agent-a', pid: process.pid }));
-            registry.register(makeEntry({ name: 'agent-b', pid: process.pid }));
+            registry.register(makeEntry({ name: 'agent-b', pid: process.ppid }));
             expect(() => registry.rename('agent-a', 'agent-b')).toThrow(RenameConflictError);
         });
 
@@ -214,7 +222,7 @@ describe('AgentRegistry', () => {
             expect(registry.lookup('agent-b')?.pid).toBe(process.pid);
         });
 
-        it('writes atomically (no leftover .tmp on success)', () => {
+        it('does not create the legacy fixed .tmp path on rename', () => {
             registry.register(makeEntry({ name: 'old-name', pid: process.pid }));
             registry.rename('old-name', 'new-name');
             expect(fs.existsSync(`${regPath}.tmp`)).toBe(false);

package/src/database/connection.ts

@@ -0,0 +1,74 @@
+import Database from 'better-sqlite3';
+import { mkdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { homedir } from 'os';
+import { initializeSchema } from './schema.js';
+
+export const DEFAULT_AGENT_REGISTRY_DB_PATH = join(homedir(), '.ai-devkit', 'agents.db');
+
+export interface DatabaseOptions {
+    dbPath?: string;
+    verbose?: boolean;
+    readonly?: boolean;
+}
+
+export function resolveAgentRegistryDbPath(filePath?: string): string {
+    if (!filePath) return DEFAULT_AGENT_REGISTRY_DB_PATH;
+    return filePath.endsWith('.json') ? filePath.replace(/\.json$/, '.db') : filePath;
+}
+
+export class DatabaseConnection {
+    private db: Database.Database;
+    private readonly dbPath: string;
+
+    constructor(options: DatabaseOptions = {}) {
+        this.dbPath = options.dbPath ?? DEFAULT_AGENT_REGISTRY_DB_PATH;
+        mkdirSync(dirname(this.dbPath), { recursive: true });
+
+        this.db = new Database(this.dbPath, {
+            readonly: options.readonly ?? false,
+            verbose: options.verbose ? console.log : undefined,
+        });
+
+        this.configure();
+        initializeSchema(this);
+    }
+
+    private configure(): void {
+        this.db.pragma('journal_mode = WAL');
+        this.db.pragma('foreign_keys = ON');
+        this.db.pragma('synchronous = NORMAL');
+        this.db.pragma('busy_timeout = 5000');
+        this.db.pragma('mmap_size = 268435456');
+    }
+
+    get instance(): Database.Database {
+        return this.db;
+    }
+
+    get path(): string {
+        return this.dbPath;
+    }
+
+    query<T>(sql: string, params: unknown[] = []): T[] {
+        return this.db.prepare(sql).all(...params) as T[];
+    }
+
+    queryOne<T>(sql: string, params: unknown[] = []): T | undefined {
+        return this.db.prepare(sql).get(...params) as T | undefined;
+    }
+
+    execute(sql: string, params: unknown[] = []): Database.RunResult {
+        return this.db.prepare(sql).run(...params);
+    }
+
+    transaction<T>(fn: () => T): T {
+        return this.db.transaction(fn)();
+    }
+
+    close(): void {
+        if (this.db.open) {
+            this.db.close();
+        }
+    }
+}

package/src/database/index.ts

@@ -0,0 +1,7 @@
+export {
+    DatabaseConnection,
+    DEFAULT_AGENT_REGISTRY_DB_PATH,
+    resolveAgentRegistryDbPath,
+} from './connection.js';
+export type { DatabaseOptions } from './connection.js';
+export { getSchemaVersion, initializeSchema } from './schema.js';

package/src/database/migrations/001_initial.sql

@@ -0,0 +1,12 @@
+CREATE TABLE IF NOT EXISTS agents (
+    type TEXT NOT NULL,
+    pid INTEGER NOT NULL,
+    name TEXT NOT NULL UNIQUE,
+    tmux_session TEXT NOT NULL DEFAULT '',
+    cwd TEXT NOT NULL DEFAULT '',
+    started_at TEXT NOT NULL,
+    session_id TEXT NOT NULL DEFAULT '',
+    session_file_path TEXT NOT NULL DEFAULT '',
+    updated_at TEXT NOT NULL,
+    PRIMARY KEY (type, pid)
+);

package/src/database/schema.ts

@@ -0,0 +1,62 @@
+import { readFileSync, readdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import type { DatabaseConnection } from './connection.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export function getSchemaVersion(db: DatabaseConnection): number {
+    const result = db.instance.pragma('user_version') as { user_version: number }[];
+    return result[0]?.user_version ?? 0;
+}
+
+function setSchemaVersion(db: DatabaseConnection, version: number): void {
+    db.instance.pragma(`user_version = ${version}`);
+}
+
+function getMigrationsDir(): string {
+    return join(__dirname, 'migrations');
+}
+
+interface Migration {
+    version: number;
+    path: string;
+    name: string;
+}
+
+function getMigrationFiles(): Migration[] {
+    const migrationsDir = getMigrationsDir();
+
+    let files: string[];
+    try {
+        files = readdirSync(migrationsDir).filter((f) => f.endsWith('.sql')).sort();
+    } catch {
+        return [];
+    }
+
+    return files.map((file) => {
+        const match = file.match(/^(\d+)_(.+)\.sql$/);
+        if (!match || !match[1] || !match[2]) {
+            throw new Error(`Invalid migration filename: ${file}. Expected format: 001_name.sql`);
+        }
+        return {
+            version: parseInt(match[1], 10),
+            name: match[2],
+            path: join(migrationsDir, file),
+        };
+    });
+}
+
+export function initializeSchema(db: DatabaseConnection): void {
+    const currentVersion = getSchemaVersion(db);
+    const pendingMigrations = getMigrationFiles().filter((m) => m.version > currentVersion);
+
+    for (const migration of pendingMigrations) {
+        const sql = readFileSync(migration.path, 'utf-8');
+
+        db.transaction(() => {
+            db.instance.exec(sql);
+            setSchemaVersion(db, migration.version);
+        });
+    }
+}

package/src/utils/AgentRegistry.ts

@@ -1,7 +1,10 @@
-import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import type { AgentType } from '../adapters/AgentAdapter.js';
+import {
+    DatabaseConnection,
+    resolveAgentRegistryDbPath,
+} from '../database/index.js';
 
 export class RenameNotFoundError extends Error {
     constructor(public agentName: string) {
@@ -28,8 +31,16 @@ export interface RegistryEntry {
     sessionFilePath: string;
 }
 
-interface RegistryFile {
-    entries: RegistryEntry[];
+interface RegistryRow {
+    name: string;
+    type: AgentType;
+    pid: number;
+    tmux_session: string;
+    cwd: string;
+    started_at: string;
+    session_id: string;
+    session_file_path: string;
+    updated_at: string;
 }
 
 const DEFAULT_REGISTRY_PATH = path.join(os.homedir(), '.ai-devkit', 'agents.json');
@@ -37,10 +48,10 @@ const DEFAULT_REGISTRY_PATH = path.join(os.homedir(), '.ai-devkit', 'agents.json
 let defaultInstance: AgentRegistry | null = null;
 
 export class AgentRegistry {
-    private filePath: string;
+    private db: DatabaseConnection;
 
     constructor(filePath: string = DEFAULT_REGISTRY_PATH) {
-        this.filePath = filePath;
+        this.db = new DatabaseConnection({ dbPath: resolveAgentRegistryDbPath(filePath) });
     }
 
     static default(): AgentRegistry {
@@ -50,32 +61,79 @@ export class AgentRegistry {
         return defaultInstance;
     }
 
-    private readFile(): RegistryFile {
-        try {
-            const raw = fs.readFileSync(this.filePath, 'utf8');
-            const parsed = JSON.parse(raw) as RegistryFile;
-            return { entries: Array.isArray(parsed.entries) ? parsed.entries : [] };
-        } catch {
-            return { entries: [] };
-        }
-    }
-
-    private writeFile(data: RegistryFile): void {
-        const dir = path.dirname(this.filePath);
-        fs.mkdirSync(dir, { recursive: true });
-        const tmp = `${this.filePath}.tmp`;
-        fs.writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf8');
-        fs.renameSync(tmp, this.filePath);
+    private rowToEntry(row: RegistryRow): RegistryEntry {
+        return {
+            name: row.name,
+            type: row.type,
+            pid: row.pid,
+            tmuxSession: row.tmux_session,
+            cwd: row.cwd,
+            startedAt: row.started_at,
+            sessionId: row.session_id,
+            sessionFilePath: row.session_file_path,
+        };
     }
 
     private mergeEntry(incoming: RegistryEntry, existing: RegistryEntry | undefined): RegistryEntry {
         if (!existing) return incoming;
+        const incomingIsManaged = Boolean(incoming.tmuxSession);
         return {
-            ...incoming,
+            ...existing,
+            name: incomingIsManaged ? incoming.name : existing.name,
             tmuxSession: incoming.tmuxSession || existing.tmuxSession,
+            cwd: incoming.cwd || existing.cwd,
+            startedAt: existing.startedAt || incoming.startedAt,
+            sessionId: incoming.sessionId || existing.sessionId,
+            sessionFilePath: incoming.sessionFilePath || existing.sessionFilePath,
         };
     }
 
+    private findByIdentity(type: AgentType, pid: number): RegistryEntry | undefined {
+        const row = this.db.queryOne<RegistryRow>(
+            'SELECT * FROM agents WHERE type = ? AND pid = ?',
+            [type, pid],
+        );
+        return row ? this.rowToEntry(row) : undefined;
+    }
+
+    private findByName(name: string): RegistryEntry | undefined {
+        const row = this.db.queryOne<RegistryRow>('SELECT * FROM agents WHERE name = ?', [name]);
+        return row ? this.rowToEntry(row) : undefined;
+    }
+
+    private deleteNameConflict(name: string, type: AgentType, pid: number): void {
+        const conflict = this.findByName(name);
+        if (!conflict) return;
+        if (conflict.type === type && conflict.pid === pid) return;
+        if (!this.isAlive(conflict)) {
+            this.db.execute('DELETE FROM agents WHERE type = ? AND pid = ?', [conflict.type, conflict.pid]);
+        }
+    }
+
+    private insertOrUpdate(entry: RegistryEntry): void {
+        this.db.instance.prepare(`
+            INSERT INTO agents (
+                type, pid, name, tmux_session, cwd, started_at, session_id, session_file_path, updated_at
+            )
+            VALUES (
+                @type, @pid, @name, @tmuxSession, @cwd, @startedAt, @sessionId, @sessionFilePath, @updatedAt
+            )
+            ON CONFLICT(type, pid) DO UPDATE SET
+                name = excluded.name,
+                tmux_session = excluded.tmux_session,
+                cwd = excluded.cwd,
+                started_at = agents.started_at,
+                session_id = excluded.session_id,
+                session_file_path = excluded.session_file_path,
+                updated_at = excluded.updated_at
+        `).run({ ...entry, updatedAt: new Date().toISOString() });
+    }
+
+    private save(entry: RegistryEntry): void {
+        this.deleteNameConflict(entry.name, entry.type, entry.pid);
+        this.insertOrUpdate(entry);
+    }
+
     isAlive(entry: RegistryEntry): boolean {
         try {
             process.kill(entry.pid, 0);
@@ -86,11 +144,13 @@ export class AgentRegistry {
     }
 
     prune(): void {
-        const data = this.readFile();
-        const live = data.entries.filter((e) => this.isAlive(e));
-        if (live.length !== data.entries.length) {
-            this.writeFile({ entries: live });
-        }
+        const entries = this.list();
+        const stale = entries.filter((e) => !this.isAlive(e));
+        this.db.transaction(() => {
+            for (const entry of stale) {
+                this.db.execute('DELETE FROM agents WHERE type = ? AND pid = ?', [entry.type, entry.pid]);
+            }
+        });
     }
 
     register(entry: RegistryEntry): void {
@@ -99,41 +159,41 @@ export class AgentRegistry {
 
     registerBatch(entries: RegistryEntry[]): void {
         if (entries.length === 0) return;
-        const data = this.readFile();
-        for (const incoming of entries) {
-            const idx = data.entries.findIndex((e) => e.name === incoming.name);
-            if (idx >= 0) {
-                data.entries[idx] = this.mergeEntry(incoming, data.entries[idx]);
-            } else {
-                data.entries.push(incoming);
+        this.db.transaction(() => {
+            for (const incoming of entries) {
+                const existing = this.findByIdentity(incoming.type, incoming.pid);
+                this.save(this.mergeEntry(incoming, existing));
             }
-        }
-        this.writeFile(data);
+        });
     }
 
     rename(currentName: string, newName: string): void {
-        const data = this.readFile();
-        const idx = data.entries.findIndex((e) => e.name === currentName);
-        if (idx < 0) {
+        const existing = this.findByName(currentName);
+        if (!existing) {
             throw new RenameNotFoundError(currentName);
         }
-        const liveEntries = data.entries.filter((e) => this.isAlive(e));
-        const conflict = liveEntries.find((e) => e.name === newName);
-        if (conflict) {
+        const conflict = this.findByName(newName);
+        if (conflict && this.isAlive(conflict)) {
             throw new RenameConflictError(newName);
         }
-        const pruned = liveEntries.map((e) =>
-            e.name === currentName ? { ...e, name: newName } : e,
-        );
-        this.writeFile({ entries: pruned });
+
+        this.db.transaction(() => {
+            if (conflict) {
+                this.db.execute('DELETE FROM agents WHERE type = ? AND pid = ?', [conflict.type, conflict.pid]);
+            }
+            this.db.execute(
+                'UPDATE agents SET name = ?, updated_at = ? WHERE type = ? AND pid = ?',
+                [newName, new Date().toISOString(), existing.type, existing.pid],
+            );
+        });
     }
 
     lookup(name: string): RegistryEntry | null {
-        const data = this.readFile();
-        return data.entries.find((e) => e.name === name) ?? null;
+        return this.findByName(name) ?? null;
     }
 
     list(): RegistryEntry[] {
-        return this.readFile().entries;
+        const rows = this.db.query<RegistryRow>('SELECT * FROM agents ORDER BY started_at ASC, name ASC');
+        return rows.map((row) => this.rowToEntry(row));
     }
 }