ai-cli-mcp 2.15.0 → 2.16.0

package/dist/peek.js

@@ -0,0 +1,56 @@
+export const DEFAULT_PEEK_TIME_SEC = 10;
+export const MAX_PEEK_TIME_SEC = 60;
+export const MAX_PEEK_PIDS = 32;
+export const PEEK_MESSAGE_CAP = 50;
+export function validatePeekPids(value) {
+    if (!Array.isArray(value)) {
+        throw new Error('Missing or invalid required parameter: pids (must be an array of positive safe integers)');
+    }
+    const deduped = [];
+    const seen = new Set();
+    for (const pid of value) {
+        if (typeof pid !== 'number' || !Number.isSafeInteger(pid) || pid <= 0) {
+            throw new Error('All pids must be positive safe integers');
+        }
+        if (!seen.has(pid)) {
+            seen.add(pid);
+            deduped.push(pid);
+        }
+    }
+    if (deduped.length === 0 || deduped.length > MAX_PEEK_PIDS) {
+        throw new Error(`pids must contain 1..${MAX_PEEK_PIDS} entries after dedupe`);
+    }
+    return deduped;
+}
+export function validatePeekTimeSec(value) {
+    if (value === undefined || value === null) {
+        return DEFAULT_PEEK_TIME_SEC;
+    }
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0 || value > MAX_PEEK_TIME_SEC) {
+        throw new Error(`peek_time_sec must be a positive integer no greater than ${MAX_PEEK_TIME_SEC}`);
+    }
+    return value;
+}
+export function buildNotFoundPeekProcess(pid) {
+    return {
+        pid,
+        agent: null,
+        status: 'not_found',
+        messages: [],
+        truncated: false,
+        error: 'process not found',
+    };
+}
+export function appendPeekMessages(target, messages) {
+    for (const message of messages) {
+        if (target.messages.length < PEEK_MESSAGE_CAP) {
+            target.messages.push(message);
+        }
+        else {
+            target.truncated = true;
+        }
+    }
+}
+export function observedDurationSec(startedAtMs, endedAtMs = Date.now()) {
+    return Number(((endedAtMs - startedAtMs) / 1000).toFixed(2));
+}

package/dist/process-service.js

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process';
 import { buildCliCommand } from './cli-builder.js';
-import { parseClaudeOutput, parseCodexOutput, parseForgeOutput, parseGeminiOutput, parseOpenCodeOutput } from './parsers.js';
+import { parseClaudeOutput, parseCodexOutput, parseForgeOutput, parseGeminiOutput, parseOpenCodeOutput, PeekMessageExtractor } from './parsers.js';
+import { appendPeekMessages, buildNotFoundPeekProcess, observedDurationSec, validatePeekPids, validatePeekTimeSec, } from './peek.js';
 import { buildProcessResult } from './process-result.js';
 function parseAgentOutput(agent, stdout, stderr) {
     if (agent === 'codex') {
@@ -155,6 +156,85 @@ export class ProcessService {
             }
         }
     }
+    async peekProcesses(pids, peekTimeSec = 10) {
+        const targetPids = validatePeekPids(pids);
+        const targetPeekTimeSec = validatePeekTimeSec(peekTimeSec);
+        const processes = [];
+        const observers = [];
+        for (const pid of targetPids) {
+            const entry = this.processManager.get(pid);
+            if (!entry) {
+                processes.push(buildNotFoundPeekProcess(pid));
+                continue;
+            }
+            const result = {
+                pid,
+                agent: entry.toolType,
+                status: entry.status,
+                messages: [],
+                truncated: false,
+                error: null,
+            };
+            processes.push(result);
+            const stdoutExtractor = new PeekMessageExtractor(entry.toolType);
+            const stderrExtractor = new PeekMessageExtractor(entry.toolType);
+            const onStdout = (data) => {
+                appendPeekMessages(result, stdoutExtractor.push(data.toString(), new Date().toISOString()));
+            };
+            const onStderr = (data) => {
+                appendPeekMessages(result, stderrExtractor.push(data.toString(), new Date().toISOString()));
+            };
+            if (entry.status === 'running') {
+                entry.process.stdout?.on('data', onStdout);
+                entry.process.stderr?.on('data', onStderr);
+            }
+            observers.push({ entry, result, stdoutExtractor, stderrExtractor, onStdout, onStderr });
+        }
+        const startedAt = new Date();
+        const startedAtMs = Date.now();
+        const runningObservers = observers.filter((observer) => observer.entry.status === 'running');
+        const terminalPromise = Promise.all(runningObservers.map((observer) => this.waitForProcessTerminal(observer.entry)));
+        let timeoutHandle;
+        const timeoutPromise = new Promise((resolve) => {
+            timeoutHandle = setTimeout(resolve, targetPeekTimeSec * 1000);
+            timeoutHandle.unref?.();
+        });
+        try {
+            await Promise.race([terminalPromise, timeoutPromise]);
+        }
+        finally {
+            if (timeoutHandle) {
+                clearTimeout(timeoutHandle);
+            }
+            const flushTs = new Date().toISOString();
+            for (const observer of observers) {
+                observer.entry.process.stdout?.off('data', observer.onStdout);
+                observer.entry.process.stderr?.off('data', observer.onStderr);
+                appendPeekMessages(observer.result, observer.stdoutExtractor.flush(flushTs));
+                appendPeekMessages(observer.result, observer.stderrExtractor.flush(flushTs));
+                observer.result.status = observer.entry.status;
+            }
+        }
+        return {
+            peek_started_at: startedAt.toISOString(),
+            observed_duration_sec: observedDurationSec(startedAtMs),
+            processes,
+        };
+    }
+    waitForProcessTerminal(processEntry) {
+        if (processEntry.status !== 'running') {
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            const done = () => {
+                processEntry.process.off('close', done);
+                processEntry.process.off('error', done);
+                resolve();
+            };
+            processEntry.process.once('close', done);
+            processEntry.process.once('error', done);
+        });
+    }
     killProcess(pid) {
         const processEntry = this.processManager.get(pid);
         if (!processEntry) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-cli-mcp",
-  "version": "2.15.0",
+  "version": "2.16.0",
   "mcpName": "io.github.mkXultra/ai-cli-mcp",
   "description": "MCP server for AI CLI tools (Claude, Codex, Gemini, Forge, and OpenCode) with background process management",
   "author": "mkXultra",

package/src/__tests__/app-cli.test.ts

@@ -3,6 +3,7 @@ import {
   CLI_HELP_TEXT,
   DOCTOR_HELP_TEXT,
   MODELS_HELP_TEXT,
+  PEEK_HELP_TEXT,
   RESULT_HELP_TEXT,
   RUN_HELP_TEXT,
   WAIT_HELP_TEXT,
@@ -199,6 +200,64 @@ describe('ai-cli app', () => {
     expect(waitForProcesses).not.toHaveBeenCalled();
   });
 
+  it('dispatches peek with deduped pid arguments and time', async () => {
+    const stdout = vi.fn();
+    const stderr = vi.fn();
+    const peekProcesses = vi.fn().mockResolvedValue({
+      peek_started_at: '2026-04-11T12:34:56.789Z',
+      observed_duration_sec: 0.01,
+      processes: [],
+    });
+
+    const exitCode = await runCli(
+      ['peek', '123', '456', '123', '--time', '5'],
+      {
+        stdout,
+        stderr,
+        peekProcesses,
+      }
+    );
+
+    expect(exitCode).toBe(0);
+    expect(peekProcesses).toHaveBeenCalledWith([123, 456], 5);
+    expect(stdout).toHaveBeenCalledWith(expect.stringContaining('"peek_started_at"'));
+    expect(stderr).not.toHaveBeenCalled();
+  });
+
+  it('defaults peek time and rejects --follow', async () => {
+    const stdout = vi.fn();
+    const stderr = vi.fn();
+    const peekProcesses = vi.fn().mockResolvedValue({
+      peek_started_at: '2026-04-11T12:34:56.789Z',
+      observed_duration_sec: 0.01,
+      processes: [],
+    });
+
+    const defaultExitCode = await runCli(['peek', '123'], { stdout, stderr, peekProcesses });
+    expect(defaultExitCode).toBe(0);
+    expect(peekProcesses).toHaveBeenCalledWith([123], 10);
+
+    const followExitCode = await runCli(['peek', '123', '--follow'], { stdout, stderr, peekProcesses });
+    expect(followExitCode).toBe(1);
+    expect(stderr).toHaveBeenCalledWith('peek does not support --follow in v1\n');
+  });
+
+  it('rejects invalid peek time values', async () => {
+    const stdout = vi.fn();
+    const stderr = vi.fn();
+    const peekProcesses = vi.fn();
+
+    const exitCode = await runCli(['peek', '123', '--time', '1.5'], {
+      stdout,
+      stderr,
+      peekProcesses,
+    });
+
+    expect(exitCode).toBe(1);
+    expect(stderr).toHaveBeenCalledWith(expect.stringContaining('peek_time_sec must be a positive integer'));
+    expect(peekProcesses).not.toHaveBeenCalled();
+  });
+
   it('dispatches ps, result, and kill', async () => {
     const stdout = vi.fn();
     const stderr = vi.fn();
@@ -354,6 +413,18 @@ describe('ai-cli app', () => {
     expect(stderr).not.toHaveBeenCalled();
   });
 
+  it('prints detailed help for peek --help', async () => {
+    const stdout = vi.fn();
+    const stderr = vi.fn();
+
+    const exitCode = await runCli(['peek', '--help'], { stdout, stderr });
+
+    expect(exitCode).toBe(0);
+    expect(stdout).toHaveBeenCalledWith(PEEK_HELP_TEXT);
+    expect(stdout).toHaveBeenCalledWith(expect.stringContaining('No --follow mode'));
+    expect(stderr).not.toHaveBeenCalled();
+  });
+
   it('prints detailed help for models --help', async () => {
     const stdout = vi.fn();
     const stderr = vi.fn();

package/src/__tests__/cli-builder.test.ts

@@ -388,7 +388,7 @@ describe('cli-builder', () => {
         expect(cmd.cliPath).toBe('/usr/bin/gemini');
         expect(cmd.args).toContain('-y');
         expect(cmd.args).toContain('--output-format');
-        expect(cmd.args).toContain('json');
+        expect(cmd.args).toContain('stream-json');
         expect(cmd.args).toContain('--model');
         expect(cmd.args).toContain('gemini-2.5-pro');
       });

package/src/__tests__/cli-process-service.test.ts

@@ -122,6 +122,74 @@ describe('CliProcessService', () => {
     expect(readFileSync(join(processDir, 'meta.json'), 'utf-8')).toContain('"status": "completed"');
   });
 
+  it('peeks only appended natural-language messages from detached logs', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'ai-cli-cli-service-'));
+    tempDirs.push(root);
+    const scriptPath = join(root, 'mock-claude-peek');
+    writeFileSync(
+      scriptPath,
+      `#!/bin/bash
+printf '%s\n' '{"type":"assistant","message":{"content":[{"type":"text","text":"old cli message"}]}}'
+sleep 2
+printf '%s\n' '{"type":"assistant","message":{"content":[{"type":"text","text":"new cli message"},{"type":"tool_use","id":"tool-1","name":"Read","input":{"file_path":"/tmp/a"}}]}}'
+printf '%s\n' '{"type":"user","message":{"content":[{"type":"tool_result","tool_use_id":"tool-1","content":"secret"}]}}'
+`
+    );
+    chmodSync(scriptPath, 0o755);
+    const stateDir = join(root, 'state');
+    const workFolder = join(root, 'work');
+    mkdirSync(workFolder, { recursive: true });
+
+    const service = new CliProcessService({
+      stateDir,
+      cliPaths: {
+        claude: scriptPath,
+        codex: scriptPath,
+        gemini: scriptPath,
+        forge: scriptPath,
+        opencode: scriptPath,
+      },
+    });
+
+    const runResult = await service.startProcess({
+      prompt: 'hello peek',
+      cwd: workFolder,
+    });
+
+    const processDir = join(stateDir, 'cwds', encodeCwd(realpathSync(workFolder)), String(runResult.pid));
+    const stdoutPath = join(processDir, 'stdout.log');
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < 5000 && !readFileSync(stdoutPath, 'utf-8').includes('old cli message')) {
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+    expect(readFileSync(stdoutPath, 'utf-8')).toContain('old cli message');
+
+    const peekResult = await service.peekProcesses([runResult.pid, runResult.pid, 999999], 3);
+
+    expect(peekResult.processes).toHaveLength(2);
+    expect(peekResult.processes[0]).toMatchObject({
+      pid: runResult.pid,
+      agent: 'claude',
+      status: 'completed',
+      messages: [
+        {
+          ts: expect.any(String),
+          text: 'new cli message',
+        },
+      ],
+      truncated: false,
+      error: null,
+    });
+    expect(peekResult.processes[1]).toEqual({
+      pid: 999999,
+      agent: null,
+      status: 'not_found',
+      messages: [],
+      truncated: false,
+      error: 'process not found',
+    });
+  });
+
   it('returns compact results by default and full results when verbose is true', async () => {
     const root = mkdtempSync(join(tmpdir(), 'ai-cli-cli-service-'));
     tempDirs.push(root);

package/src/__tests__/e2e.test.ts

@@ -39,7 +39,7 @@ describe('Claude Code MCP E2E Tests', () => {
     it('should register run tool', async () => {
       const tools = await client.listTools();
       
-      expect(tools).toHaveLength(6);
+      expect(tools).toHaveLength(7);
       const claudeCodeTool = tools.find((t: any) => t.name === 'run');
       expect(claudeCodeTool.inputSchema.properties.model.description).toContain('sonnet');
       expect(claudeCodeTool.inputSchema.properties.model.description).toContain('opencode');
@@ -49,6 +49,7 @@ describe('Claude Code MCP E2E Tests', () => {
       // Verify other tools exist
       expect(tools.some((t: any) => t.name === 'list_processes')).toBe(true);
       expect(tools.some((t: any) => t.name === 'get_result')).toBe(true);
+      expect(tools.some((t: any) => t.name === 'peek')).toBe(true);
       expect(tools.some((t: any) => t.name === 'kill_process')).toBe(true);
     });
   });

package/src/__tests__/mcp-contract.test.ts

@@ -96,6 +96,7 @@ describe('MCP Contract Tests', () => {
       'get_result',
       'kill_process',
       'list_processes',
+      'peek',
       'run',
       'wait',
     ]);
@@ -132,6 +133,14 @@ describe('MCP Contract Tests', () => {
       'timeout',
       'verbose',
     ]);
+
+    const peekTool = tools.find((tool: any) => tool.name === 'peek');
+    expect(peekTool.inputSchema.required).toEqual(['pids']);
+    expect(Object.keys(peekTool.inputSchema.properties).sort()).toEqual([
+      'peek_time_sec',
+      'pids',
+    ]);
+    expect(peekTool.description).toContain('One-shot');
   });
 
   it('preserves the stdio MCP smoke flow and response shapes', async () => {

package/src/__tests__/parsers.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { parseCodexOutput, parseClaudeOutput, parseForgeOutput, parseOpenCodeOutput } from '../parsers.js';
+import { parseCodexOutput, parseClaudeOutput, parseForgeOutput, parseGeminiOutput, parseOpenCodeOutput, PeekMessageExtractor } from '../parsers.js';
 
 describe('parseCodexOutput', () => {
   it('should parse basic Codex output with message and session_id', () => {
@@ -65,6 +65,193 @@ INVALID_JSON
   });
 });
 
+describe('PeekMessageExtractor', () => {
+  const ts = '2026-04-11T12:34:56.789Z';
+
+  it('extracts only Codex agent_message text', () => {
+    const extractor = new PeekMessageExtractor('codex');
+    const output = [
+      '{"type":"item.completed","item":{"type":"reasoning","text":"hidden"}}',
+      '{"type":"item.completed","item":{"type":"command_execution","aggregated_output":"secret command output"}}',
+      '{"type":"item.completed","item":{"type":"agent_message","text":"Visible Codex message"}}',
+      '{"msg":{"type":"token_count","total":123}}',
+      '{"msg":{"type":"agent_message","message":"Visible legacy Codex message"}}',
+    ].join('\n') + '\n';
+
+    expect(extractor.push(output, ts)).toEqual([
+      { ts, text: 'Visible Codex message' },
+      { ts, text: 'Visible legacy Codex message' },
+    ]);
+  });
+
+  it('extracts only Claude assistant text content', () => {
+    const extractor = new PeekMessageExtractor('claude');
+    const output = [
+      '{"type":"assistant","message":{"content":[{"type":"text","text":"Visible Claude text"},{"type":"tool_use","id":"tool-1","name":"Read","input":{"file_path":"/tmp/a"}}]}}',
+      '{"type":"user","message":{"content":[{"type":"tool_result","tool_use_id":"tool-1","content":"secret"}]}}',
+      '{"type":"result","result":"Final result is not peek assistant text"}',
+    ].join('\n') + '\n';
+
+    expect(extractor.push(output, ts)).toEqual([
+      { ts, text: 'Visible Claude text' },
+    ]);
+  });
+
+  it('extracts only Gemini assistant message content', () => {
+    const extractor = new PeekMessageExtractor('gemini');
+    const output = [
+      '{"type":"message","timestamp":"2026-04-11T14:44:42.294Z","role":"user","content":"hidden user text"}',
+      '{"type":"message","timestamp":"2026-04-11T14:44:53.820Z","role":"assistant","content":"Visible Gemini text","delta":true}',
+      '{"type":"tool_use","timestamp":"2026-04-11T14:44:53.821Z","tool_name":"run_shell_command","parameters":{"command":"echo secret"}}',
+      '{"type":"tool_result","timestamp":"2026-04-11T14:45:03.011Z","status":"success","output":"secret command output"}',
+      '{"type":"result","timestamp":"2026-04-11T14:45:10.380Z","status":"success","response":"Final result is not peek assistant text"}',
+    ].join('\n') + '\n';
+
+    expect(extractor.push(output, ts)).toEqual([
+      { ts, text: 'Visible Gemini text' },
+    ]);
+  });
+
+  it('joins split Gemini assistant chunks into one peek message on flush', () => {
+    const extractor = new PeekMessageExtractor('gemini');
+    const output = [
+      '{"type":"message","timestamp":"2026-04-11T14:44:53.820Z","role":"assistant","content":"Step 2 done. Starting step ","delta":true}',
+      '{"type":"message","timestamp":"2026-04-11T14:44:53.821Z","role":"assistant","content":"3.","delta":true}',
+    ].join('\n') + '\n';
+
+    expect(extractor.push(output, ts)).toEqual([]);
+    expect(extractor.flush('2026-04-11T12:34:59.000Z')).toEqual([
+      { ts: '2026-04-11T12:34:59.000Z', text: 'Step 2 done. Starting step 3.' },
+    ]);
+  });
+
+  it('emits separate Gemini peek messages when a boundary separates logical messages', () => {
+    const extractor = new PeekMessageExtractor('gemini');
+    const output = [
+      '{"type":"message","timestamp":"2026-04-11T14:44:53.820Z","role":"assistant","content":"Starting step ","delta":true}',
+      '{"type":"message","timestamp":"2026-04-11T14:44:53.821Z","role":"assistant","content":"1.","delta":true}',
+      '{"type":"tool_use","timestamp":"2026-04-11T14:44:53.822Z","tool_name":"run_shell_command","parameters":{"command":"echo secret"}}',
+      '{"type":"tool_result","timestamp":"2026-04-11T14:45:03.011Z","status":"success","output":"secret command output"}',
+      '{"type":"message","timestamp":"2026-04-11T14:45:10.315Z","role":"assistant","content":"Final ","delta":true}',
+      '{"type":"message","timestamp":"2026-04-11T14:45:10.316Z","role":"assistant","content":"answer.","delta":true}',
+      '{"type":"result","timestamp":"2026-04-11T14:45:10.380Z","status":"success","response":"Final result response is not peek text","stats":{"total_tokens":21999}}',
+    ].join('\n') + '\n';
+
+    expect(extractor.push(output, ts)).toEqual([
+      { ts, text: 'Starting step 1.' },
+      { ts, text: 'Final answer.' },
+    ]);
+    expect(extractor.flush(ts)).toEqual([]);
+  });
+
+  it('does not emit Gemini user, tool, tool result, stats, or result response text', () => {
+    const extractor = new PeekMessageExtractor('gemini');
+    const output = [
+      '{"type":"message","timestamp":"2026-04-11T14:44:42.294Z","role":"user","content":"hidden user text"}',
+      '{"type":"tool_use","timestamp":"2026-04-11T14:44:53.821Z","tool_name":"run_shell_command","parameters":{"command":"echo secret"}}',
+      '{"type":"tool_result","timestamp":"2026-04-11T14:45:03.011Z","status":"success","output":"secret command output"}',
+      '{"type":"result","timestamp":"2026-04-11T14:45:10.380Z","status":"success","response":"Final result response is not peek text","stats":{"total_tokens":21999}}',
+    ].join('\n') + '\n';
+
+    expect(extractor.push(output, ts)).toEqual([]);
+    expect(extractor.flush(ts)).toEqual([]);
+  });
+
+  it('denies unsupported agents and invalid shapes by default', () => {
+    const extractor = new PeekMessageExtractor('forge');
+    const output = [
+      '{"type":"assistant","message":{"content":[{"type":"text","text":"not supported here"}]}}',
+      '{"type":"item.completed","item":{"type":"agent_message","text":"not supported here"}}',
+      '{"type":"text","part":{"type":"text","text":"not supported here"}}',
+      '{"type":"message","role":"assistant","content":"not supported here"}',
+      'plain stdout',
+    ].join('\n') + '\n';
+
+    expect(extractor.push(output, ts)).toEqual([]);
+  });
+
+  it('extracts only OpenCode natural-language text events', () => {
+    const extractor = new PeekMessageExtractor('opencode');
+    const output = [
+      '{"type":"text","timestamp":1775918783605,"sessionID":"ses-1","part":{"type":"text","text":"OpenCode visible text"}}',
+      '{"type":"tool_use","timestamp":1775918783606,"sessionID":"ses-1","part":{"type":"tool","state":{"output":"secret command output"},"metadata":{"output":"secret metadata output"}}}',
+      '{"type":"text","timestamp":1775918783607,"sessionID":"ses-1","part":{"type":"tool","text":"wrong part type"}}',
+    ].join('\n') + '\n';
+
+    expect(extractor.push(output, ts)).toEqual([
+      { ts, text: 'OpenCode visible text' },
+    ]);
+  });
+
+  it('can flush a complete JSON event without a trailing newline', () => {
+    const extractor = new PeekMessageExtractor('codex');
+    expect(extractor.push('{"type":"item.completed","item":{"type":"agent_message","text":"pending"}}', ts)).toEqual([]);
+    expect(extractor.flush(ts)).toEqual([{ ts, text: 'pending' }]);
+  });
+});
+
+describe('parseGeminiOutput', () => {
+  it('should parse legacy final JSON output', () => {
+    const output = JSON.stringify({
+      session_id: 'gemini-session-json',
+      response: 'Legacy Gemini final response',
+      stats: {
+        total_tokens: 123,
+      },
+    });
+
+    expect(parseGeminiOutput(output)).toEqual({
+      session_id: 'gemini-session-json',
+      response: 'Legacy Gemini final response',
+      stats: {
+        total_tokens: 123,
+      },
+    });
+  });
+
+  it('should normalize a single-line Gemini assistant stream event', () => {
+    const output = '{"type":"message","timestamp":"2026-04-11T14:44:53.820Z","role":"assistant","content":"Only answer","delta":true}';
+
+    const result = parseGeminiOutput(output);
+
+    expect(result).toMatchObject({
+      message: 'Only answer',
+      session_id: null,
+    });
+    expect(result).not.toHaveProperty('type');
+    expect(result).not.toHaveProperty('content');
+  });
+
+  it('should parse Gemini stream-json NDJSON output', () => {
+    const output = [
+      '{"type":"init","timestamp":"2026-04-11T14:44:42.293Z","session_id":"gemini-session-stream","model":"gemini-3.1-pro-preview"}',
+      '{"type":"message","timestamp":"2026-04-11T14:44:42.294Z","role":"user","content":"hidden user text"}',
+      '{"type":"message","timestamp":"2026-04-11T14:44:53.820Z","role":"assistant","content":"First logical assistant response.","delta":true}',
+      '{"type":"tool_use","timestamp":"2026-04-11T14:44:53.821Z","tool_name":"run_shell_command","tool_id":"tool-1","parameters":{"command":"echo hidden"}}',
+      '{"type":"tool_result","timestamp":"2026-04-11T14:45:03.011Z","tool_id":"tool-1","status":"success","output":"hidden command output"}',
+      '{"type":"message","timestamp":"2026-04-11T14:45:10.315Z","role":"assistant","content":"Final assistant ","delta":true}',
+      '{"type":"message","timestamp":"2026-04-11T14:45:10.316Z","role":"assistant","content":"response.","delta":true}',
+      '{"type":"result","timestamp":"2026-04-11T14:45:10.380Z","status":"success","response":"Result response is not the parsed message","stats":{"total_tokens":21999}}',
+    ].join('\n') + '\n';
+
+    expect(parseGeminiOutput(output)).toEqual({
+      message: 'Final assistant response.',
+      session_id: 'gemini-session-stream',
+      stats: {
+        total_tokens: 21999,
+      },
+      tools: [
+        {
+          tool: 'run_shell_command',
+          input: { command: 'echo hidden' },
+          output: 'hidden command output',
+          status: 'success',
+        },
+      ],
+    });
+  });
+});
+
 describe('parseClaudeOutput', () => {
   it('should parse legacy JSON output', () => {
     const output = JSON.stringify({

package/src/__tests__/peek.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { appendPeekMessages, validatePeekPids, validatePeekTimeSec, type PeekProcessResult } from '../peek.js';
+
+describe('peek helpers', () => {
+  it('dedupes pids while preserving first occurrence order', () => {
+    expect(validatePeekPids([3, 1, 3, 2, 1])).toEqual([3, 1, 2]);
+  });
+
+  it('validates pid and time limits', () => {
+    expect(() => validatePeekPids([])).toThrow(/1..32/);
+    expect(() => validatePeekPids([1.5])).toThrow(/positive safe integers/);
+    expect(() => validatePeekPids([Number.MAX_SAFE_INTEGER + 1])).toThrow(/positive safe integers/);
+    expect(validatePeekTimeSec(undefined)).toBe(10);
+    expect(validatePeekTimeSec(60)).toBe(60);
+    expect(() => validatePeekTimeSec(0)).toThrow(/positive integer/);
+    expect(() => validatePeekTimeSec(1.5)).toThrow(/positive integer/);
+    expect(() => validatePeekTimeSec(61)).toThrow(/positive integer/);
+  });
+
+  it('keeps the first 50 messages and marks truncation when later messages are dropped', () => {
+    const process: PeekProcessResult = {
+      pid: 123,
+      agent: 'codex',
+      status: 'running',
+      messages: [],
+      truncated: false,
+      error: null,
+    };
+
+    appendPeekMessages(
+      process,
+      Array.from({ length: 55 }, (_, index) => ({
+        ts: '2026-04-11T12:34:56.789Z',
+        text: `message ${index}`,
+      })),
+    );
+
+    expect(process.messages).toHaveLength(50);
+    expect(process.messages[0].text).toBe('message 0');
+    expect(process.messages[49].text).toBe('message 49');
+    expect(process.truncated).toBe(true);
+  });
+});