@ai-devkit/agent-manager 0.26.4 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-devkit/agent-manager",
-  "version": "0.26.4",
+  "version": "0.27.0",
   "type": "module",
   "description": "Standalone agent detection and management utilities for AI DevKit",
   "main": "dist/index.js",

package/src/AgentManager.ts

@@ -26,6 +26,13 @@ export interface ListAgentsOptions {
     sortBy?: AgentSortKey;
 }
 
+export class AgentNotRunningError extends Error {
+    constructor(public agentName: string) {
+        super(`Agent "${agentName}" is no longer running.`);
+        this.name = 'AgentNotRunningError';
+    }
+}
+
 /**
  * Agent Manager Class
  * 
@@ -194,6 +201,8 @@ export class AgentManager {
             const entry = preExistingByIdentity.get(identityKey(agent.type, agent.pid));
             if (entry) {
                 agent.name = entry.name;
+                agent.pinned = entry.pinned;
+                if (entry.pinned && entry.updatedAt) agent.lastActive = new Date(entry.updatedAt);
             }
         }
 
@@ -211,9 +220,21 @@ export class AgentManager {
             startedAt: existing?.startedAt ?? new Date().toISOString(),
             sessionId: agent.sessionId,
             sessionFilePath: agent.sessionFilePath ?? '',
+            pinned: existing?.pinned ?? agent.pinned ?? false,
         };
     }
 
+    togglePin(agentName: string): boolean {
+        const entry = this.registry.lookup(agentName);
+        if (!entry || !this.registry.isAlive(entry)) {
+            if (entry) this.registry.prune();
+            throw new AgentNotRunningError(agentName);
+        }
+        const pinned = this.registry.togglePin(entry.type, entry.pid);
+        if (pinned === null) throw new AgentNotRunningError(agentName);
+        return pinned;
+    }
+
     /**
      * List historical sessions across every registered adapter.
      *

package/src/__tests__/AgentManager.test.ts

@@ -554,6 +554,58 @@ describe('AgentManager', () => {
             expect(writes).toEqual([]);
         });
 
+        it('exposes a persisted pin and preserves it across a changed poll refresh', async () => {
+            const adapter = new MockAdapter('claude', [
+                createMockAgent({ name: 'pinned', pid: process.pid, sessionId: 'before' }),
+            ]);
+            scopedManager.registerAdapter(adapter);
+            await scopedManager.listAgents();
+            registry.togglePin('claude', process.pid);
+            adapter.setAgents([
+                createMockAgent({ name: 'pinned', pid: process.pid, sessionId: 'after' }),
+            ]);
+
+            const agents = await scopedManager.listAgents();
+
+            expect(agents[0].pinned).toBe(true);
+            expect(registry.lookup('pinned')).toMatchObject({ sessionId: 'after', pinned: true });
+        });
+
+        it('uses registry updated_at as lastActive for pinned recency ordering', async () => {
+            const adapter = new MockAdapter('claude', [
+                createMockAgent({
+                    name: 'recently-pinned',
+                    pid: process.pid,
+                    lastActive: new Date('2026-01-01T00:00:00.000Z'),
+                }),
+            ]);
+            scopedManager.registerAdapter(adapter);
+            await scopedManager.listAgents();
+            nowMs += 60_000;
+            scopedManager.togglePin('recently-pinned');
+
+            const agents = await scopedManager.listAgents();
+
+            expect(agents[0].pinned).toBe(true);
+            expect(agents[0].lastActive.toISOString()).toBe('2026-08-14T10:01:00.000Z');
+        });
+
+        it('preserves adapter lastActive for unpinned agents', async () => {
+            scopedManager.registerAdapter(new MockAdapter('claude', [
+                createMockAgent({
+                    name: 'unpinned',
+                    pid: process.pid,
+                    lastActive: new Date('2026-01-01T00:00:00.000Z'),
+                }),
+            ]));
+
+            await scopedManager.listAgents();
+            const agents = await scopedManager.listAgents();
+
+            expect(agents[0].pinned).toBe(false);
+            expect(agents[0].lastActive.toISOString()).toBe('2026-01-01T00:00:00.000Z');
+        });
+
         it('persists changed fields once in one write transaction', async () => {
             const adapter = new MockAdapter('claude', [
                 createMockAgent({ name: 'changing', pid: process.pid, projectPath: '/cwd/before' }),
@@ -645,6 +697,71 @@ describe('AgentManager', () => {
         });
     });
 
+    describe('togglePin', () => {
+        it('resolves the agent name to its process identity and toggles the pin', () => {
+            const registry = new AgentRegistry(path.join(tmpDir, 'toggle.json'));
+            const scopedManager = new AgentManager(registry);
+            registry.register({
+                name: 'renamed-agent',
+                type: 'claude',
+                pid: process.pid,
+                tmuxSession: '',
+                cwd: '/tmp',
+                startedAt: '2026-08-16T00:00:00.000Z',
+                sessionId: 'session',
+                sessionFilePath: '',
+                pinned: false,
+            });
+
+            expect(scopedManager.togglePin('renamed-agent')).toBe(true);
+            expect(registry.lookup('renamed-agent')?.pinned).toBe(true);
+        });
+
+        it('reports when the agent is no longer running', () => {
+            expect(() => manager.togglePin('missing')).toThrow(/no longer running/i);
+        });
+
+        it('rejects a dead process and prunes its row', () => {
+            const registry = new AgentRegistry(path.join(tmpDir, 'dead-toggle.json'));
+            const scopedManager = new AgentManager(registry);
+            registry.register({
+                name: 'dead',
+                type: 'claude',
+                pid: 999999,
+                tmuxSession: '',
+                cwd: '/tmp',
+                startedAt: '2026-08-16T00:00:00.000Z',
+                sessionId: 'session',
+                sessionFilePath: '',
+                pinned: false,
+            });
+
+            expect(() => scopedManager.togglePin('dead')).toThrow(/no longer running/i);
+            expect(registry.lookup('dead')).toBeNull();
+        });
+
+        it('surfaces a clear readonly mutation error', () => {
+            const regPath = path.join(tmpDir, 'readonly-toggle.json');
+            const writable = new AgentRegistry(regPath);
+            writable.register({
+                name: 'readonly-agent',
+                type: 'claude',
+                pid: process.pid,
+                tmuxSession: '',
+                cwd: '/tmp',
+                startedAt: '2026-08-16T00:00:00.000Z',
+                sessionId: 'session',
+                sessionFilePath: '',
+                pinned: false,
+            });
+            const readonlyManager = new AgentManager(new AgentRegistry(regPath, { readonly: true }));
+
+            expect(() => readonlyManager.togglePin('readonly-agent')).toThrow(
+                'Agent registry is readonly; cannot toggle pin.',
+            );
+        });
+    });
+
     describe('clear', () => {
         it('should remove all adapters', () => {
             manager.registerAdapter(new MockAdapter('claude'));

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,
     };
 }
@@ -172,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([]);

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

@@ -20,23 +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,
+            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';

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,6 +43,7 @@ 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');
@@ -52,20 +55,24 @@ 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, 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,
         });
     }
 
@@ -86,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,
         };
     }
 
@@ -256,6 +265,18 @@ export class AgentRegistry {
         });
     }
 
+    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;
     }