@ai-devkit/agent-manager 0.22.0 → 0.24.0

package/src/__tests__/terminal/TerminalFocusManager.test.ts

@@ -2,6 +2,7 @@ import { execFile } from 'child_process';
 import type { MockedFunction } from 'vitest';
 
 import { TerminalFocusManager, TerminalType } from '../../terminal/TerminalFocusManager.js';
+import type { TerminalLocation } from '../../terminal/TerminalFocusManager.js';
 import { getProcessTty } from '../../utils/process.js';
 
 vi.mock('child_process', () => ({
@@ -62,6 +63,192 @@ describe('TerminalFocusManager', () => {
         );
     });
 
+    describe('WezTerm', () => {
+        const listArgs = ['cli', 'list', '--format', 'json'];
+
+        it('finds the WezTerm pane whose tty_name matches the agent tty', async () => {
+            setExecFileHandler((cmd, args) => {
+                if (cmd === 'tmux') return new Error('tmux not running');
+                if (cmd === 'wezterm' && args.join(' ') === listArgs.join(' ')) {
+                    return JSON.stringify([
+                        { pane_id: 3, tty_name: '/dev/ttys099', cwd: '/x' },
+                        { pane_id: 7, tty_name: '/dev/ttys000', cwd: '/y' },
+                    ]);
+                }
+                return '';
+            });
+
+            const location = await new TerminalFocusManager().findTerminal(123);
+
+            expect(location).toEqual({
+                type: TerminalType.WEZTERM,
+                identifier: '7',
+                tty: '/dev/ttys000',
+            });
+        });
+
+        it('skips the macOS AppleScript probes when WezTerm matches', async () => {
+            setExecFileHandler((cmd) => {
+                if (cmd === 'tmux') return new Error('tmux not running');
+                if (cmd === 'wezterm') {
+                    return JSON.stringify([{ pane_id: 7, tty_name: '/dev/ttys000' }]);
+                }
+                return '';
+            });
+
+            await new TerminalFocusManager().findTerminal(123);
+
+            expect(mockedExecFile).not.toHaveBeenCalledWith(
+                'osascript',
+                expect.any(Array),
+                expect.any(Function),
+            );
+        });
+
+        it('returns UNKNOWN when WezTerm is installed but no pane matches the tty', async () => {
+            setExecFileHandler((cmd) => {
+                if (cmd === 'tmux') return new Error('tmux not running');
+                if (cmd === 'wezterm') {
+                    return JSON.stringify([{ pane_id: 7, tty_name: '/dev/ttys099' }]);
+                }
+                return '';
+            });
+
+            const location = await new TerminalFocusManager().findTerminal(123);
+
+            expect(location?.type).toBe(TerminalType.UNKNOWN);
+        });
+
+        it('returns UNKNOWN (without throwing) on malformed JSON from wezterm', async () => {
+            setExecFileHandler((cmd) => {
+                if (cmd === 'tmux') return new Error('tmux not running');
+                if (cmd === 'wezterm') return 'not-json{';
+                return '';
+            });
+
+            const location = await new TerminalFocusManager().findTerminal(123);
+
+            expect(location?.type).toBe(TerminalType.UNKNOWN);
+        });
+
+        it('returns UNKNOWN when the wezterm binary is missing', async () => {
+            setExecFileHandler((cmd) => {
+                if (cmd === 'tmux') return new Error('tmux not running');
+                if (cmd === 'wezterm') return new Error('spawn wezterm ENOENT');
+                return '';
+            });
+
+            const location = await new TerminalFocusManager().findTerminal(123);
+
+            expect(location?.type).toBe(TerminalType.UNKNOWN);
+        });
+
+        it('prefers tmux over WezTerm (tmux-inside-WezTerm resolves to tmux)', async () => {
+            setExecFileHandler((cmd) => {
+                if (cmd === 'tmux') {
+                    return `/dev/ttys000|my:0.1`;
+                }
+                if (cmd === 'wezterm') {
+                    return JSON.stringify([{ pane_id: 7, tty: '/dev/ttys000' }]);
+                }
+                return '';
+            });
+
+            const location = await new TerminalFocusManager().findTerminal(123);
+
+            expect(location).toEqual({
+                type: TerminalType.TMUX,
+                identifier: 'my:0.1',
+                tty: '/dev/ttys000',
+            });
+            // WezTerm must not even be queried when tmux already matched.
+            expect(mockedExecFile).not.toHaveBeenCalledWith(
+                'wezterm',
+                expect.any(Array),
+                expect.any(Function),
+            );
+        });
+    });
+
+    describe('focusTerminal for WezTerm', () => {
+        const location: TerminalLocation = {
+            type: TerminalType.WEZTERM,
+            identifier: '7',
+            tty: '/dev/ttys000',
+        };
+
+        it('focuses the pane via wezterm cli activate-pane --pane-id', async () => {
+            setExecFileHandler((cmd, args) => {
+                if (cmd === 'wezterm' && args.join(' ') === 'cli activate-pane --pane-id 7') {
+                    return '';
+                }
+                return '';
+            });
+
+            const ok = await new TerminalFocusManager().focusTerminal(location);
+
+            expect(ok).toBe(true);
+            expect(mockedExecFile).toHaveBeenCalledWith(
+                'wezterm',
+                ['cli', 'activate-pane', '--pane-id', '7'],
+                expect.any(Function),
+            );
+        });
+
+        it('returns false (without throwing) when focus fails', async () => {
+            setExecFileHandler((cmd) => {
+                if (cmd === 'wezterm') return new Error('boom');
+                return '';
+            });
+
+            const ok = await new TerminalFocusManager().focusTerminal(location);
+
+            expect(ok).toBe(false);
+        });
+    });
+
+    describe('debug tracing', () => {
+        it('emits the matching decision path via the debug logger', async () => {
+            const debug = vi.fn();
+            setExecFileHandler((cmd, args) => {
+                if (cmd === 'tmux') return new Error('tmux not running');
+                if (cmd === 'wezterm' && args.join(' ').includes('cli list')) {
+                    return JSON.stringify([{ pane_id: 7, tty_name: '/dev/ttys000' }]);
+                }
+                return '';
+            });
+
+            const location = await new TerminalFocusManager(debug).findTerminal(123);
+
+            expect(location?.type).toBe(TerminalType.WEZTERM);
+            const messages = debug.mock.calls.map((call) => call[0] as string);
+            expect(messages.some((m) => /pid=123/.test(m))).toBe(true);
+            expect(messages.some((m) => /tmux.*no match|tmux: no/i.test(m))).toBe(true);
+            expect(messages.some((m) => /wezterm/i.test(m))).toBe(true);
+        });
+
+        it('emits the focus decision path via the debug logger', async () => {
+            const debug = vi.fn();
+            setExecFileHandler((cmd, args) => {
+                if (cmd === 'wezterm' && args.join(' ') === 'cli activate-pane --pane-id 7') {
+                    return '';
+                }
+                return '';
+            });
+
+            const ok = await new TerminalFocusManager(debug).focusTerminal({
+                type: TerminalType.WEZTERM,
+                identifier: '7',
+                tty: '/dev/ttys000',
+            });
+
+            expect(ok).toBe(true);
+            const messages = debug.mock.calls.map((call) => call[0] as string);
+            expect(messages.some((m) => /focusing wezterm/i.test(m))).toBe(true);
+            expect(messages.some((m) => /succeeded/i.test(m))).toBe(true);
+        });
+    });
+
     it('finds Terminal.app when the process is listed by app bundle path', async () => {
         setExecFileHandler((cmd, args) => {
             if (cmd === 'tmux') return new Error('tmux not running');

package/src/__tests__/terminal/TtyWriter.test.ts

@@ -19,6 +19,7 @@ function mockExecFileSuccess(stdout = '') {
     mockedExecFile.mockImplementation((...args: unknown[]) => {
         const cb = args[args.length - 1] as (err: Error | null, result: { stdout: string }, stderr: string) => void;
         cb(null, { stdout }, '');
+        return { stdin: { end: vi.fn() } };
     });
 }
 
@@ -41,22 +42,36 @@ describe('TtyWriter', () => {
             tty: '/dev/ttys030',
         };
 
-        it('sends message and Enter as separate tmux send-keys calls', async () => {
+        it('pastes message in bracketed paste mode and sends Enter separately', async () => {
             mockExecFileSuccess();
+            const message = 'line 1\nline 2\n';
 
-            await TtyWriter.send(location, 'continue');
+            await TtyWriter.send(location, message);
 
-            expect(mockedExecFile).toHaveBeenCalledWith(
+            const loadArgs = mockedExecFile.mock.calls[0]?.[1] as string[];
+            const bufferName = loadArgs[2];
+            expect(bufferName).toMatch(/^ai-devkit-send-/);
+            expect(mockedExecFile).toHaveBeenNthCalledWith(
+                1,
                 'tmux',
-                ['send-keys', '-t', 'main:0.1', '-l', 'continue'],
+                ['load-buffer', '-b', bufferName, '-'],
                 expect.any(Function),
             );
-            expect(mockedExecFile).toHaveBeenCalledWith(
+            expect(mockedExecFile.mock.results[0]?.value.stdin.end)
+                .toHaveBeenCalledWith(message);
+            expect(mockedExecFile).toHaveBeenNthCalledWith(
+                2,
+                'tmux',
+                ['paste-buffer', '-t', 'main:0.1', '-b', bufferName, '-p', '-d'],
+                expect.any(Function),
+            );
+            expect(mockedExecFile).toHaveBeenNthCalledWith(
+                3,
                 'tmux',
                 ['send-keys', '-t', 'main:0.1', 'Enter'],
                 expect.any(Function),
             );
-            expect(mockedExecFile).toHaveBeenCalledTimes(2);
+            expect(mockedExecFile).toHaveBeenCalledTimes(3);
         });
 
         it('throws on tmux failure', async () => {
@@ -186,6 +201,96 @@ describe('TtyWriter', () => {
         });
     });
 
+    describe('WezTerm', () => {
+        const location: TerminalLocation = {
+            type: TerminalType.WEZTERM,
+            identifier: '7',
+            tty: '/dev/ttys030',
+        };
+
+        it('sends the message via stdin and Enter as a separate send-text call', async () => {
+            mockExecFileSuccess();
+
+            await TtyWriter.send(location, 'continue');
+
+            // Step 1: message body via stdin, not argv, so prompt contents are
+            // not exposed through process listings.
+            expect(mockedExecFile).toHaveBeenCalledWith(
+                'wezterm',
+                ['cli', 'send-text', '--pane-id', '7'],
+                expect.any(Function),
+            );
+            expect(mockedExecFile.mock.results[0]?.value.stdin.end)
+                .toHaveBeenCalledWith('continue');
+            // Step 2: Enter as a single carriage return (0x0d) with --no-paste,
+            // so the CR is delivered literally (not wrapped in paste brackets).
+            // execFile passes the actual CR byte (JS '\x0d'); the equivalent
+            // shell command is:
+            //   wezterm cli send-text --pane-id <id> --no-paste $'\x0d'
+            expect(mockedExecFile).toHaveBeenCalledWith(
+                'wezterm',
+                ['cli', 'send-text', '--pane-id', '7', '--no-paste', '\x0d'],
+                expect.any(Function),
+            );
+            expect(mockedExecFile).toHaveBeenCalledTimes(2);
+        });
+
+        it('passes the Enter byte as the carriage return (0x0d), not newline', async () => {
+            mockExecFileSuccess();
+
+            await TtyWriter.send(location, 'continue');
+
+            // The Enter call is the second invocation; its last argv element is
+            // a single byte equal to char code 13 (0x0d).
+            const enterCall = mockedExecFile.mock.calls[1];
+            const enterArgs = enterCall[1] as string[];
+            const enterByte = enterArgs[enterArgs.length - 1];
+            expect(enterByte).toHaveLength(1);
+            expect(enterByte.charCodeAt(0)).toBe(0x0d);
+            expect(enterArgs).toContain('--no-paste');
+        });
+
+        it('keeps the whole message out of argv and writes it verbatim to stdin', async () => {
+            mockExecFileSuccess();
+            const hostile = 'echo pwned; $(rm -rf /) `whoami` | cat\nline2';
+
+            await TtyWriter.send(location, hostile);
+
+            // The message is written verbatim to stdin, not built into a shell
+            // string or exposed as a process argument.
+            const textCall = mockedExecFile.mock.calls[0];
+            const textArgs = textCall[1] as string[];
+            expect(textArgs).toEqual(
+                ['cli', 'send-text', '--pane-id', '7'],
+            );
+            expect(textCall[2]).toBeTypeOf('function');
+            expect(mockedExecFile.mock.results[0]?.value.stdin.end)
+                .toHaveBeenCalledWith(hostile);
+        });
+
+        it('uses the pane id from location.identifier', async () => {
+            mockExecFileSuccess();
+            const pane42 = { ...location, identifier: '42' };
+
+            await TtyWriter.send(pane42, 'hi');
+
+            expect(mockedExecFile).toHaveBeenCalledWith(
+                'wezterm',
+                ['cli', 'send-text', '--pane-id', '42'],
+                expect.any(Function),
+            );
+            expect(mockedExecFile.mock.results[0]?.value.stdin.end)
+                .toHaveBeenCalledWith('hi');
+        });
+
+        it('throws when the text send fails', async () => {
+            mockExecFileError('wezterm send-text failed');
+
+            await expect(TtyWriter.send(location, 'hello'))
+                .rejects.toThrow('wezterm send-text failed');
+        });
+    });
+
     describe('unsupported terminal', () => {
         it('throws for unknown terminal type', async () => {
             const location: TerminalLocation = {
@@ -198,4 +303,148 @@ describe('TtyWriter', () => {
                 .rejects.toThrow('Cannot send input: unsupported terminal type');
         });
     });
+
+    describe('sendKey — tmux', () => {
+        const location: TerminalLocation = {
+            type: TerminalType.TMUX,
+            identifier: 'main:0.1',
+            tty: '/dev/ttys030',
+        };
+
+        it('sends key via tmux send-keys directly (no paste buffer, no auto-Enter)', async () => {
+            mockExecFileSuccess();
+
+            await TtyWriter.sendKey(location, '1');
+
+            expect(mockedExecFile).toHaveBeenCalledTimes(1);
+            expect(mockedExecFile).toHaveBeenCalledWith(
+                'tmux',
+                ['send-keys', '-t', 'main:0.1', '1'],
+                expect.any(Function),
+            );
+        });
+
+        it('passes through named keys like Enter', async () => {
+            mockExecFileSuccess();
+            await TtyWriter.sendKey(location, 'Enter');
+            expect(mockedExecFile).toHaveBeenCalledWith(
+                'tmux',
+                ['send-keys', '-t', 'main:0.1', 'Enter'],
+                expect.any(Function),
+            );
+        });
+
+        it('translates Esc byte (\\x1b) to the named "Escape" key', async () => {
+            mockExecFileSuccess();
+            await TtyWriter.sendKey(location, '\x1b');
+            expect(mockedExecFile).toHaveBeenCalledWith(
+                'tmux',
+                ['send-keys', '-t', 'main:0.1', 'Escape'],
+                expect.any(Function),
+            );
+        });
+    });
+
+    describe('sendKey — WezTerm', () => {
+        const location: TerminalLocation = {
+            type: TerminalType.WEZTERM,
+            identifier: '7',
+            tty: '/dev/ttys030',
+        };
+
+        it('uses wezterm cli send-text --no-paste to deliver a raw key', async () => {
+            mockExecFileSuccess();
+
+            await TtyWriter.sendKey(location, '1');
+
+            expect(mockedExecFile).toHaveBeenCalledTimes(1);
+            expect(mockedExecFile).toHaveBeenCalledWith(
+                'wezterm',
+                ['cli', 'send-text', '--pane-id', '7', '--no-paste', '1'],
+                expect.any(Function),
+            );
+        });
+    });
+
+    describe('sendKey — iTerm2', () => {
+        const location: TerminalLocation = {
+            type: TerminalType.ITERM2,
+            identifier: '/dev/ttys030',
+            tty: '/dev/ttys030',
+        };
+
+        it('uses System Events keystroke after activating the iTerm2 session', async () => {
+            mockExecFileSuccess('ok');
+
+            await TtyWriter.sendKey(location, '2');
+
+            const args = (mockedExecFile.mock.calls[0] as unknown[])[1] as string[];
+            const script = args[1];
+            expect(script).toContain('tell application "iTerm"');
+            expect(script).toContain('tell application "System Events" to keystroke "2"');
+            expect(mockedExecFile).toHaveBeenCalledTimes(1);
+        });
+
+        it('translates Esc byte (\\x1b) to AppleScript `key code 53`', async () => {
+            mockExecFileSuccess('ok');
+            await TtyWriter.sendKey(location, '\x1b');
+            const args = (mockedExecFile.mock.calls[0] as unknown[])[1] as string[];
+            const script = args[1];
+            expect(script).toContain('tell application "System Events" to key code 53');
+            expect(script).not.toContain('keystroke');
+        });
+
+        it('throws when session not found', async () => {
+            mockExecFileSuccess('not_found');
+            await expect(TtyWriter.sendKey(location, '1'))
+                .rejects.toThrow('iTerm2 session not found');
+        });
+    });
+
+    describe('sendKey — Terminal.app', () => {
+        const location: TerminalLocation = {
+            type: TerminalType.TERMINAL_APP,
+            identifier: '/dev/ttys030',
+            tty: '/dev/ttys030',
+        };
+
+        it('uses System Events keystroke after selecting the Terminal.app tab', async () => {
+            mockExecFileSuccess('ok');
+
+            await TtyWriter.sendKey(location, '3');
+
+            const args = (mockedExecFile.mock.calls[0] as unknown[])[1] as string[];
+            const script = args[1];
+            expect(script).toContain('tell application "Terminal"');
+            expect(script).toContain('tell application "System Events" to keystroke "3"');
+            expect(mockedExecFile).toHaveBeenCalledTimes(1);
+        });
+
+        it('translates Esc byte (\\x1b) to AppleScript `key code 53`', async () => {
+            mockExecFileSuccess('ok');
+            await TtyWriter.sendKey(location, '\x1b');
+            const args = (mockedExecFile.mock.calls[0] as unknown[])[1] as string[];
+            const script = args[1];
+            expect(script).toContain('tell application "System Events" to key code 53');
+            expect(script).not.toContain('keystroke');
+        });
+
+        it('throws when tab not found', async () => {
+            mockExecFileSuccess('not_found');
+            await expect(TtyWriter.sendKey(location, '1'))
+                .rejects.toThrow('Terminal.app tab not found');
+        });
+    });
+
+    describe('sendKey — unsupported terminal', () => {
+        it('throws for unknown terminal type', async () => {
+            const location: TerminalLocation = {
+                type: TerminalType.UNKNOWN,
+                identifier: '',
+                tty: '/dev/ttys030',
+            };
+            await expect(TtyWriter.sendKey(location, '1'))
+                .rejects.toThrow('Cannot send key: unsupported terminal type');
+        });
+    });
 });

package/src/__tests__/utils/agent-requests.test.ts

@@ -0,0 +1,74 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { getAgentRequestPath, readLatestAgentRequest, writeAgentRequest, type AgentRequest } from '../../utils/agent-requests.js';
+
+describe('agent-requests', () => {
+    let homeDir: string;
+
+    beforeEach(() => {
+        homeDir = mkdtempSync(join(tmpdir(), 'agent-requests-test-'));
+    });
+
+    afterEach(() => {
+        rmSync(homeDir, { recursive: true, force: true });
+    });
+
+    describe('getAgentRequestPath', () => {
+        it('returns ~/.ai-devkit/agent-requests/<sessionId>.json', () => {
+            expect(getAgentRequestPath(homeDir, 'abc-123')).toBe(
+                join(homeDir, '.ai-devkit', 'agent-requests', 'abc-123.json'),
+            );
+        });
+    });
+
+    describe('writeAgentRequest', () => {
+        it('creates the directory and file on first write', () => {
+            const entry: AgentRequest = {
+                sessionId: 'sess-1',
+                toolName: 'Bash',
+                toolInput: { command: 'ls /tmp' },
+                timestamp: '2026-06-29T00:00:00.000Z',
+            };
+            writeAgentRequest(homeDir, entry);
+
+            expect(readLatestAgentRequest(homeDir, 'sess-1')).toEqual(entry);
+        });
+
+        it('overwrites an existing entry on subsequent writes', () => {
+            const first: AgentRequest = { sessionId: 'sess-2', toolName: 'Bash', toolInput: { command: 'echo first' }, timestamp: '2026-06-29T00:00:01.000Z' };
+            const second: AgentRequest = { sessionId: 'sess-2', toolName: 'Bash', toolInput: { command: 'echo second' }, timestamp: '2026-06-29T00:00:02.000Z' };
+
+            writeAgentRequest(homeDir, first);
+            writeAgentRequest(homeDir, second);
+
+            expect(readLatestAgentRequest(homeDir, 'sess-2')).toEqual(second);
+        });
+    });
+
+    describe('readLatestAgentRequest', () => {
+        it('returns null when no file exists for the session', () => {
+            expect(readLatestAgentRequest(homeDir, 'no-such-session')).toBeNull();
+        });
+
+        it('returns null when the file contains malformed JSON', () => {
+            const entry: AgentRequest = { sessionId: 'bad', toolName: 'Bash', toolInput: {}, timestamp: '2026-06-29T00:00:00.000Z' };
+            writeAgentRequest(homeDir, entry);
+            writeFileSync(getAgentRequestPath(homeDir, 'bad'), 'NOT JSON{{{', 'utf-8');
+
+            expect(readLatestAgentRequest(homeDir, 'bad')).toBeNull();
+        });
+
+        it('returns the stored entry when the file is valid', () => {
+            const entry: AgentRequest = {
+                sessionId: 'good',
+                toolName: 'AskUserQuestion',
+                toolInput: { question: 'Which option?', options: ['A', 'B'] },
+                timestamp: '2026-06-29T12:00:00.000Z',
+            };
+            writeAgentRequest(homeDir, entry);
+
+            expect(readLatestAgentRequest(homeDir, 'good')).toEqual(entry);
+        });
+    });
+});

package/src/index.ts

@@ -30,3 +30,6 @@ 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';
+
+export type { AgentRequest } from './utils/agent-requests.js';
+export { getAgentRequestPath, readLatestAgentRequest, writeAgentRequest } from './utils/agent-requests.js';