@ai-devkit/agent-manager 0.3.0 → 0.5.0

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

@@ -0,0 +1,191 @@
+/**
+ * Tests for utils/matching.ts
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import { matchProcessesToSessions, generateAgentName } from '../../utils/matching';
+import type { ProcessInfo } from '../../adapters/AgentAdapter';
+import type { SessionFile } from '../../utils/session';
+
+function makeProcess(overrides: Partial<ProcessInfo> & { pid: number }): ProcessInfo {
+    return {
+        command: 'claude',
+        cwd: '/projects/my-app',
+        tty: 'ttys001',
+        startTime: new Date('2026-03-18T23:18:01.000Z'),
+        ...overrides,
+    };
+}
+
+function makeSession(overrides: Partial<SessionFile> & { sessionId: string }): SessionFile {
+    return {
+        filePath: `/home/.claude/projects/my-app/${overrides.sessionId}.jsonl`,
+        projectDir: '/home/.claude/projects/my-app',
+        birthtimeMs: new Date('2026-03-18T23:18:44.000Z').getTime(),
+        resolvedCwd: '/projects/my-app',
+        ...overrides,
+    };
+}
+
+describe('matchProcessesToSessions', () => {
+    it('should return empty array when no processes', () => {
+        const sessions = [makeSession({ sessionId: 's1' })];
+        expect(matchProcessesToSessions([], sessions)).toEqual([]);
+    });
+
+    it('should return empty array when no sessions', () => {
+        const processes = [makeProcess({ pid: 100 })];
+        expect(matchProcessesToSessions(processes, [])).toEqual([]);
+    });
+
+    it('should match a single process to closest session', () => {
+        const proc = makeProcess({ pid: 100, startTime: new Date('2026-03-18T23:18:01.000Z') });
+        const s1 = makeSession({ sessionId: 's1', birthtimeMs: new Date('2026-03-18T23:18:44.000Z').getTime() });
+        const s2 = makeSession({ sessionId: 's2', birthtimeMs: new Date('2026-03-18T23:20:00.000Z').getTime() });
+
+        const results = matchProcessesToSessions([proc], [s1, s2]);
+        expect(results).toHaveLength(1);
+        expect(results[0].session.sessionId).toBe('s1');
+        expect(results[0].deltaMs).toBe(43000);
+    });
+
+    it('should enforce 1:1 constraint — each process matches only one session', () => {
+        const p1 = makeProcess({ pid: 100, startTime: new Date('2026-03-18T23:18:01.000Z') });
+        const p2 = makeProcess({ pid: 200, startTime: new Date('2026-03-18T23:18:30.000Z') });
+        const s1 = makeSession({ sessionId: 's1', birthtimeMs: new Date('2026-03-18T23:18:10.000Z').getTime() });
+        const s2 = makeSession({ sessionId: 's2', birthtimeMs: new Date('2026-03-18T23:18:35.000Z').getTime() });
+
+        const results = matchProcessesToSessions([p1, p2], [s1, s2]);
+        expect(results).toHaveLength(2);
+
+        const pids = results.map(r => r.process.pid).sort();
+        const sids = results.map(r => r.session.sessionId).sort();
+        expect(pids).toEqual([100, 200]);
+        expect(sids).toEqual(['s1', 's2']);
+    });
+
+    it('should disambiguate multiple processes with same CWD by birthtime', () => {
+        const p1 = makeProcess({ pid: 100, startTime: new Date('2026-03-18T23:18:01.000Z') });
+        const p2 = makeProcess({ pid: 200, startTime: new Date('2026-03-19T08:53:11.000Z') });
+        const s1 = makeSession({ sessionId: 's1', birthtimeMs: new Date('2026-03-18T23:18:44.000Z').getTime() });
+        const s2 = makeSession({ sessionId: 's2', birthtimeMs: new Date('2026-03-19T08:55:35.000Z').getTime() });
+
+        const results = matchProcessesToSessions([p1, p2], [s1, s2]);
+        expect(results).toHaveLength(2);
+
+        const match1 = results.find(r => r.process.pid === 100);
+        const match2 = results.find(r => r.process.pid === 200);
+        expect(match1?.session.sessionId).toBe('s1');
+        expect(match2?.session.sessionId).toBe('s2');
+    });
+
+    it('should exclude processes without startTime', () => {
+        const proc = makeProcess({ pid: 100, startTime: undefined });
+        const session = makeSession({ sessionId: 's1' });
+
+        const results = matchProcessesToSessions([proc], [session]);
+        expect(results).toEqual([]);
+    });
+
+    it('should exclude processes without cwd', () => {
+        const proc = makeProcess({ pid: 100, cwd: '' });
+        const session = makeSession({ sessionId: 's1' });
+
+        const results = matchProcessesToSessions([proc], [session]);
+        expect(results).toEqual([]);
+    });
+
+    it('should not match when CWD does not match resolvedCwd', () => {
+        const proc = makeProcess({ pid: 100, cwd: '/projects/app-a' });
+        const session = makeSession({ sessionId: 's1', resolvedCwd: '/projects/app-b' });
+
+        const results = matchProcessesToSessions([proc], [session]);
+        expect(results).toEqual([]);
+    });
+
+    it('should not match when delta exceeds 3-minute tolerance', () => {
+        const proc = makeProcess({ pid: 100, startTime: new Date('2026-03-18T23:18:01.000Z') });
+        const session = makeSession({
+            sessionId: 's1',
+            birthtimeMs: new Date('2026-03-18T23:22:00.000Z').getTime(), // ~4 min later
+        });
+
+        const results = matchProcessesToSessions([proc], [session]);
+        expect(results).toEqual([]);
+    });
+
+    it('should match at exactly 3-minute boundary', () => {
+        const startTime = new Date('2026-03-18T23:18:00.000Z');
+        const proc = makeProcess({ pid: 100, startTime });
+        const session = makeSession({
+            sessionId: 's1',
+            birthtimeMs: startTime.getTime() + 180_000, // exactly 3 min
+        });
+
+        const results = matchProcessesToSessions([proc], [session]);
+        expect(results).toHaveLength(1);
+    });
+
+    it('should handle more sessions than processes', () => {
+        const proc = makeProcess({ pid: 100, startTime: new Date('2026-03-18T23:18:01.000Z') });
+        const s1 = makeSession({ sessionId: 's1', birthtimeMs: new Date('2026-03-18T23:18:44.000Z').getTime() });
+        const s2 = makeSession({ sessionId: 's2', birthtimeMs: new Date('2026-03-18T23:19:00.000Z').getTime() });
+        const s3 = makeSession({ sessionId: 's3', birthtimeMs: new Date('2026-03-18T23:19:30.000Z').getTime() });
+
+        const results = matchProcessesToSessions([proc], [s1, s2, s3]);
+        expect(results).toHaveLength(1);
+        expect(results[0].session.sessionId).toBe('s1'); // closest
+    });
+
+    it('should handle more processes than sessions', () => {
+        const p1 = makeProcess({ pid: 100, startTime: new Date('2026-03-18T23:18:01.000Z') });
+        const p2 = makeProcess({ pid: 200, startTime: new Date('2026-03-18T23:20:01.000Z') });
+        const s1 = makeSession({ sessionId: 's1', birthtimeMs: new Date('2026-03-18T23:18:44.000Z').getTime() });
+
+        const results = matchProcessesToSessions([p1, p2], [s1]);
+        expect(results).toHaveLength(1);
+        expect(results[0].process.pid).toBe(100); // closest
+    });
+
+    it('should skip sessions with empty resolvedCwd', () => {
+        const proc = makeProcess({ pid: 100 });
+        const session = makeSession({ sessionId: 's1', resolvedCwd: '' });
+
+        const results = matchProcessesToSessions([proc], [session]);
+        expect(results).toEqual([]);
+    });
+
+    it('should prefer best match when greedy ordering matters', () => {
+        // p1 is 10s from s2, p2 is 5s from s2 — p2 should win s2, p1 gets s1
+        const p1 = makeProcess({ pid: 100, startTime: new Date('2026-03-18T23:18:00.000Z') });
+        const p2 = makeProcess({ pid: 200, startTime: new Date('2026-03-18T23:18:25.000Z') });
+        const s1 = makeSession({ sessionId: 's1', birthtimeMs: new Date('2026-03-18T23:18:08.000Z').getTime() });
+        const s2 = makeSession({ sessionId: 's2', birthtimeMs: new Date('2026-03-18T23:18:30.000Z').getTime() });
+
+        const results = matchProcessesToSessions([p1, p2], [s1, s2]);
+        expect(results).toHaveLength(2);
+
+        const match1 = results.find(r => r.process.pid === 200);
+        const match2 = results.find(r => r.process.pid === 100);
+        expect(match1?.session.sessionId).toBe('s2'); // 5s delta
+        expect(match2?.session.sessionId).toBe('s1'); // 8s delta
+    });
+});
+
+describe('generateAgentName', () => {
+    it('should return folderName (pid)', () => {
+        expect(generateAgentName('/projects/my-app', 12345)).toBe('my-app (12345)');
+    });
+
+    it('should handle root path', () => {
+        expect(generateAgentName('/', 100)).toBe('unknown (100)');
+    });
+
+    it('should handle empty cwd', () => {
+        expect(generateAgentName('', 100)).toBe('unknown (100)');
+    });
+
+    it('should handle nested paths', () => {
+        expect(generateAgentName('/home/user/projects/ai-devkit', 78070)).toBe('ai-devkit (78070)');
+    });
+});

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

@@ -0,0 +1,202 @@
+/**
+ * Tests for new functions in utils/process.ts
+ */
+
+import { describe, it, expect, jest, beforeEach } from '@jest/globals';
+import { execSync } from 'child_process';
+import {
+    listAgentProcesses,
+    batchGetProcessCwds,
+    batchGetProcessStartTimes,
+    enrichProcesses,
+} from '../../utils/process';
+
+jest.mock('child_process', () => ({
+    execSync: jest.fn(),
+}));
+
+const mockedExecSync = execSync as jest.MockedFunction<typeof execSync>;
+
+describe('listAgentProcesses', () => {
+    beforeEach(() => {
+        mockedExecSync.mockReset();
+    });
+
+    it('should parse ps aux | grep output and post-filter by executable name', () => {
+        mockedExecSync.mockReturnValue(
+            'user  78070  1.0  0.5 485636016 245952 s018  S+   11:18PM   1:55.14 claude\n' +
+            'user  55106  0.1  0.4 485620368  72496 s015  S+    9Mar26   8:06.36 claude\n',
+        );
+
+        const processes = listAgentProcesses('claude');
+        expect(processes).toHaveLength(2);
+        expect(processes[0].pid).toBe(78070);
+        expect(processes[0].command).toBe('claude');
+        expect(processes[0].tty).toBe('s018');
+        expect(processes[0].cwd).toBe(''); // not populated yet
+        expect(processes[1].pid).toBe(55106);
+    });
+
+    it('should filter out non-matching executables', () => {
+        mockedExecSync.mockReturnValue(
+            'user  100  0.0  0.0 0 0 s001  S  1:00PM  0:00 claude\n' +
+            'user  200  0.0  0.0 0 0 s002  S  1:00PM  0:00 claude-helper --pid 100\n' +
+            'user  300  0.0  0.0 0 0 s003  S  1:00PM  0:00 /usr/bin/claude\n',
+        );
+
+        const processes = listAgentProcesses('claude');
+        expect(processes).toHaveLength(2);
+        expect(processes.map(p => p.pid)).toEqual([100, 300]);
+    });
+
+    it('should return empty array on command failure', () => {
+        mockedExecSync.mockImplementation(() => { throw new Error('fail'); });
+        expect(listAgentProcesses('claude')).toEqual([]);
+    });
+
+    it('should handle empty output', () => {
+        mockedExecSync.mockReturnValue('');
+        expect(listAgentProcesses('claude')).toEqual([]);
+    });
+
+    it('should reject empty pattern', () => {
+        expect(listAgentProcesses('')).toEqual([]);
+        expect(mockedExecSync).not.toHaveBeenCalled();
+    });
+
+    it('should reject patterns with shell injection characters', () => {
+        expect(listAgentProcesses('claude; rm -rf /')).toEqual([]);
+        expect(listAgentProcesses("claude' || true")).toEqual([]);
+        expect(listAgentProcesses('$(whoami)')).toEqual([]);
+        expect(mockedExecSync).not.toHaveBeenCalled();
+    });
+
+    it('should accept valid patterns with dashes and underscores', () => {
+        mockedExecSync.mockReturnValue('');
+        listAgentProcesses('claude-code');
+        expect(mockedExecSync).toHaveBeenCalled();
+
+        mockedExecSync.mockReset();
+        mockedExecSync.mockReturnValue('');
+        listAgentProcesses('my_agent');
+        expect(mockedExecSync).toHaveBeenCalled();
+    });
+});
+
+describe('batchGetProcessCwds', () => {
+    beforeEach(() => {
+        mockedExecSync.mockReset();
+    });
+
+    it('should parse batched lsof output', () => {
+        mockedExecSync.mockReturnValue(
+            'p78070\nn/Users/user/ai-devkit\np55106\nn/Users/user/other-project\n',
+        );
+
+        const cwds = batchGetProcessCwds([78070, 55106]);
+        expect(cwds.get(78070)).toBe('/Users/user/ai-devkit');
+        expect(cwds.get(55106)).toBe('/Users/user/other-project');
+    });
+
+    it('should return empty map for empty pids', () => {
+        expect(batchGetProcessCwds([])).toEqual(new Map());
+    });
+
+    it('should return partial results when lsof succeeds for some PIDs', () => {
+        // lsof might not return entries for dead processes
+        mockedExecSync.mockReturnValue(
+            'p78070\nn/Users/user/ai-devkit\n',
+        );
+
+        const cwds = batchGetProcessCwds([78070, 99999]);
+        expect(cwds.size).toBe(1);
+        expect(cwds.get(78070)).toBe('/Users/user/ai-devkit');
+    });
+
+    it('should return empty map on total failure', () => {
+        mockedExecSync.mockImplementation(() => { throw new Error('fail'); });
+        const cwds = batchGetProcessCwds([78070]);
+        // Falls through to pwdx fallback which also fails
+        expect(cwds.size).toBe(0);
+    });
+});
+
+describe('batchGetProcessStartTimes', () => {
+    beforeEach(() => {
+        mockedExecSync.mockReset();
+    });
+
+    it('should parse ps lstart output', () => {
+        mockedExecSync.mockReturnValue(
+            ' 78070 Wed Mar 18 23:18:01 2026\n' +
+            ' 55106 Mon Mar  9 21:41:42 2026\n',
+        );
+
+        const times = batchGetProcessStartTimes([78070, 55106]);
+        expect(times.size).toBe(2);
+        expect(times.get(78070)?.getFullYear()).toBe(2026);
+        expect(times.get(55106)?.getMonth()).toBe(2); // March = 2
+    });
+
+    it('should return empty map for empty pids', () => {
+        expect(batchGetProcessStartTimes([])).toEqual(new Map());
+    });
+
+    it('should skip lines with unparseable dates', () => {
+        mockedExecSync.mockReturnValue(
+            ' 78070 Wed Mar 18 23:18:01 2026\n' +
+            ' 99999 INVALID_DATE\n',
+        );
+
+        const times = batchGetProcessStartTimes([78070, 99999]);
+        expect(times.size).toBe(1);
+        expect(times.has(78070)).toBe(true);
+    });
+
+    it('should return empty map on failure', () => {
+        mockedExecSync.mockImplementation(() => { throw new Error('fail'); });
+        expect(batchGetProcessStartTimes([78070])).toEqual(new Map());
+    });
+});
+
+describe('enrichProcesses', () => {
+    beforeEach(() => {
+        mockedExecSync.mockReset();
+    });
+
+    it('should populate cwd and startTime on processes', () => {
+        // First call: batchGetProcessCwds (lsof)
+        // Second call: batchGetProcessStartTimes (ps lstart)
+        mockedExecSync
+            .mockReturnValueOnce('p100\nn/projects/app\n')
+            .mockReturnValueOnce(' 100 Wed Mar 18 23:18:01 2026\n');
+
+        const processes = [
+            { pid: 100, command: 'claude', cwd: '', tty: 's001' },
+        ];
+
+        const enriched = enrichProcesses(processes);
+        expect(enriched[0].cwd).toBe('/projects/app');
+        expect(enriched[0].startTime).toBeDefined();
+    });
+
+    it('should return empty array for empty input', () => {
+        expect(enrichProcesses([])).toEqual([]);
+        expect(mockedExecSync).not.toHaveBeenCalled();
+    });
+
+    it('should handle partial failures', () => {
+        // lsof succeeds, ps lstart fails
+        mockedExecSync
+            .mockReturnValueOnce('p100\nn/projects/app\n')
+            .mockImplementationOnce(() => { throw new Error('fail'); });
+
+        const processes = [
+            { pid: 100, command: 'claude', cwd: '', tty: 's001' },
+        ];
+
+        const enriched = enrichProcesses(processes);
+        expect(enriched[0].cwd).toBe('/projects/app');
+        expect(enriched[0].startTime).toBeUndefined();
+    });
+});

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

@@ -0,0 +1,117 @@
+/**
+ * Tests for utils/session.ts
+ */
+
+import { describe, it, expect, jest, beforeEach } from '@jest/globals';
+import { execSync } from 'child_process';
+import { batchGetSessionFileBirthtimes } from '../../utils/session';
+
+jest.mock('child_process', () => ({
+    execSync: jest.fn(),
+}));
+
+const mockedExecSync = execSync as jest.MockedFunction<typeof execSync>;
+
+describe('batchGetSessionFileBirthtimes', () => {
+    beforeEach(() => {
+        mockedExecSync.mockReset();
+    });
+
+    it('should parse stat output correctly', () => {
+        mockedExecSync.mockReturnValue(
+            '1710800324 /home/.claude/projects/my-app/abc123.jsonl\n' +
+            '1710800500 /home/.claude/projects/my-app/def456.jsonl\n',
+        );
+
+        const results = batchGetSessionFileBirthtimes(['/home/.claude/projects/my-app']);
+
+        expect(results).toHaveLength(2);
+        expect(results[0]).toEqual({
+            sessionId: 'abc123',
+            filePath: '/home/.claude/projects/my-app/abc123.jsonl',
+            projectDir: '/home/.claude/projects/my-app',
+            birthtimeMs: 1710800324000,
+            resolvedCwd: '',
+        });
+        expect(results[1].sessionId).toBe('def456');
+        expect(results[1].birthtimeMs).toBe(1710800500000);
+    });
+
+    it('should return empty array for empty dirs list', () => {
+        expect(batchGetSessionFileBirthtimes([])).toEqual([]);
+        expect(mockedExecSync).not.toHaveBeenCalled();
+    });
+
+    it('should return empty array on command failure', () => {
+        mockedExecSync.mockImplementation(() => {
+            throw new Error('Command failed');
+        });
+
+        expect(batchGetSessionFileBirthtimes(['/some/dir'])).toEqual([]);
+    });
+
+    it('should skip lines with invalid epoch (0 or negative)', () => {
+        mockedExecSync.mockReturnValue(
+            '0 /dir/bad.jsonl\n' +
+            '-1 /dir/negative.jsonl\n' +
+            '1710800324 /dir/good.jsonl\n',
+        );
+
+        const results = batchGetSessionFileBirthtimes(['/dir']);
+        expect(results).toHaveLength(1);
+        expect(results[0].sessionId).toBe('good');
+    });
+
+    it('should skip non-jsonl files in output', () => {
+        mockedExecSync.mockReturnValue(
+            '1710800324 /dir/sessions-index.json\n' +
+            '1710800500 /dir/abc123.jsonl\n',
+        );
+
+        const results = batchGetSessionFileBirthtimes(['/dir']);
+        expect(results).toHaveLength(1);
+        expect(results[0].sessionId).toBe('abc123');
+    });
+
+    it('should handle empty output', () => {
+        mockedExecSync.mockReturnValue('');
+        expect(batchGetSessionFileBirthtimes(['/dir'])).toEqual([]);
+    });
+
+    it('should handle UUID session IDs', () => {
+        mockedExecSync.mockReturnValue(
+            '1710800324 /dir/068e7b1f-cff5-4c94-bf69-b9acd32d765c.jsonl\n',
+        );
+
+        const results = batchGetSessionFileBirthtimes(['/dir']);
+        expect(results).toHaveLength(1);
+        expect(results[0].sessionId).toBe('068e7b1f-cff5-4c94-bf69-b9acd32d765c');
+    });
+
+    it('should leave resolvedCwd empty', () => {
+        mockedExecSync.mockReturnValue('1710800324 /dir/abc.jsonl\n');
+
+        const results = batchGetSessionFileBirthtimes(['/dir']);
+        expect(results[0].resolvedCwd).toBe('');
+    });
+
+    it('should combine multiple directories into a single stat call', () => {
+        mockedExecSync.mockReturnValue(
+            '1710800324 /projects/app-a/sess1.jsonl\n' +
+            '1710800400 /projects/app-b/sess2.jsonl\n' +
+            '1710800500 /projects/app-a/sess3.jsonl\n',
+        );
+
+        const results = batchGetSessionFileBirthtimes(['/projects/app-a', '/projects/app-b']);
+
+        expect(mockedExecSync).toHaveBeenCalledTimes(1);
+        const cmd = mockedExecSync.mock.calls[0][0] as string;
+        expect(cmd).toContain('"/projects/app-a"/*.jsonl');
+        expect(cmd).toContain('"/projects/app-b"/*.jsonl');
+
+        expect(results).toHaveLength(3);
+        expect(results[0].projectDir).toBe('/projects/app-a');
+        expect(results[1].projectDir).toBe('/projects/app-b');
+        expect(results[2].projectDir).toBe('/projects/app-a');
+    });
+});

package/src/adapters/AgentAdapter.ts

@@ -68,6 +68,9 @@ export interface ProcessInfo {
 
     /** Terminal TTY (e.g., "ttys030") */
     tty: string;
+
+    /** Process start time, populated by enrichProcesses */
+    startTime?: Date;
 }
 
 /**