ai-cli-mcp 2.15.0 → 2.16.0

package/src/__tests__/process-management.test.ts

@@ -118,6 +118,190 @@ describe('Process Management Tests', () => {
       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() as any;
+      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() as any;
+      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() as any;
+      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();
       

package/src/__tests__/server.test.ts

@@ -497,14 +497,15 @@ describe('ClaudeCodeServer Unit Tests', () => {
       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 () => {

package/src/app/cli.ts

@@ -2,12 +2,14 @@ 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
@@ -58,6 +60,17 @@ Options:
   --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.
@@ -118,6 +131,7 @@ interface CliDeps {
   listProcesses: () => Promise<any>;
   getProcessResult: (pid: number, verbose: boolean) => Promise<any>;
   waitForProcesses: (pids: number[], timeoutSeconds?: number, verbose?: boolean) => Promise<any>;
+  peekProcesses: (pids: number[], peekTimeSec?: number) => Promise<any>;
   killProcess: (pid: number) => Promise<any>;
   cleanupProcesses: () => Promise<any>;
   getDoctorStatus: () => any;
@@ -140,6 +154,7 @@ const defaultDeps: CliDeps = {
   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(),
@@ -204,6 +219,10 @@ function hasHelpFlag(flags: Record<string, string>): boolean {
   return 'help' in flags || 'h' in flags;
 }
 
+function parsePeekCliPids(values: string[]): number[] {
+  return validatePeekPids(values.map((value) => Number(value)));
+}
+
 export async function runCli(argv: string[], deps: Partial<CliDeps> = {}): Promise<number> {
   const {
     stdout,
@@ -213,6 +232,7 @@ export async function runCli(argv: string[], deps: Partial<CliDeps> = {}): Promi
     listProcesses,
     getProcessResult,
     waitForProcesses,
+    peekProcesses,
     killProcess,
     cleanupProcesses,
     getDoctorStatus,
@@ -323,6 +343,34 @@ export async function runCli(argv: string[], deps: Partial<CliDeps> = {}): Promi
     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: number[];
+    let peekTimeSec: number;
+    try {
+      pids = parsePeekCliPids(positionals);
+      const timeRaw = getFirstFlag(flags, ['time']);
+      peekTimeSec = validatePeekTimeSec(timeRaw === undefined ? undefined : Number(timeRaw));
+    } catch (error: any) {
+      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/src/app/mcp.ts

@@ -10,6 +10,7 @@ import {
 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
@@ -230,6 +231,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.',
@@ -270,6 +290,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':
@@ -359,6 +381,30 @@ ${getSupportedModelsDescription()}
     }
   }
 
+  private async handlePeek(toolArguments: any): Promise<ServerResult> {
+    let pids: number[];
+    let peekTimeSec: number;
+
+    try {
+      pids = validatePeekPids(toolArguments.pids);
+      peekTimeSec = validatePeekTimeSec(toolArguments.peek_time_sec);
+    } catch (error: any) {
+      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: any) {
+      throw new McpError(ErrorCode.InternalError, `Failed to peek processes: ${error.message}`);
+    }
+  }
+
   private async handleKillProcess(toolArguments: any): Promise<ServerResult> {
     if (!toolArguments.pid || typeof toolArguments.pid !== 'number') {
       throw new McpError(ErrorCode.InvalidParams, 'Missing or invalid required parameter: pid');

package/src/cli-builder.ts

@@ -219,7 +219,7 @@ export function buildCliCommand(options: BuildCliCommandOptions): CliCommand {
     args.push('--skip-git-repo-check', '--full-auto', '--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/src/cli-process-service.ts

@@ -5,11 +5,13 @@ import {
   existsSync,
   mkdirSync,
   openSync,
+  readSync,
   readFileSync,
   readdirSync,
   realpathSync,
   renameSync,
   rmSync,
+  statSync,
   unlinkSync,
   writeFileSync,
 } from 'node:fs';
@@ -17,8 +19,17 @@ import { join, basename, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { buildCliCommand, type BuildCliCommandOptions } 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,
+  type PeekProcessResult,
+  type PeekResponse,
+} from './peek.js';
 import type { AgentType, ProcessListItem } from './process-service.js';
 
 interface StoredProcess {
@@ -244,6 +255,97 @@ export class CliProcessService {
     }
   }
 
+  async peekProcesses(pids: number[], peekTimeSec = 10): Promise<PeekResponse> {
+    const targetPids = validatePeekPids(pids);
+    const targetPeekTimeSec = validatePeekTimeSec(peekTimeSec);
+    const processes: PeekProcessResult[] = [];
+    const observers: Array<{
+      process: StoredProcess;
+      result: PeekProcessResult;
+      stdoutExtractor: PeekMessageExtractor;
+      stderrExtractor: PeekMessageExtractor;
+      stdoutOffset: number;
+      stderrOffset: number;
+    }> = [];
+
+    for (const pid of targetPids) {
+      let process: StoredProcess;
+      try {
+        process = this.refreshStatus(this.readProcess(pid));
+      } catch {
+        processes.push(buildNotFoundPeekProcess(pid));
+        continue;
+      }
+
+      const result: PeekProcessResult = {
+        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: number): Promise<{ pid: number; status: string; message: string }> {
     const process = this.readProcess(pid);
     const refreshed = this.refreshStatus(process);
@@ -445,6 +547,37 @@ export class CliProcessService {
     return readFileSync(filePath, 'utf-8');
   }
 
+  private fileSizeSafe(filePath: string): number {
+    if (!existsSync(filePath)) {
+      return 0;
+    }
+    return statSync(filePath).size;
+  }
+
+  private readTextFromOffset(filePath: string, offset: number): { text: string; offset: number } {
+    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);
+    }
+  }
+
   private resolveCwdsDir(): string {
     return join(this.stateDir, 'cwds');
   }