ai-cli-mcp 2.15.0 → 2.17.0

package/dist/__tests__/process-management.test.js

@@ -101,6 +101,165 @@ describe('Process Management Tests', () => {
             expect(response.status).toBe('started');
             expect(response.message).toBe('claude process started successfully');
         });
+        it('should peek only natural-language messages observed after registration', async () => {
+            const { handlers } = await setupServer();
+            const mockProcess = new EventEmitter();
+            mockProcess.pid = 12345;
+            mockProcess.stdout = new EventEmitter();
+            mockProcess.stderr = new EventEmitter();
+            mockProcess.kill = vi.fn();
+            mockSpawn.mockReturnValue(mockProcess);
+            const callToolHandler = handlers.get('callTool');
+            await callToolHandler({
+                params: {
+                    name: 'run',
+                    arguments: {
+                        prompt: 'test prompt',
+                        workFolder: '/tmp'
+                    }
+                }
+            });
+            mockProcess.stdout.emit('data', '{"type":"assistant","message":{"content":[{"type":"text","text":"old message"}]}}\n');
+            const peekPromise = callToolHandler({
+                params: {
+                    name: 'peek',
+                    arguments: {
+                        pids: [12345, 12345, 99999],
+                        peek_time_sec: 1,
+                    }
+                }
+            });
+            setTimeout(() => {
+                mockProcess.stdout.emit('data', '{"type":"assistant","message":{"content":[{"type":"text","text":"new message"},{"type":"tool_use","id":"tool-1","name":"Read","input":{"file_path":"/tmp/a"}}]}}\n');
+                mockProcess.stdout.emit('data', '{"type":"user","message":{"content":[{"type":"tool_result","tool_use_id":"tool-1","content":"secret"}]}}\n');
+                mockProcess.emit('close', 0);
+            }, 10);
+            const result = await peekPromise;
+            const response = JSON.parse(result.content[0].text);
+            expect(response.processes).toHaveLength(2);
+            expect(response.processes[0]).toMatchObject({
+                pid: 12345,
+                agent: 'claude',
+                status: 'completed',
+                messages: [
+                    {
+                        ts: expect.any(String),
+                        text: 'new message',
+                    },
+                ],
+                truncated: false,
+                error: null,
+            });
+            expect(response.processes[1]).toEqual({
+                pid: 99999,
+                agent: null,
+                status: 'not_found',
+                messages: [],
+                truncated: false,
+                error: 'process not found',
+            });
+        });
+        it('should peek OpenCode text events and exclude OpenCode tool output', async () => {
+            const { handlers } = await setupServer();
+            const mockProcess = new EventEmitter();
+            mockProcess.pid = 12346;
+            mockProcess.stdout = new EventEmitter();
+            mockProcess.stderr = new EventEmitter();
+            mockProcess.kill = vi.fn();
+            mockSpawn.mockReturnValue(mockProcess);
+            const callToolHandler = handlers.get('callTool');
+            await callToolHandler({
+                params: {
+                    name: 'run',
+                    arguments: {
+                        prompt: 'opencode peek prompt',
+                        workFolder: '/tmp',
+                        model: 'opencode',
+                    }
+                }
+            });
+            const peekPromise = callToolHandler({
+                params: {
+                    name: 'peek',
+                    arguments: {
+                        pids: [12346],
+                        peek_time_sec: 1,
+                    }
+                }
+            });
+            setTimeout(() => {
+                mockProcess.stdout.emit('data', '{"type":"text","timestamp":1775918783605,"sessionID":"ses-1","part":{"type":"text","text":"OpenCode visible text"}}\n');
+                mockProcess.stdout.emit('data', '{"type":"tool_use","timestamp":1775918783606,"sessionID":"ses-1","part":{"type":"tool","state":{"output":"secret command output"},"metadata":{"output":"secret metadata output"}}}\n');
+                mockProcess.emit('close', 0);
+            }, 10);
+            const result = await peekPromise;
+            const response = JSON.parse(result.content[0].text);
+            expect(response.processes).toHaveLength(1);
+            expect(response.processes[0]).toMatchObject({
+                pid: 12346,
+                agent: 'opencode',
+                status: 'completed',
+                messages: [
+                    {
+                        ts: expect.any(String),
+                        text: 'OpenCode visible text',
+                    },
+                ],
+                truncated: false,
+                error: null,
+            });
+        });
+        it('should peek Gemini assistant message events and exclude tool output', async () => {
+            const { handlers } = await setupServer();
+            const mockProcess = new EventEmitter();
+            mockProcess.pid = 12347;
+            mockProcess.stdout = new EventEmitter();
+            mockProcess.stderr = new EventEmitter();
+            mockProcess.kill = vi.fn();
+            mockSpawn.mockReturnValue(mockProcess);
+            const callToolHandler = handlers.get('callTool');
+            await callToolHandler({
+                params: {
+                    name: 'run',
+                    arguments: {
+                        prompt: 'gemini peek prompt',
+                        workFolder: '/tmp',
+                        model: 'gemini-2.5-pro',
+                    }
+                }
+            });
+            const peekPromise = callToolHandler({
+                params: {
+                    name: 'peek',
+                    arguments: {
+                        pids: [12347],
+                        peek_time_sec: 1,
+                    }
+                }
+            });
+            setTimeout(() => {
+                mockProcess.stdout.emit('data', '{"type":"message","timestamp":"2026-04-11T14:44:42.294Z","role":"user","content":"hidden user text"}\n');
+                mockProcess.stdout.emit('data', '{"type":"message","timestamp":"2026-04-11T14:44:53.820Z","role":"assistant","content":"Visible Gemini text","delta":true}\n');
+                mockProcess.stdout.emit('data', '{"type":"tool_result","timestamp":"2026-04-11T14:45:03.011Z","status":"success","output":"secret command output"}\n');
+                mockProcess.emit('close', 0);
+            }, 10);
+            const result = await peekPromise;
+            const response = JSON.parse(result.content[0].text);
+            expect(response.processes).toHaveLength(1);
+            expect(response.processes[0]).toMatchObject({
+                pid: 12347,
+                agent: 'gemini',
+                status: 'completed',
+                messages: [
+                    {
+                        ts: expect.any(String),
+                        text: 'Visible Gemini text',
+                    },
+                ],
+                truncated: false,
+                error: null,
+            });
+        });
         it('should handle process with model parameter', async () => {
             const { handlers } = await setupServer();
             const mockProcess = new EventEmitter();

package/dist/__tests__/server.test.js

@@ -407,14 +407,15 @@ describe('ClaudeCodeServer Unit Tests', () => {
             // Test the handler
             const handler = listToolsCall[1];
             const result = await handler();
-            expect(result.tools).toHaveLength(6);
+            expect(result.tools).toHaveLength(7);
             expect(result.tools[0].name).toBe('run');
             expect(result.tools[0].description).toContain('AI Agent Runner');
             expect(result.tools[1].name).toBe('list_processes');
             expect(result.tools[2].name).toBe('get_result');
             expect(result.tools[3].name).toBe('wait');
-            expect(result.tools[4].name).toBe('kill_process');
-            expect(result.tools[5].name).toBe('cleanup_processes');
+            expect(result.tools[4].name).toBe('peek');
+            expect(result.tools[5].name).toBe('kill_process');
+            expect(result.tools[6].name).toBe('cleanup_processes');
         });
         it('should handle CallToolRequest', async () => {
             mockHomedir.mockReturnValue('/home/user');

package/dist/app/cli.js

@@ -2,11 +2,13 @@ import { runMcpServer } from './mcp.js';
 import { CliProcessService } from '../cli-process-service.js';
 import { getCliDoctorStatus } from '../cli-utils.js';
 import { getModelsPayload } from '../model-catalog.js';
+import { validatePeekPids, validatePeekTimeSec } from '../peek.js';
 export const CLI_HELP_TEXT = `Usage: ai-cli <command> [options]
 
 Commands:
   run       Start an AI CLI process in the background
   wait      Wait for one or more pids
+  peek      Observe new natural-language agent messages for a short window
   ps        List tracked processes
   result    Get the current result for a pid
   kill      Terminate a tracked pid
@@ -53,6 +55,16 @@ Options:
   --verbose                    Return full metadata and detailed parsed output
   --help, -h                   Show this help message
 `;
+export const PEEK_HELP_TEXT = `Usage: ai-cli peek <pid...> [options]
+
+Observe new natural-language agent messages for a short one-shot window.
+In v1, message extraction is supported for Codex, Claude, OpenCode, and Gemini; Forge returns status with messages: [].
+This is not a history API, gapless streaming, or stdout/stderr tailing. No --follow mode is available in v1.
+
+Options:
+  --time <seconds>             Observation window in seconds. Defaults to 10, maximum 60
+  --help, -h                   Show this help message
+`;
 export const KILL_HELP_TEXT = `Usage: ai-cli kill <pid>
 
 Terminate a tracked process.
@@ -107,6 +119,7 @@ const defaultDeps = {
     listProcesses: () => getCliProcessService().listProcesses(),
     getProcessResult: (pid, verbose) => getCliProcessService().getProcessResult(pid, verbose),
     waitForProcesses: (pids, timeoutSeconds, verbose) => getCliProcessService().waitForProcesses(pids, timeoutSeconds, verbose),
+    peekProcesses: (pids, peekTimeSec) => getCliProcessService().peekProcesses(pids, peekTimeSec),
     killProcess: (pid) => getCliProcessService().killProcess(pid),
     cleanupProcesses: () => getCliProcessService().cleanupProcesses(),
     getDoctorStatus: () => getCliDoctorStatus(),
@@ -161,8 +174,11 @@ function writeJson(stdout, value) {
 function hasHelpFlag(flags) {
     return 'help' in flags || 'h' in flags;
 }
+function parsePeekCliPids(values) {
+    return validatePeekPids(values.map((value) => Number(value)));
+}
 export async function runCli(argv, deps = {}) {
-    const { stdout, stderr, startMcpServer, runProcess, listProcesses, getProcessResult, waitForProcesses, killProcess, cleanupProcesses, getDoctorStatus, } = { ...defaultDeps, ...deps };
+    const { stdout, stderr, startMcpServer, runProcess, listProcesses, getProcessResult, waitForProcesses, peekProcesses, killProcess, cleanupProcesses, getDoctorStatus, } = { ...defaultDeps, ...deps };
     const [command] = argv;
     if (!command || command === 'help' || command === '--help' || command === '-h') {
         stdout(CLI_HELP_TEXT);
@@ -258,6 +274,32 @@ export async function runCli(argv, deps = {}) {
         writeJson(stdout, await waitForProcesses(pids, timeout, 'verbose' in flags));
         return 0;
     }
+    if (command === 'peek') {
+        const { positionals, flags } = parseArgs(argv.slice(1));
+        if (hasHelpFlag(flags)) {
+            stdout(PEEK_HELP_TEXT);
+            return 0;
+        }
+        if ('follow' in flags) {
+            stderr('peek does not support --follow in v1\n');
+            stdout(CLI_HELP_TEXT);
+            return 1;
+        }
+        let pids;
+        let peekTimeSec;
+        try {
+            pids = parsePeekCliPids(positionals);
+            const timeRaw = getFirstFlag(flags, ['time']);
+            peekTimeSec = validatePeekTimeSec(timeRaw === undefined ? undefined : Number(timeRaw));
+        }
+        catch (error) {
+            stderr(`${error.message}\n`);
+            stdout(CLI_HELP_TEXT);
+            return 1;
+        }
+        writeJson(stdout, await peekProcesses(pids, peekTimeSec));
+        return 0;
+    }
     if (command === 'kill') {
         const { positionals, flags } = parseArgs(argv.slice(1));
         if (hasHelpFlag(flags)) {

package/dist/app/mcp.js

@@ -4,6 +4,7 @@ import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } f
 import { spawn } from 'node:child_process';
 import { debugLog, findClaudeCli, findCodexCli, findForgeCli, findGeminiCli, findOpencodeCli } from '../cli-utils.js';
 import { getModelParameterDescription, getSupportedModelsDescription } from '../model-catalog.js';
+import { validatePeekPids, validatePeekTimeSec } from '../peek.js';
 import { ProcessService } from '../process-service.js';
 // Server version - update this when releasing new versions
 const SERVER_VERSION = "2.2.0";
@@ -208,6 +209,25 @@ ${getSupportedModelsDescription()}
                         required: ['pids'],
                     },
                 },
+                {
+                    name: 'peek',
+                    description: 'One-shot short observation window for running child agents. Returns only natural-language agent messages observed during this call; not a history API, not gapless streaming, and not stdout/stderr tailing. In v1, message extraction is supported for Codex, Claude, OpenCode, and Gemini; Forge returns status with messages: [].',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            pids: {
+                                type: 'array',
+                                items: { type: 'number' },
+                                description: 'Process IDs returned by run. Duplicates are deduplicated server-side, preserving first occurrence order. Unknown PIDs are returned per process as not_found.',
+                            },
+                            peek_time_sec: {
+                                type: 'number',
+                                description: 'Optional positive integer observation window in seconds. Defaults to 10; maximum is 60.',
+                            },
+                        },
+                        required: ['pids'],
+                    },
+                },
                 {
                     name: 'kill_process',
                     description: 'Terminate a running AI agent process by PID.',
@@ -245,6 +265,8 @@ ${getSupportedModelsDescription()}
                     return this.handleGetResult(toolArguments);
                 case 'wait':
                     return this.handleWait(toolArguments);
+                case 'peek':
+                    return this.handlePeek(toolArguments);
                 case 'kill_process':
                     return this.handleKillProcess(toolArguments);
                 case 'cleanup_processes':
@@ -326,6 +348,29 @@ ${getSupportedModelsDescription()}
             throw new McpError(code, error.message);
         }
     }
+    async handlePeek(toolArguments) {
+        let pids;
+        let peekTimeSec;
+        try {
+            pids = validatePeekPids(toolArguments.pids);
+            peekTimeSec = validatePeekTimeSec(toolArguments.peek_time_sec);
+        }
+        catch (error) {
+            throw new McpError(ErrorCode.InvalidParams, error.message);
+        }
+        try {
+            const response = await this.processService.peekProcesses(pids, peekTimeSec);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify(response, null, 2)
+                    }]
+            };
+        }
+        catch (error) {
+            throw new McpError(ErrorCode.InternalError, `Failed to peek processes: ${error.message}`);
+        }
+    }
     async handleKillProcess(toolArguments) {
         if (!toolArguments.pid || typeof toolArguments.pid !== 'number') {
             throw new McpError(ErrorCode.InvalidParams, 'Missing or invalid required parameter: pid');

package/dist/cli-builder.js

@@ -155,11 +155,11 @@ export function buildCliCommand(options) {
         if (resolvedModel) {
             args.push('--model', resolvedModel);
         }
-        args.push('--skip-git-repo-check', '--full-auto', '--json', prompt);
+        args.push('--skip-git-repo-check', '--dangerously-bypass-approvals-and-sandbox', '--json', prompt);
     }
     else if (agent === 'gemini') {
         cliPath = options.cliPaths.gemini;
-        args = ['-y', '--output-format', 'json'];
+        args = ['-y', '--output-format', 'stream-json'];
         if (options.session_id && typeof options.session_id === 'string') {
             args.push('-r', options.session_id);
         }

package/dist/cli-process-service.js

@@ -1,11 +1,12 @@
 import { spawn } from 'node:child_process';
-import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { join, basename, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { buildCliCommand } from './cli-builder.js';
 import { findClaudeCli, findCodexCli, findForgeCli, findGeminiCli, findOpencodeCli } from './cli-utils.js';
-import { parseClaudeOutput, parseCodexOutput, parseForgeOutput, parseGeminiOutput, parseOpenCodeOutput } from './parsers.js';
+import { parseClaudeOutput, parseCodexOutput, parseForgeOutput, parseGeminiOutput, parseOpenCodeOutput, PeekMessageExtractor } from './parsers.js';
 import { buildProcessResult } from './process-result.js';
+import { appendPeekMessages, buildNotFoundPeekProcess, observedDurationSec, validatePeekPids, validatePeekTimeSec, } from './peek.js';
 function resolveDefaultStateDir() {
     return process.env.AI_CLI_STATE_DIR || join(homedir(), '.local', 'state', 'ai-cli');
 }
@@ -174,6 +175,79 @@ export class CliProcessService {
             await new Promise((resolve) => setTimeout(resolve, 50));
         }
     }
+    async peekProcesses(pids, peekTimeSec = 10) {
+        const targetPids = validatePeekPids(pids);
+        const targetPeekTimeSec = validatePeekTimeSec(peekTimeSec);
+        const processes = [];
+        const observers = [];
+        for (const pid of targetPids) {
+            let process;
+            try {
+                process = this.refreshStatus(this.readProcess(pid));
+            }
+            catch {
+                processes.push(buildNotFoundPeekProcess(pid));
+                continue;
+            }
+            const result = {
+                pid,
+                agent: process.toolType,
+                status: process.status,
+                messages: [],
+                truncated: false,
+                error: null,
+            };
+            processes.push(result);
+            observers.push({
+                process,
+                result,
+                stdoutExtractor: new PeekMessageExtractor(process.toolType),
+                stderrExtractor: new PeekMessageExtractor(process.toolType),
+                stdoutOffset: this.fileSizeSafe(process.stdoutPath),
+                stderrOffset: this.fileSizeSafe(process.stderrPath),
+            });
+        }
+        const startedAt = new Date();
+        const startedAtMs = Date.now();
+        const deadlineMs = startedAtMs + targetPeekTimeSec * 1000;
+        while (Date.now() <= deadlineMs) {
+            const observedAt = new Date().toISOString();
+            let allTerminal = true;
+            for (const observer of observers) {
+                const stdoutRead = this.readTextFromOffset(observer.process.stdoutPath, observer.stdoutOffset);
+                observer.stdoutOffset = stdoutRead.offset;
+                appendPeekMessages(observer.result, observer.stdoutExtractor.push(stdoutRead.text, observedAt));
+                const stderrRead = this.readTextFromOffset(observer.process.stderrPath, observer.stderrOffset);
+                observer.stderrOffset = stderrRead.offset;
+                appendPeekMessages(observer.result, observer.stderrExtractor.push(stderrRead.text, observedAt));
+                observer.process = this.refreshStatus(this.readProcess(observer.process.pid));
+                observer.result.status = observer.process.status;
+                if (observer.process.status === 'running') {
+                    allTerminal = false;
+                }
+            }
+            if (allTerminal) {
+                break;
+            }
+            const remainingMs = deadlineMs - Date.now();
+            if (remainingMs <= 0) {
+                break;
+            }
+            await new Promise((resolve) => setTimeout(resolve, Math.min(50, remainingMs)));
+        }
+        const flushTs = new Date().toISOString();
+        for (const observer of observers) {
+            observer.process = this.refreshStatus(this.readProcess(observer.process.pid));
+            observer.result.status = observer.process.status;
+            appendPeekMessages(observer.result, observer.stdoutExtractor.flush(flushTs));
+            appendPeekMessages(observer.result, observer.stderrExtractor.flush(flushTs));
+        }
+        return {
+            peek_started_at: startedAt.toISOString(),
+            observed_duration_sec: observedDurationSec(startedAtMs),
+            processes,
+        };
+    }
     async killProcess(pid) {
         const process = this.readProcess(pid);
         const refreshed = this.refreshStatus(process);
@@ -341,6 +415,34 @@ export class CliProcessService {
         }
         return readFileSync(filePath, 'utf-8');
     }
+    fileSizeSafe(filePath) {
+        if (!existsSync(filePath)) {
+            return 0;
+        }
+        return statSync(filePath).size;
+    }
+    readTextFromOffset(filePath, offset) {
+        if (!existsSync(filePath)) {
+            return { text: '', offset };
+        }
+        const size = statSync(filePath).size;
+        if (size <= offset) {
+            return { text: '', offset: size };
+        }
+        const fd = openSync(filePath, 'r');
+        try {
+            const length = size - offset;
+            const buffer = Buffer.alloc(length);
+            const bytesRead = readSync(fd, buffer, 0, length, offset);
+            return {
+                text: buffer.subarray(0, bytesRead).toString('utf-8'),
+                offset: size,
+            };
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
     resolveCwdsDir() {
         return join(this.stateDir, 'cwds');
     }