@ai-devkit/agent-manager 0.15.0 → 0.16.0

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

@@ -0,0 +1,223 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { AgentRegistry, RenameNotFoundError, RenameConflictError, type RegistryEntry } from '../../utils/AgentRegistry.js';
+
+function makeEntry(over: Partial<RegistryEntry> = {}): RegistryEntry {
+    return {
+        name: 'agent1',
+        type: 'claude',
+        pid: process.pid,
+        tmuxSession: 'agent1',
+        cwd: '/tmp',
+        startedAt: '2026-05-30T00:00:00.000Z',
+        sessionId: 'sid-1',
+        sessionFilePath: '/tmp/session.jsonl',
+        ...over,
+    };
+}
+
+describe('AgentRegistry', () => {
+    let tmpDir: string;
+    let regPath: string;
+    let registry: AgentRegistry;
+
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-registry-'));
+        regPath = path.join(tmpDir, 'nested', 'agents.json');
+        registry = new AgentRegistry(regPath);
+    });
+
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    describe('register', () => {
+        it('creates the file 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');
+        });
+
+        it('appends a new entry when name is unique', () => {
+            registry.register(makeEntry({ name: 'a' }));
+            registry.register(makeEntry({ name: 'b' }));
+            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 }));
+            const all = registry.list();
+            expect(all).toHaveLength(1);
+            expect(all[0].pid).toBe(200);
+        });
+
+        it('writes atomically (no leftover .tmp on success)', () => {
+            registry.register(makeEntry());
+            expect(fs.existsSync(`${regPath}.tmp`)).toBe(false);
+        });
+
+        it('persists session fields', () => {
+            registry.register(makeEntry({ sessionId: 'sid-xyz', sessionFilePath: '/foo/bar.jsonl' }));
+            const saved = registry.list()[0];
+            expect(saved.sessionId).toBe('sid-xyz');
+            expect(saved.sessionFilePath).toBe('/foo/bar.jsonl');
+        });
+
+        it('preserves existing tmuxSession when incoming is empty string', () => {
+            registry.register(makeEntry({ name: 'a', tmuxSession: 'pinned' }));
+            registry.register(makeEntry({ name: 'a', tmuxSession: '', pid: 999 }));
+            const saved = registry.lookup('a');
+            expect(saved?.tmuxSession).toBe('pinned');
+            expect(saved?.pid).toBe(999);
+        });
+
+        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');
+        });
+    });
+
+    describe('registerBatch', () => {
+        it('is a no-op on empty array', () => {
+            registry.registerBatch([]);
+            expect(fs.existsSync(regPath)).toBe(false);
+        });
+
+        it('upserts multiple entries with a single write', () => {
+            const writeSpy = vi.spyOn(fs, 'writeFileSync');
+            registry.registerBatch([
+                makeEntry({ name: 'a' }),
+                makeEntry({ name: 'b' }),
+                makeEntry({ name: 'c' }),
+            ]);
+            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: '' }),
+            ]);
+            expect(registry.lookup('a')?.tmuxSession).toBe('pinned');
+            expect(registry.lookup('a')?.pid).toBe(7);
+            expect(registry.lookup('b')?.tmuxSession).toBe('');
+        });
+    });
+
+    describe('lookup', () => {
+        it('returns null when name not found', () => {
+            expect(registry.lookup('missing')).toBeNull();
+        });
+
+        it('returns the entry when name matches', () => {
+            registry.register(makeEntry({ name: 'a' }));
+            expect(registry.lookup('a')?.name).toBe('a');
+        });
+    });
+
+    describe('list', () => {
+        it('returns empty array when file does not exist', () => {
+            expect(registry.list()).toEqual([]);
+        });
+
+        it('returns empty array when file is malformed', () => {
+            fs.mkdirSync(path.dirname(regPath), { recursive: true });
+            fs.writeFileSync(regPath, 'not json', 'utf8');
+            expect(registry.list()).toEqual([]);
+        });
+
+        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([]);
+        });
+    });
+
+    describe('isAlive', () => {
+        it('returns true for the current process', () => {
+            expect(registry.isAlive(makeEntry({ pid: process.pid }))).toBe(true);
+        });
+
+        it('returns false for a PID that does not exist', () => {
+            expect(registry.isAlive(makeEntry({ pid: 999999 }))).toBe(false);
+        });
+    });
+
+    describe('prune', () => {
+        it('removes entries whose PIDs are dead', () => {
+            registry.register(makeEntry({ name: 'alive', pid: process.pid }));
+            registry.register(makeEntry({ name: 'dead', pid: 999999 }));
+            registry.prune();
+            const remaining = registry.list();
+            expect(remaining).toHaveLength(1);
+            expect(remaining[0].name).toBe('alive');
+        });
+
+        it('is a no-op when all entries are alive', () => {
+            registry.register(makeEntry({ pid: process.pid }));
+            const before = fs.readFileSync(regPath, 'utf8');
+            registry.prune();
+            const after = fs.readFileSync(regPath, 'utf8');
+            expect(after).toBe(before);
+        });
+
+        it('does nothing when file is missing', () => {
+            expect(() => registry.prune()).not.toThrow();
+        });
+    });
+
+    describe('default()', () => {
+        it('returns a singleton instance', () => {
+            expect(AgentRegistry.default()).toBe(AgentRegistry.default());
+        });
+    });
+
+    describe('rename', () => {
+        it('updates the name of an existing entry', () => {
+            registry.register(makeEntry({ name: 'old-name', pid: process.pid }));
+            registry.rename('old-name', 'new-name');
+            expect(registry.lookup('new-name')?.name).toBe('new-name');
+            expect(registry.lookup('old-name')).toBeNull();
+        });
+
+        it('preserves all other fields on the renamed entry', () => {
+            registry.register(makeEntry({ name: 'old-name', pid: process.pid, tmuxSession: 'old-name', cwd: '/my/cwd' }));
+            registry.rename('old-name', 'new-name');
+            const entry = registry.lookup('new-name');
+            expect(entry?.tmuxSession).toBe('old-name');
+            expect(entry?.cwd).toBe('/my/cwd');
+            expect(entry?.pid).toBe(process.pid);
+        });
+
+        it('throws RenameNotFoundError when current name does not exist', () => {
+            expect(() => registry.rename('ghost', 'new-name')).toThrow(RenameNotFoundError);
+        });
+
+        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 }));
+            expect(() => registry.rename('agent-a', 'agent-b')).toThrow(RenameConflictError);
+        });
+
+        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 }));
+            expect(() => registry.rename('agent-a', 'agent-b')).not.toThrow();
+            expect(registry.lookup('agent-b')?.pid).toBe(process.pid);
+        });
+
+        it('writes atomically (no leftover .tmp on success)', () => {
+            registry.register(makeEntry({ name: 'old-name', pid: process.pid }));
+            registry.rename('old-name', 'new-name');
+            expect(fs.existsSync(`${regPath}.tmp`)).toBe(false);
+        });
+    });
+});

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

@@ -193,3 +193,74 @@ describe('ClaudeSessionParser.getConversation — harness tag stripping', () =>
         expect(conv[0].content).toBe('before\n\nafter');
     });
 });
+
+describe('ClaudeSessionParser.readSession — UI-state entries ignored for status', () => {
+    let parser: ClaudeSessionParser;
+    const tempFiles: string[] = [];
+
+    beforeEach(() => {
+        parser = new ClaudeSessionParser();
+    });
+
+    afterEach(() => {
+        for (const f of tempFiles) {
+            try {
+                fs.rmSync(path.dirname(f), { recursive: true, force: true });
+            } catch { /* best effort */ }
+        }
+        tempFiles.length = 0;
+    });
+
+    function writeRawSession(lines: object[]): string {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'parser-status-'));
+        const filePath = path.join(dir, 'session.jsonl');
+        fs.writeFileSync(filePath, lines.map(l => JSON.stringify(l)).join('\n'));
+        tempFiles.push(filePath);
+        return filePath;
+    }
+
+    const uiStateTypes = [
+        'attachment',
+        'permission-mode',
+        'ai-title',
+        'queued_command',
+        'tools_changed',
+        'model_changed',
+        'hook_progress',
+    ];
+
+    for (const uiType of uiStateTypes) {
+        it(`keeps lastEntryType from previous conversation turn when trailing entry is ${uiType}`, () => {
+            const file = writeRawSession([
+                { type: 'user', timestamp: '2026-05-30T06:17:57.189Z', message: { content: 'hello' } },
+                { type: uiType, timestamp: '2026-05-30T06:17:57.201Z' },
+            ]);
+
+            const session = parser.readSession(file, '/test');
+            expect(session?.lastEntryType).toBe('user');
+        });
+    }
+
+    it('keeps lastEntryType from a user turn even with multiple trailing UI-state entries', () => {
+        const file = writeRawSession([
+            { type: 'user', timestamp: '2026-05-30T06:17:57.189Z', message: { content: 'hello' } },
+            { type: 'attachment', timestamp: '2026-05-30T06:17:57.200Z', attachment: { type: 'task_reminder', content: [] } },
+            { type: 'permission-mode', timestamp: '2026-05-30T06:17:57.210Z', permissionMode: 'default' },
+            { type: 'ai-title', timestamp: '2026-05-30T06:17:57.220Z' },
+        ]);
+
+        const session = parser.readSession(file, '/test');
+        expect(session?.lastEntryType).toBe('user');
+    });
+
+    it('keeps lastEntryType from assistant turn when followed by UI-state events', () => {
+        const file = writeRawSession([
+            { type: 'user', timestamp: '2026-05-30T06:17:00.000Z', message: { content: 'go' } },
+            { type: 'assistant', timestamp: '2026-05-30T06:17:01.000Z', message: { content: [{ type: 'text', text: 'done' }] } },
+            { type: 'permission-mode', timestamp: '2026-05-30T06:17:02.000Z', permissionMode: 'default' },
+        ]);
+
+        const session = parser.readSession(file, '/test');
+        expect(session?.lastEntryType).toBe('assistant');
+    });
+});

package/src/adapters/CodexAdapter.ts

@@ -25,6 +25,7 @@ import { listAgentProcesses, enrichProcesses } from '../utils/process.js';
 import { batchGetSessionFileBirthtimes, isDirectory, safeReadFile, safeReaddir, safeStat } from '../utils/session.js';
 import type { SessionFile } from '../utils/session.js';
 import { matchProcessesToSessions, generateAgentName } from '../utils/matching.js';
+import { AgentRegistry } from '../utils/AgentRegistry.js';
 
 interface CodexEventEntry {
     timestamp?: string;
@@ -55,10 +56,12 @@ export class CodexAdapter implements AgentAdapter {
     private static readonly PROCESS_START_DAY_WINDOW_DAYS = 1;
 
     private codexSessionsDir: string;
+    private registry: AgentRegistry;
 
-    constructor() {
+    constructor(registry: AgentRegistry = AgentRegistry.default()) {
         const homeDir = process.env.HOME || process.env.USERPROFILE || '';
         this.codexSessionsDir = path.join(homeDir, '.codex', 'sessions');
+        this.registry = registry;
     }
 
     canHandle(processInfo: ProcessInfo): boolean {
@@ -72,12 +75,15 @@ export class CodexAdapter implements AgentAdapter {
         const processes = enrichProcesses(listAgentProcesses('codex'));
         if (processes.length === 0) return [];
 
-        const { sessions, contentCache } = this.discoverSessions(processes);
+        const { cachedAgents, remaining } = this.tryRegistryCache(processes);
+        if (remaining.length === 0) return cachedAgents;
+
+        const { sessions, contentCache } = this.discoverSessions(remaining);
         if (sessions.length === 0) {
-            return processes.map((p) => this.mapProcessOnlyAgent(p));
+            return [...cachedAgents, ...remaining.map((p) => this.mapProcessOnlyAgent(p))];
         }
 
-        const matches = matchProcessesToSessions(processes, sessions);
+        const matches = matchProcessesToSessions(remaining, sessions);
         const matchedPids = new Set(matches.map((m) => m.process.pid));
         const agents: AgentInfo[] = [];
 
@@ -91,13 +97,46 @@ export class CodexAdapter implements AgentAdapter {
             }
         }
 
-        for (const proc of processes) {
+        for (const proc of remaining) {
             if (!matchedPids.has(proc.pid)) {
                 agents.push(this.mapProcessOnlyAgent(proc));
             }
         }
 
-        return agents;
+        return [...cachedAgents, ...agents];
+    }
+
+    private tryRegistryCache(processes: ProcessInfo[]): {
+        cachedAgents: AgentInfo[];
+        remaining: ProcessInfo[];
+    } {
+        const cachedAgents: AgentInfo[] = [];
+        const remaining: ProcessInfo[] = [];
+        const byPid = new Map(this.registry.list().map((e) => [e.pid, e]));
+
+        for (const proc of processes) {
+            const entry = byPid.get(proc.pid);
+            if (
+                !entry ||
+                entry.type !== this.type ||
+                !entry.sessionFilePath ||
+                !fs.existsSync(entry.sessionFilePath)
+            ) {
+                remaining.push(proc);
+                continue;
+            }
+
+            const content = safeReadFile(entry.sessionFilePath);
+            const sessionData = this.parseSession(content, entry.sessionFilePath);
+            if (!sessionData) {
+                remaining.push(proc);
+                continue;
+            }
+
+            cachedAgents.push(this.mapSessionToAgent(sessionData, proc, entry.sessionFilePath));
+        }
+
+        return { cachedAgents, remaining };
     }
 
     /**

package/src/adapters/GeminiCliAdapter.ts

@@ -26,6 +26,7 @@ import { listAgentProcesses, enrichProcesses } from '../utils/process.js';
 import { isDirectory, safeReadFile, safeReaddir, safeStat } from '../utils/session.js';
 import type { SessionFile } from '../utils/session.js';
 import { matchProcessesToSessions, generateAgentName } from '../utils/matching.js';
+import { AgentRegistry } from '../utils/AgentRegistry.js';
 
 /**
  * A single Gemini CLI message content part. Mirrors the `{text?: string}`
@@ -87,10 +88,12 @@ export class GeminiCliAdapter implements AgentAdapter {
     private static readonly TMP_DIR_NAME = 'tmp';
 
     private geminiTmpDir: string;
+    private registry: AgentRegistry;
 
-    constructor() {
+    constructor(registry: AgentRegistry = AgentRegistry.default()) {
         const homeDir = process.env.HOME || process.env.USERPROFILE || '';
         this.geminiTmpDir = path.join(homeDir, '.gemini', GeminiCliAdapter.TMP_DIR_NAME);
+        this.registry = registry;
     }
 
     canHandle(processInfo: ProcessInfo): boolean {
@@ -114,12 +117,15 @@ export class GeminiCliAdapter implements AgentAdapter {
         const processes = nodeProcesses.filter((proc) => this.isGeminiExecutable(proc.command));
         if (processes.length === 0) return [];
 
-        const { sessions, contentCache } = this.discoverSessions(processes);
+        const { cachedAgents, remaining } = this.tryRegistryCache(processes);
+        if (remaining.length === 0) return cachedAgents;
+
+        const { sessions, contentCache } = this.discoverSessions(remaining);
         if (sessions.length === 0) {
-            return processes.map((p) => this.mapProcessOnlyAgent(p));
+            return [...cachedAgents, ...remaining.map((p) => this.mapProcessOnlyAgent(p))];
         }
 
-        const matches = matchProcessesToSessions(processes, sessions);
+        const matches = matchProcessesToSessions(remaining, sessions);
         const matchedPids = new Set(matches.map((m) => m.process.pid));
         const agents: AgentInfo[] = [];
 
@@ -133,13 +139,46 @@ export class GeminiCliAdapter implements AgentAdapter {
             }
         }
 
-        for (const proc of processes) {
+        for (const proc of remaining) {
             if (!matchedPids.has(proc.pid)) {
                 agents.push(this.mapProcessOnlyAgent(proc));
             }
         }
 
-        return agents;
+        return [...cachedAgents, ...agents];
+    }
+
+    private tryRegistryCache(processes: ProcessInfo[]): {
+        cachedAgents: AgentInfo[];
+        remaining: ProcessInfo[];
+    } {
+        const cachedAgents: AgentInfo[] = [];
+        const remaining: ProcessInfo[] = [];
+        const byPid = new Map(this.registry.list().map((e) => [e.pid, e]));
+
+        for (const proc of processes) {
+            const entry = byPid.get(proc.pid);
+            if (
+                !entry ||
+                entry.type !== this.type ||
+                !entry.sessionFilePath ||
+                !fs.existsSync(entry.sessionFilePath)
+            ) {
+                remaining.push(proc);
+                continue;
+            }
+
+            const content = safeReadFile(entry.sessionFilePath);
+            const sessionData = this.parseSession(content, entry.sessionFilePath);
+            if (!sessionData) {
+                remaining.push(proc);
+                continue;
+            }
+
+            cachedAgents.push(this.mapSessionToAgent(sessionData, proc, entry.sessionFilePath));
+        }
+
+        return { cachedAgents, remaining };
     }
 
     /**

package/src/index.ts

@@ -22,3 +22,9 @@ export { TtyWriter } from './terminal/TtyWriter.js';
 export { getProcessTty } from './utils/process.js';
 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 { TmuxManager } from './terminal/TmuxManager.js';
+export { AGENTS } from './utils/agents.js';
+export type { AgentConfig, StartableAgentType } from './utils/agents.js';

package/src/terminal/TmuxManager.ts

@@ -0,0 +1,118 @@
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+
+const execFileAsync = promisify(execFile);
+
+export class TmuxManager {
+    async isAvailable(): Promise<boolean> {
+        try {
+            await execFileAsync('tmux', ['-V']);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    async sessionExists(name: string): Promise<boolean> {
+        try {
+            await execFileAsync('tmux', ['has-session', '-t', name]);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    async createSession(name: string, cwd: string): Promise<void> {
+        await execFileAsync('tmux', ['new-session', '-d', '-s', name, '-c', cwd]);
+    }
+
+    async sendKeys(session: string, keys: string): Promise<void> {
+        await execFileAsync('tmux', ['send-keys', '-t', session, keys, 'Enter']);
+    }
+
+    async killSession(name: string): Promise<void> {
+        try {
+            await execFileAsync('tmux', ['kill-session', '-t', name]);
+        } catch {
+            // Already gone — ignore
+        }
+    }
+
+    /**
+     * Find the actual agent process PID inside a tmux pane.
+     *
+     * Strategy: BFS the process tree, return the deepest descendant whose
+     * `ps` command line is accepted by `matches`. The caller supplies the
+     * matcher so this method has no agent-type knowledge.
+     *
+     * This handles two real-world process shapes:
+     * - Wrapper case: shell → claude-wrapper (matches) → claude (matches, deeper)
+     *   → returns the deeper one
+     * - Subprocess case: shell → claude (matches) → MCP server child (doesn't match)
+     *   → returns claude, not the subprocess
+     *
+     * Returns null when no descendant matches yet (agent still starting); the
+     * caller's poll loop retries.
+     */
+    async findAgentPid(session: string, matches: (psCommand: string) => boolean): Promise<number | null> {
+        const panePid = await this.getPanePid(session);
+        if (panePid === null) return null;
+
+        const visited = new Set<number>();
+        const queue: number[] = [panePid];
+        let deepestMatch: number | null = null;
+
+        while (queue.length > 0) {
+            const pid = queue.shift()!;
+            if (visited.has(pid)) continue;
+            visited.add(pid);
+
+            if (pid !== panePid) {
+                const command = await this.getProcessCommand(pid);
+                if (command && matches(command)) {
+                    deepestMatch = pid;
+                }
+            }
+
+            const children = await this.pgrepChildren(pid);
+            queue.push(...children);
+        }
+
+        return deepestMatch;
+    }
+
+    private async getPanePid(session: string): Promise<number | null> {
+        try {
+            const { stdout } = await execFileAsync('tmux', [
+                'list-panes', '-t', session, '-F', '#{pane_pid}',
+            ]);
+            const panePid = parseInt(stdout.trim().split('\n')[0], 10);
+            return isNaN(panePid) ? null : panePid;
+        } catch {
+            return null;
+        }
+    }
+
+    private async pgrepChildren(pid: number): Promise<number[]> {
+        try {
+            const { stdout } = await execFileAsync('pgrep', ['-P', String(pid)]);
+            return stdout
+                .trim()
+                .split('\n')
+                .map((s) => parseInt(s, 10))
+                .filter((n) => !isNaN(n));
+        } catch {
+            return [];
+        }
+    }
+
+    private async getProcessCommand(pid: number): Promise<string | null> {
+        try {
+            const { stdout } = await execFileAsync('ps', ['-p', String(pid), '-o', 'command=']);
+            const trimmed = stdout.trim();
+            return trimmed || null;
+        } catch {
+            return null;
+        }
+    }
+}