@ai-devkit/agent-manager 0.26.3 → 0.27.0

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

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
+import Database from 'better-sqlite3';
 import { AgentRegistry, RenameNotFoundError, RenameConflictError, type RegistryEntry } from '../../utils/AgentRegistry.js';
 
 function makeEntry(over: Partial<RegistryEntry> = {}): RegistryEntry {
@@ -13,6 +14,7 @@ function makeEntry(over: Partial<RegistryEntry> = {}): RegistryEntry {
         startedAt: '2026-05-30T00:00:00.000Z',
         sessionId: 'sid-1',
         sessionFilePath: '/tmp/session.jsonl',
+        pinned: false,
         ...over,
     };
 }
@@ -29,6 +31,7 @@ describe('AgentRegistry', () => {
     });
 
     afterEach(() => {
+        vi.restoreAllMocks();
         fs.rmSync(tmpDir, { recursive: true, force: true });
     });
 
@@ -81,6 +84,19 @@ describe('AgentRegistry', () => {
             expect(registry.lookup(`ai-devkit-${process.pid}`)).toBeNull();
             expect(registry.list()).toHaveLength(1);
         });
+
+        it('preserves an existing name conflict when its probe fails with EPERM', () => {
+            registry.register(makeEntry({ name: 'claimed-name', pid: process.pid }));
+            vi.spyOn(process, 'kill').mockImplementation(() => {
+                throw Object.assign(new Error('operation not permitted'), { code: 'EPERM' });
+            });
+
+            expect(() => registry.register(makeEntry({
+                name: 'claimed-name',
+                pid: process.pid + 1,
+            }))).toThrow();
+            expect(registry.lookup('claimed-name')?.pid).toBe(process.pid);
+        });
     });
 
     describe('registerBatch', () => {
@@ -118,6 +134,33 @@ describe('AgentRegistry', () => {
             expect(registry.list()).toHaveLength(1);
             expect(registry.lookup('custom-name')?.pid).toBe(process.pid);
         });
+
+        it('cleans up a cross-type row when its pid has been reused', () => {
+            registry.register(makeEntry({ name: 'old-claude', type: 'claude', pid: process.pid }));
+
+            registry.register(makeEntry({
+                name: 'new-codex',
+                type: 'codex',
+                pid: process.pid,
+                tmuxSession: '',
+            }));
+
+            expect(registry.lookup('old-claude')).toBeNull();
+            expect(registry.lookup('new-codex')).toMatchObject({ type: 'codex', pid: process.pid });
+            expect(registry.list()).toHaveLength(1);
+        });
+
+        it('rolls back the whole batch when a live name conflict rejects one entry', () => {
+            registry.register(makeEntry({ name: 'taken', pid: process.pid }));
+
+            expect(() => registry.registerBatch([
+                makeEntry({ name: 'fresh', pid: 999998 }),
+                makeEntry({ name: 'taken', type: 'codex', pid: 999997 }),
+            ])).toThrow(/UNIQUE constraint failed/);
+
+            expect(registry.lookup('fresh')).toBeNull();
+            expect(registry.lookup('taken')?.pid).toBe(process.pid);
+        });
     });
 
     describe('lookup', () => {
@@ -131,6 +174,72 @@ describe('AgentRegistry', () => {
         });
     });
 
+    describe('pinning', () => {
+        it('defaults new rows to unpinned and toggles the persisted state', () => {
+            registry.register(makeEntry());
+
+            expect(registry.lookup('agent1')?.pinned).toBe(false);
+            expect(registry.togglePin('claude', process.pid)).toBe(true);
+            expect(registry.lookup('agent1')?.pinned).toBe(true);
+            expect(registry.togglePin('claude', process.pid)).toBe(false);
+            expect(registry.lookup('agent1')?.pinned).toBe(false);
+        });
+
+        it('updates existing recency when toggled', () => {
+            let now = new Date('2026-08-16T10:00:00.000Z');
+            const clocked = new AgentRegistry(regPath, { now: () => now });
+            clocked.register(makeEntry());
+            now = new Date('2026-08-16T10:01:00.000Z');
+
+            clocked.togglePin('claude', process.pid);
+
+            expect(clocked.lookup('agent1')?.updatedAt).toBe(now.toISOString());
+            const db = new Database(regPath.replace(/\.json$/, '.db'), { readonly: true });
+            const row = db.prepare('SELECT updated_at FROM agents WHERE type = ? AND pid = ?')
+                .get('claude', process.pid) as { updated_at: string };
+            db.close();
+            expect(row.updated_at).toBe(now.toISOString());
+        });
+
+        it('returns null when the process row has disappeared', () => {
+            expect(registry.togglePin('claude', 999999)).toBeNull();
+        });
+
+        it('preserves a pin when poll registration updates the row', () => {
+            registry.register(makeEntry({ sessionId: 'before' }));
+            registry.togglePin('claude', process.pid);
+
+            registry.register(makeEntry({ sessionId: 'after' }));
+
+            expect(registry.lookup('agent1')).toMatchObject({ sessionId: 'after', pinned: true });
+        });
+
+        it('preserves a pin through rename', () => {
+            registry.register(makeEntry({ name: 'before' }));
+            registry.togglePin('claude', process.pid);
+
+            registry.rename('before', 'after');
+
+            expect(registry.lookup('after')?.pinned).toBe(true);
+        });
+
+        it('removes the pin with a pruned process row', () => {
+            registry.register(makeEntry({ pid: 999999 }));
+            registry.togglePin('claude', 999999);
+
+            registry.prune();
+
+            expect(registry.lookup('agent1')).toBeNull();
+        });
+
+        it('reports a clear error when a readonly registry toggles a pin', () => {
+            registry.register(makeEntry());
+            const readonlyRegistry = new AgentRegistry(regPath, { readonly: true });
+
+            expect(() => readonlyRegistry.togglePin('claude', process.pid)).toThrow(/readonly/i);
+        });
+    });
+
     describe('list', () => {
         it('returns empty array when database does not contain entries', () => {
             expect(registry.list()).toEqual([]);
@@ -157,6 +266,30 @@ describe('AgentRegistry', () => {
         it('returns false for a PID that does not exist', () => {
             expect(registry.isAlive(makeEntry({ pid: 999999 }))).toBe(false);
         });
+
+        it('returns true when the process probe is forbidden with EPERM', () => {
+            vi.spyOn(process, 'kill').mockImplementation(() => {
+                throw Object.assign(new Error('operation not permitted'), { code: 'EPERM' });
+            });
+
+            expect(registry.isAlive(makeEntry())).toBe(true);
+        });
+
+        it('returns false when the process probe reports ESRCH', () => {
+            vi.spyOn(process, 'kill').mockImplementation(() => {
+                throw Object.assign(new Error('no such process'), { code: 'ESRCH' });
+            });
+
+            expect(registry.isAlive(makeEntry())).toBe(false);
+        });
+
+        it('returns true when the process probe fails without a definitive error code', () => {
+            vi.spyOn(process, 'kill').mockImplementation(() => {
+                throw new Error('indeterminate probe failure');
+            });
+
+            expect(registry.isAlive(makeEntry())).toBe(true);
+        });
     });
 
     describe('prune', () => {
@@ -177,9 +310,52 @@ describe('AgentRegistry', () => {
             expect(after).toEqual(before);
         });
 
+        it('preserves entries when liveness probing fails with EPERM', () => {
+            registry.register(makeEntry({ name: 'custom-name', tmuxSession: 'tmux-custom' }));
+            vi.spyOn(process, 'kill').mockImplementation(() => {
+                throw Object.assign(new Error('operation not permitted'), { code: 'EPERM' });
+            });
+
+            registry.prune();
+
+            expect(registry.lookup('custom-name')).toMatchObject({
+                name: 'custom-name',
+                tmuxSession: 'tmux-custom',
+            });
+        });
+
+        it('removes entries when liveness probing fails with ESRCH', () => {
+            registry.register(makeEntry({ name: 'dead' }));
+            vi.spyOn(process, 'kill').mockImplementation(() => {
+                throw Object.assign(new Error('no such process'), { code: 'ESRCH' });
+            });
+
+            registry.prune();
+
+            expect(registry.lookup('dead')).toBeNull();
+        });
+
         it('does nothing when file is missing', () => {
             expect(() => registry.prune()).not.toThrow();
         });
+
+        it('keeps forced prune available before the passive cadence is due', () => {
+            let nowMs = Date.parse('2026-08-14T10:00:00.000Z');
+            const clocked = new AgentRegistry(regPath, {
+                now: () => new Date(nowMs),
+                pruneIntervalMs: 30_000,
+            });
+            clocked.register(makeEntry({ name: 'forced', pid: process.pid }));
+            const alive = vi.spyOn(clocked, 'isAlive').mockReturnValue(true);
+            clocked.pruneIfDue();
+            alive.mockReturnValue(false);
+            nowMs += 1;
+
+            clocked.prune();
+
+            expect(alive).toHaveBeenCalledTimes(2);
+            expect(clocked.lookup('forced')).toBeNull();
+        });
     });
 
     describe('default()', () => {
@@ -215,6 +391,17 @@ describe('AgentRegistry', () => {
             expect(() => registry.rename('agent-a', 'agent-b')).toThrow(RenameConflictError);
         });
 
+        it('throws RenameConflictError when the conflicting entry probe fails with EPERM', () => {
+            registry.register(makeEntry({ name: 'agent-a', pid: process.pid }));
+            registry.register(makeEntry({ name: 'agent-b', pid: process.ppid }));
+            vi.spyOn(process, 'kill').mockImplementation(() => {
+                throw Object.assign(new Error('operation not permitted'), { code: 'EPERM' });
+            });
+
+            expect(() => registry.rename('agent-a', 'agent-b')).toThrow(RenameConflictError);
+            expect(registry.lookup('agent-b')?.pid).toBe(process.ppid);
+        });
+
         it('succeeds when new name exists only as a stale (dead) entry', () => {
             registry.register(makeEntry({ name: 'agent-a', pid: process.pid }));
             registry.register(makeEntry({ name: 'agent-b', pid: 999999 }));

package/src/adapters/AgentAdapter.ts

@@ -48,6 +48,9 @@ export interface AgentInfo {
     /** Timestamp of last activity */
     lastActive: Date;
 
+    /** Whether the live process is pinned in the agent console */
+    pinned?: boolean;
+
     /** Path to the session JSONL file on disk */
     sessionFilePath?: string;
 }

package/src/database/connection.ts

@@ -8,7 +8,7 @@ export const DEFAULT_AGENT_REGISTRY_DB_PATH = join(homedir(), '.ai-devkit', 'age
 
 export interface DatabaseOptions {
     dbPath?: string;
-    verbose?: boolean;
+    verbose?: boolean | ((message: string) => void);
     readonly?: boolean;
 }
 
@@ -20,21 +20,30 @@ export function resolveAgentRegistryDbPath(filePath?: string): string {
 export class DatabaseConnection {
     private db: Database.Database;
     private readonly dbPath: string;
+    private readonly readonly: boolean;
 
     constructor(options: DatabaseOptions = {}) {
         this.dbPath = options.dbPath ?? DEFAULT_AGENT_REGISTRY_DB_PATH;
+        this.readonly = options.readonly ?? false;
         mkdirSync(dirname(this.dbPath), { recursive: true });
 
         this.db = new Database(this.dbPath, {
-            readonly: options.readonly ?? false,
-            verbose: options.verbose ? console.log : undefined,
+            readonly: this.readonly,
+            verbose: typeof options.verbose === 'function'
+                ? options.verbose
+                : options.verbose ? console.log : undefined,
         });
 
         this.configure();
-        initializeSchema(this);
+        if (!this.readonly) initializeSchema(this);
     }
 
     private configure(): void {
+        if (this.readonly) {
+            this.db.pragma('foreign_keys = ON');
+            this.db.pragma('busy_timeout = 5000');
+            return;
+        }
         this.db.pragma('journal_mode = WAL');
         this.db.pragma('foreign_keys = ON');
         this.db.pragma('synchronous = NORMAL');

package/src/database/migrations/002_pins.sql

@@ -0,0 +1 @@
+ALTER TABLE agents ADD COLUMN pinned INTEGER NOT NULL DEFAULT 0;

package/src/index.ts

@@ -1,4 +1,4 @@
-export { AgentManager } from './AgentManager.js';
+export { AgentManager, AgentNotRunningError } from './AgentManager.js';
 
 export { ClaudeCodeAdapter } from './adapters/ClaudeCodeAdapter.js';
 export { CodexAdapter } from './adapters/CodexAdapter.js';
@@ -29,7 +29,7 @@ export type { AgentSortKey } from './utils/sortAgents.js';
 export type { ListAgentsOptions } from './AgentManager.js';
 
 export { AgentRegistry, RenameNotFoundError, RenameConflictError } from './utils/AgentRegistry.js';
-export type { RegistryEntry } from './utils/AgentRegistry.js';
+export type { AgentRegistryOptions, RegistryEntry } from './utils/AgentRegistry.js';
 export { TmuxManager } from './terminal/TmuxManager.js';
 export { AGENTS } from './utils/agents.js';
 export type { AgentConfig, StartableAgentType } from './utils/agents.js';

package/src/utils/AgentRegistry.ts

@@ -29,6 +29,8 @@ export interface RegistryEntry {
     startedAt: string;  // ISO 8601
     sessionId: string;
     sessionFilePath: string;
+    pinned: boolean;
+    updatedAt?: string;
 }
 
 interface RegistryRow {
@@ -41,17 +43,37 @@ interface RegistryRow {
     session_id: string;
     session_file_path: string;
     updated_at: string;
+    pinned: number;
 }
 
 const DEFAULT_REGISTRY_PATH = path.join(os.homedir(), '.ai-devkit', 'agents.json');
+const DEFAULT_PRUNE_INTERVAL_MS = 30_000;
 
 let defaultInstance: AgentRegistry | null = null;
 
+export interface AgentRegistryOptions {
+    now?: () => Date;
+    pruneIntervalMs?: number;
+    onDatabaseOperation?: (sql: string) => void;
+    readonly?: boolean;
+}
+
 export class AgentRegistry {
     private db: DatabaseConnection;
+    private readonly now: () => Date;
+    private readonly pruneIntervalMs: number;
+    private readonly readonly: boolean;
+    private lastPrunedAt: number | undefined;
 
-    constructor(filePath: string = DEFAULT_REGISTRY_PATH) {
-        this.db = new DatabaseConnection({ dbPath: resolveAgentRegistryDbPath(filePath) });
+    constructor(filePath: string = DEFAULT_REGISTRY_PATH, options: AgentRegistryOptions = {}) {
+        this.now = options.now ?? (() => new Date());
+        this.pruneIntervalMs = options.pruneIntervalMs ?? DEFAULT_PRUNE_INTERVAL_MS;
+        this.readonly = options.readonly ?? false;
+        this.db = new DatabaseConnection({
+            dbPath: resolveAgentRegistryDbPath(filePath),
+            verbose: options.onDatabaseOperation,
+            readonly: this.readonly,
+        });
     }
 
     static default(): AgentRegistry {
@@ -71,6 +93,8 @@ export class AgentRegistry {
             startedAt: row.started_at,
             sessionId: row.session_id,
             sessionFilePath: row.session_file_path,
+            pinned: row.pinned !== 0,
+            updatedAt: row.updated_at,
         };
     }
 
@@ -101,6 +125,24 @@ export class AgentRegistry {
         return row ? this.rowToEntry(row) : undefined;
     }
 
+    private findPidConflicts(type: AgentType, pid: number): RegistryEntry[] {
+        return this.db.query<RegistryRow>(
+            'SELECT * FROM agents WHERE pid = ? AND type <> ?',
+            [pid, type],
+        ).map((row) => this.rowToEntry(row));
+    }
+
+    private entriesEqual(left: RegistryEntry, right: RegistryEntry): boolean {
+        return left.name === right.name
+            && left.type === right.type
+            && left.pid === right.pid
+            && left.tmuxSession === right.tmuxSession
+            && left.cwd === right.cwd
+            && left.startedAt === right.startedAt
+            && left.sessionId === right.sessionId
+            && left.sessionFilePath === right.sessionFilePath;
+    }
+
     private deleteNameConflict(name: string, type: AgentType, pid: number): void {
         const conflict = this.findByName(name);
         if (!conflict) return;
@@ -126,31 +168,66 @@ export class AgentRegistry {
                 session_id = excluded.session_id,
                 session_file_path = excluded.session_file_path,
                 updated_at = excluded.updated_at
-        `).run({ ...entry, updatedAt: new Date().toISOString() });
+        `).run({ ...entry, updatedAt: this.now().toISOString() });
     }
 
-    private save(entry: RegistryEntry): void {
-        this.deleteNameConflict(entry.name, entry.type, entry.pid);
-        this.insertOrUpdate(entry);
+    private needsWrite(incoming: RegistryEntry): boolean {
+        const existing = this.findByIdentity(incoming.type, incoming.pid);
+        const merged = this.mergeEntry(incoming, existing);
+        return !existing
+            || !this.entriesEqual(merged, existing)
+            || this.findPidConflicts(incoming.type, incoming.pid).length > 0;
+    }
+
+    private save(incoming: RegistryEntry): void {
+        const existing = this.findByIdentity(incoming.type, incoming.pid);
+        const merged = this.mergeEntry(incoming, existing);
+        const pidConflicts = this.findPidConflicts(incoming.type, incoming.pid);
+        if (existing && this.entriesEqual(merged, existing) && pidConflicts.length === 0) return;
+
+        for (const conflict of pidConflicts) {
+            this.db.execute('DELETE FROM agents WHERE type = ? AND pid = ?', [conflict.type, conflict.pid]);
+        }
+        if (existing && this.entriesEqual(merged, existing)) return;
+
+        this.deleteNameConflict(merged.name, merged.type, merged.pid);
+        this.insertOrUpdate(merged);
     }
 
     isAlive(entry: RegistryEntry): boolean {
         try {
             process.kill(entry.pid, 0);
             return true;
-        } catch {
-            return false;
+        } catch (error) {
+            const code = error && typeof error === 'object' && 'code' in error
+                ? error.code
+                : undefined;
+            return code !== 'ESRCH';
         }
     }
 
-    prune(): void {
+    private pruneAt(nowMs: number): void {
         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]);
-            }
-        });
+        if (stale.length > 0) {
+            this.db.transaction(() => {
+                for (const entry of stale) {
+                    this.db.execute('DELETE FROM agents WHERE type = ? AND pid = ?', [entry.type, entry.pid]);
+                }
+            });
+        }
+        this.lastPrunedAt = nowMs;
+    }
+
+    prune(): void {
+        this.pruneAt(this.now().getTime());
+    }
+
+    pruneIfDue(): void {
+        const nowMs = this.now().getTime();
+        const elapsed = this.lastPrunedAt === undefined ? undefined : nowMs - this.lastPrunedAt;
+        if (elapsed !== undefined && elapsed >= 0 && elapsed < this.pruneIntervalMs) return;
+        this.pruneAt(nowMs);
     }
 
     register(entry: RegistryEntry): void {
@@ -159,10 +236,10 @@ export class AgentRegistry {
 
     registerBatch(entries: RegistryEntry[]): void {
         if (entries.length === 0) return;
+        if (!entries.some((entry) => this.needsWrite(entry))) return;
         this.db.transaction(() => {
             for (const incoming of entries) {
-                const existing = this.findByIdentity(incoming.type, incoming.pid);
-                this.save(this.mergeEntry(incoming, existing));
+                this.save(incoming);
             }
         });
     }
@@ -183,11 +260,23 @@ export class AgentRegistry {
             }
             this.db.execute(
                 'UPDATE agents SET name = ?, updated_at = ? WHERE type = ? AND pid = ?',
-                [newName, new Date().toISOString(), existing.type, existing.pid],
+                [newName, this.now().toISOString(), existing.type, existing.pid],
             );
         });
     }
 
+    togglePin(type: AgentType, pid: number): boolean | null {
+        if (this.readonly) {
+            throw new Error('Agent registry is readonly; cannot toggle pin.');
+        }
+        const result = this.db.execute(
+            'UPDATE agents SET pinned = NOT pinned, updated_at = ? WHERE type = ? AND pid = ?',
+            [this.now().toISOString(), type, pid],
+        );
+        if (result.changes === 0) return null;
+        return this.findByIdentity(type, pid)?.pinned ?? null;
+    }
+
     lookup(name: string): RegistryEntry | null {
         return this.findByName(name) ?? null;
     }