Merge pull request #41 from mkXultra/feat/peek

feat: Add peek command for one-shot observation of running agent messages

Author: mkXultra

README.ja.md

@@ -124,6 +124,7 @@ ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --session-id ses_123 --prompt
 ai-cli ps
 ai-cli result 12345
 ai-cli result 12345 --verbose
+ai-cli peek 12345 --time 10
 ai-cli wait 12345 --timeout 300
 ai-cli wait 12345 --verbose
 ai-cli kill 12345
@@ -178,6 +179,7 @@ macOSでは、これらのツールを初めて実行する際にフォルダへ
 - `run`
 - `ps`
 - `result`
+- `peek`
 - `wait`
 - `kill`
 - `cleanup`
@@ -194,6 +196,8 @@ ai-cli run --cwd "$PWD" --model codex-ultra --prompt "fix failing tests"
 ai-cli run --cwd "$PWD" --model opencode --session-id ses_existing --prompt "この OpenCode セッションを継続して"
 ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --prompt "明示的な OpenCode モデルで実行"
 ai-cli ps
+ai-cli peek 12345 --time 10
+ai-cli peek 12345 12346 --time 10
 ai-cli wait 12345
 ai-cli wait 12345 --verbose
 ai-cli result 12345
@@ -272,6 +276,60 @@ Claude CLI、Codex CLI、Gemini CLI、Forge CLI、または OpenCode を使用
 - `timeout` (number, 任意): 最大待機時間（秒）。デフォルトは180秒（3分）です。
 - `verbose` (boolean, 任意): `true` の場合、各結果項目を full 形で返します。デフォルトは `false` です。
 
+### `peek`
+
+実行中の子エージェントを短時間だけ観測し、その `peek` 呼び出しの観測ウィンドウ内で ai-cli-mcp が受理した自然言語メッセージだけを返します。履歴APIではなく、欠落のないストリーミングでもなく、シェルの `stdout` / `stderr` tail でもありません。別々の `peek` 呼び出しの間に出たメッセージは取得できない場合があります。v1 では `--follow` はありません。
+
+CLI v1:
+
+```bash
+ai-cli peek 123 --time 10
+ai-cli peek 123 456 --time 10
+```
+
+**引数:**
+- `pids` (array of numbers, 必須): `run` が返したプロセスIDを 1..32 件指定します。重複したPIDはサーバー側で重複排除され、最初に出た順序が維持されます。未知または管理外のPIDは、呼び出し全体の失敗ではなく、プロセスごとに `not_found` として返されます。
+- `peek_time_sec` (number, 任意): 観測時間（秒）の正の整数です。デフォルトは10秒、最大60秒です。`0`、負数、小数は無効です。
+
+**観測とフィルタリング:**
+- `peek_started_at` と `messages[].ts` は、ai-cli-mcp サーバー側の UTC RFC3339 タイムスタンプです。`peek_started_at` は検証とリスナー登録後に観測ウィンドウが始まった時刻、`messages[].ts` は ai-cli-mcp がメッセージを観測して受理した時刻です。
+- 観測ウィンドウは `peek_time_sec` が経過するか、対象プロセスがすべて終端状態になった時点で終了します。
+- 観測開始前のメッセージは返しません。同じPIDへの同時 `peek` は可能で、それぞれ独立した観測ウィンドウを持つため、メッセージが重複して返ることがあります。
+- 返すのは認識済みの自然言語メッセージだけです。Codex の `agent_message` text、Claude assistant の text content、OpenCode の `type: "text"` かつ `part.type` が `"text"` のイベント、Gemini stream-json の `role` が `"assistant"` の `message` イベントを含めます。raw `stdout` / `stderr`、raw JSONL、reasoning、`tool_use`、`tool_result`、コマンドの `stdout` / `stderr`、command execution メタデータ、token usage、verbose メタデータは除外します。
+- 未知のイベント形状はデフォルトで拒否します。Forge など、自然言語抽出がまだ明示対応されていない管理対象エージェントは、実際のプロセス状態を返しつつ、`messages: []`、`truncated: false`、`error: null` にします。
+- 各PIDごとに、観測ウィンドウ内で最初に観測された50件までを保持します。それ以降のメッセージを捨てた場合は `truncated` が `true` になります。
+- `status` は `running`、`completed`、`failed`、`not_found` のいずれかで、観測ウィンドウ終了時点の状態を表します。
+- `agent` は `claude`、`codex`、`gemini`、`forge`、`opencode`、将来追加される追跡済みエージェント文字列、または `null` です。`null` はプロセスが見つからない、またはエージェント種別を判断できない場合を表します。
+
+レスポンス例:
+
+```json
+{
+  "peek_started_at": "2026-04-11T12:34:56.789Z",
+  "observed_duration_sec": 10.01,
+  "processes": [
+    {
+      "pid": 123,
+      "agent": "codex",
+      "status": "running",
+      "messages": [
+        { "ts": "2026-04-11T12:34:59.120Z", "text": "I'm checking the implementation." }
+      ],
+      "truncated": false,
+      "error": null
+    },
+    {
+      "pid": 999,
+      "agent": null,
+      "status": "not_found",
+      "messages": [],
+      "truncated": false,
+      "error": "process not found"
+    }
+  ]
+}
+```
+
 ### `list_processes`
 
 実行中および完了したすべてのAIエージェントプロセスを、ステータス、PID、基本情報とともにリストアップします。

README.md

@@ -121,6 +121,7 @@ ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --session-id ses_123 --prompt
 ai-cli ps
 ai-cli result 12345
 ai-cli result 12345 --verbose
+ai-cli peek 12345 --time 10
 ai-cli wait 12345 --timeout 300
 ai-cli wait 12345 --verbose
 ai-cli kill 12345
@@ -175,6 +176,7 @@ macOS might ask for folder permissions the first time any of these tools run. If
 - `run`
 - `ps`
 - `result`
+- `peek`
 - `wait`
 - `kill`
 - `cleanup`
@@ -191,6 +193,8 @@ ai-cli run --cwd "$PWD" --model codex-ultra --prompt "fix failing tests"
 ai-cli run --cwd "$PWD" --model opencode --session-id ses_existing --prompt "continue this OpenCode session"
 ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --prompt "run with an explicit OpenCode backend model"
 ai-cli ps
+ai-cli peek 12345 --time 10
+ai-cli peek 12345 12346 --time 10
 ai-cli wait 12345
 ai-cli wait 12345 --verbose
 ai-cli result 12345
@@ -269,6 +273,60 @@ By default, each returned result item uses the compact shape shared with `get_re
 - `timeout` (number, optional): Maximum wait time in seconds. Defaults to 180 (3 minutes).
 - `verbose` (boolean, optional): If `true`, each result item uses the full result shape. Defaults to `false`.
 
+### `peek`
+
+Starts a one-shot short observation window for running child agents and returns only natural-language agent messages observed during that specific call. It is not a history API, not gapless streaming, and not shell stdout/stderr tailing. Separate `peek` calls may miss messages emitted between calls; `--follow` is intentionally not part of v1.
+
+CLI v1:
+
+```bash
+ai-cli peek 123 --time 10
+ai-cli peek 123 456 --time 10
+```
+
+**Arguments:**
+- `pids` (array of numbers, required): 1..32 process IDs returned by `run`. Duplicate PIDs are deduplicated server-side, preserving first occurrence order. Unknown or unmanaged PIDs are returned per process as `not_found`, not as a whole-call failure.
+- `peek_time_sec` (number, optional): Positive integer observation length in seconds. Defaults to 10 and is capped at 60. `0`, negative values, and fractional values are invalid.
+
+**Observation and filtering:**
+- `peek_started_at` and `messages[].ts` are ai-cli-mcp server-side UTC RFC3339 timestamps. `peek_started_at` is when the observation window starts after validation and listener registration; `messages[].ts` is when ai-cli-mcp observed and accepted the message.
+- The window ends when `peek_time_sec` elapses or all target processes reach a terminal state, whichever comes first.
+- Messages emitted before the window starts are not returned. Concurrent `peek` calls for the same PID are allowed; each has an independent window and may return overlapping messages.
+- Only recognized natural-language agent messages are returned: Codex `agent_message` text, Claude assistant text content, OpenCode `type: "text"` events where `part.type` is `"text"`, and Gemini stream-json `message` events where `role` is `"assistant"`. Raw stdout/stderr, raw JSONL, reasoning, `tool_use`, `tool_result`, command stdout/stderr, command execution metadata, token usage, and verbose metadata are excluded.
+- Unknown event shapes are denied by default. Managed agents without supported natural-language extraction, such as Forge until explicitly supported, return their real process status with `messages: []`, `truncated: false`, and `error: null`.
+- Each PID keeps the first 50 messages observed in the window. If later messages are dropped, `truncated` is `true`.
+- `status` is one of `running`, `completed`, `failed`, or `not_found`, and reflects state when the observation window closes.
+- `agent` is `claude`, `codex`, `gemini`, `forge`, `opencode`, a future tracked string value, or `null` when the process is not found or the agent cannot be determined.
+
+Example response:
+
+```json
+{
+  "peek_started_at": "2026-04-11T12:34:56.789Z",
+  "observed_duration_sec": 10.01,
+  "processes": [
+    {
+      "pid": 123,
+      "agent": "codex",
+      "status": "running",
+      "messages": [
+        { "ts": "2026-04-11T12:34:59.120Z", "text": "I'm checking the implementation." }
+      ],
+      "truncated": false,
+      "error": null
+    },
+    {
+      "pid": 999,
+      "agent": null,
+      "status": "not_found",
+      "messages": [],
+      "truncated": false,
+      "error": "process not found"
+    }
+  ]
+}
+```
+
 ### `list_processes`
 
 Lists all running and completed AI agent processes with their status, PID, and basic info.

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();

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');
       });

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);

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);
     });
   });

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 () => {