aiterm-mcp 0.29.6 → 0.29.7

package/README.md

@@ -472,7 +472,7 @@ When an agent's answer is longer than the on-screen tail (pane height ≈ 24 lin
 As of v0.16 a parent agent **never blocks** on aiterm — there is no wait parameter anywhere (v0.17 makes the waiter's exit codes mirror its outcome). The whole flow is dispatch + one universal waiter:
 
 1. Launch the child with `agent_launch({ harness: ... })`; every launch shares the normal project/user environment and adds only completion correlation plus lineage. Send a turn with plain `pty_send` (or `claude_turn issue` for durable Claude operations). The call returns immediately with an `event_cursor` in its structured receipt.
-2. Run `aiterm-wait --session <id> --cursor <event_cursor> [--operation sha256:<64hex>] [--timeout <sec>]`. It observes the harness-owned completion source, plus Claude's additive launch hook, as a **pure reader** and exits with a one-line `aiterm.agent-wait-result.v1` receipt. **Exit ≠ done**: the receipt's `outcome` is authoritative (`0` = `done`, `3` = `timeout`, `4` = `closed`, `1` = error).
+2. Pass the receipt's `wait_process.executable` and `wait_process.args` unchanged to a true argv process API. PowerShell 7's `Start-Process` is the exception because it joins `-ArgumentList` arrays; pass `windows_start_process_argument_list` as its one ready-made argument string instead. This invokes the bundled waiter through the exact Node runtime that is already running aiterm, including on native Windows where npm's human-facing bin is a PowerShell script shim and install paths may contain spaces. `wait_command` remains a compatibility display string for humans. The waiter observes the harness-owned completion source, plus Claude's additive launch hook, as a **pure reader** and exits with a one-line `aiterm.agent-wait-result.v1` receipt. **Exit ≠ done**: the receipt's `outcome` is authoritative (`0` = `done`, `3` = `timeout`, `4` = `closed`, `1` = error).
 3. **The parent never runs the waiter in its own foreground.** Waiting is correct — but the waiter is a separate process, not the parent's turn. A harness that re-invokes its agent when a background task exits (Claude Code) runs the waiter **in the background** and gets woken with zero polling. So that this is not left to interpretation, aiterm reads `clientInfo.name` from the MCP `initialize` handshake and its receipts name the concrete invocation for the detected host — for Claude Code, literally `Bash(command: "aiterm-wait …", run_in_background: true)`. Unknown or undeclared hosts get the generic "start it as a process that does not block the parent's turn" wording; nothing else about the contract changes. Every receipt leads with the same rule: dispatch and let go, then go do something else or end the turn.
 4. Collect the result exactly as before: `pty_read(agent_transcript: true)`, or `claude_turn recover` for durable Claude operations. The waiter carries the signal, never the payload.
 

package/dist/core.js

@@ -11,6 +11,7 @@ import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { createHash, randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
 import * as rtk from "./rtk.js";
 import { AitermError, telemetryOwnedFailure, ownTelemetryFailure } from "./errors.js";
 import { isWin, SOCKDIR, tmuxCommand, sendPsmuxPayload, loadPtyBufferChunk, pasteBufferBaseArgs, TMUX_EMPTY_CONFIG, attachCommand, normalizePaneCommand, appendMarkSentinel, settlePaneLog, paneCwdArgument, } from "./tmux-runtime.js";
@@ -2144,6 +2145,48 @@ function assertInitialPromptNotPendingForSend(name, force) {
 }
 // aiterm-wait の exit 契約（CLI と各所の案内文で共有する正）。exit≠完了: outcome が done の時だけ完了。
 export const AITERM_WAIT_OUTCOME_NOTE = `exit 0=done / 3=timeout（既定${DEFAULT_AGENT_DONE_TIMEOUT}秒・未完了） / 4=closed。receiptのoutcomeが正で、done以外は未完了`;
+function quoteWindowsProcessArgument(value) {
+    if (value !== "" && !/[\s"]/u.test(value))
+        return value;
+    let quoted = '"';
+    let backslashes = 0;
+    for (const char of value) {
+        if (char === "\\") {
+            backslashes += 1;
+        }
+        else if (char === '"') {
+            quoted += "\\".repeat(backslashes * 2 + 1) + '"';
+            backslashes = 0;
+        }
+        else {
+            quoted += "\\".repeat(backslashes) + char;
+            backslashes = 0;
+        }
+    }
+    return quoted + "\\".repeat(backslashes * 2) + '"';
+}
+export function windowsStartProcessArgumentList(args) {
+    return args.map(quoteWindowsProcessArgument).join(" ");
+}
+// npmのplatform別bin shimをcallerに解釈させず、現在稼働中のNodeと同梱CLIを直接起動する。
+// Windowsでもbackendはpsmux、対話shellはPowerShell 7のまま。これはwaiter processの入口だけを所有する。
+export function agentWaitProcess(session, cursor, runtime = {}) {
+    const executable = runtime.executable ?? process.execPath;
+    const args = [
+        runtime.cliPath ?? fileURLToPath(new URL("./aiterm-wait-cli.js", import.meta.url)),
+        "--session",
+        session,
+        "--cursor",
+        String(cursor),
+    ];
+    return {
+        executable,
+        args,
+        windows_start_process_argument_list: (runtime.platform ?? process.platform) === "win32"
+            ? windowsStartProcessArgumentList(args)
+            : null,
+    };
+}
 // 親ホストの識別（MCP initialize の clientInfo.name）。完了待ちコマンドを「親のターンを塞がない
 // 起動形」で名指しするためだけに使う。分からない時は汎用文へ落ち、機能は一切変えない。
 let parentClientName = null;

package/dist/index.js

@@ -27,9 +27,17 @@ const server = new McpServer({ name: "aiterm", version: pkg.version });
  * ここでは「待つな」を断定形で先に置き、foreground 実行の禁止までを説明の側に含める。
  */
 const NON_BLOCKING_RULE = "dispatch した子は投げっぱなしでよい＝親はここで待たない。" +
-    "完了通知は `aiterm-wait --session <id> --cursor <event_cursor>` を親のターンを塞がない別プロセスとして起動して受け、" +
+    "完了通知はreceiptの `wait_process.executable` と `wait_process.args` をそのまま親のターンを塞がない別プロセスAPIへ渡して受け、" +
+    "PowerShell 7のStart-Processだけは `windows_start_process_argument_list` を単一文字列として渡す。" +
     `exit を完了通知として扱う（${core.AITERM_WAIT_OUTCOME_NOTE}。ポーリング不要）。` +
-    "この待ちコマンドを foreground で実行して親のターンを塞ぐことはしない（receipt が実際の起動形を示す）。";
+    "`wait_command` は人間向け互換表示でありprocess境界へ使わない。foreground実行で親のターンを塞がない。";
+const waitProcessOutputSchema = z
+    .object({
+    executable: z.string(),
+    args: z.array(z.string()),
+    windows_start_process_argument_list: z.string().nullable(),
+})
+    .nullable();
 function ok(s) {
     return { content: [{ type: "text", text: s }] };
 }
@@ -134,6 +142,7 @@ server.registerTool("pty_send", {
         mode: z.enum(["sent", "agent_dispatch"]),
         session_id: z.string(),
         event_cursor: z.number().int().nullable(),
+        wait_process: waitProcessOutputSchema,
         launch_id: z.string().nullable(),
         vendor: z.enum(["claude", "codex", "grok", "composer", "cursor"]).nullable(),
         harness: z.enum(["claude-code", "codex-cli", "grok-cli", "cursor-cli"]).nullable(),
@@ -151,6 +160,7 @@ server.registerTool("pty_send", {
             if (rtk)
                 throw new Error("agent session への dispatch は rtk:true と併用できません");
             const receipt = await core.dispatchAgentTurn(session_id, text, { raw });
+            const waitProcess = core.agentWaitProcess(receipt.session_id, receipt.event_cursor);
             return {
                 content: [
                     {
@@ -165,6 +175,7 @@ server.registerTool("pty_send", {
                     mode: "agent_dispatch",
                     session_id: receipt.session_id,
                     event_cursor: receipt.event_cursor,
+                    wait_process: waitProcess,
                     launch_id: receipt.launch_id,
                     vendor: receipt.vendor,
                     harness: receipt.harness,
@@ -180,6 +191,7 @@ server.registerTool("pty_send", {
                 mode: "sent",
                 session_id,
                 event_cursor: null,
+                wait_process: null,
                 launch_id: null,
                 vendor: null,
                 harness: null,
@@ -457,13 +469,14 @@ const agentEffortDesc = (kind) => kind === "claude"
         : kind === "cursor"
             ? "Cursor catalogのeffort。指定時はmodel必須で、adapterが model-effort の正規IDへ変換してlive catalogに照合する。"
             : "Grok Build reasoning effort。利用可能値はCLI／modelのlive catalogに従う。省略時はCLI／model既定。";
-// 全launcher共通の完了受信ガイド。待ちコマンドは起動応答の wait_command（初回prompt時）または
-// pty_send dispatch の event_cursor から組む。文型は NON_BLOCKING_RULE と同じく「待たない」が先。
+// 全launcher共通の完了受信ガイド。machine callerはreceiptのwait_processをそのまま別process APIへ渡す。
+// wait_commandは人間向け互換表示。文型は NON_BLOCKING_RULE と同じく「待たない」が先。
 const agentCompletionDesc = `起動して投げたら投げっぱなしでよい＝親はここで待たない。` +
-    `完了通知は起動応答の wait_command（初回prompt時）または pty_send dispatch 後の ` +
-    `aiterm-wait --session <id> --cursor <event_cursor> を親のターンを塞がない別プロセスとして起動して受ける` +
+    `完了通知は起動応答またはpty_send dispatch receiptの wait_processを、親のターンを塞がない` +
+    `別プロセスAPIへexecutable／argsの境界を保ったまま渡して受ける` +
+    `（PowerShell 7のStart-Processはwindows_start_process_argument_listを使う）` +
     `（${core.AITERM_WAIT_OUTCOME_NOTE}。ポーリング不要・foreground実行はしない）。` +
-    `結果回収は pty_read(agent_transcript:true)。`;
+    `wait_commandは人間向け互換表示。結果回収は pty_read(agent_transcript:true)。`;
 const agentEnvironmentDesc = `通常CLIと同じHOME・cwd・project/user/local設定・MCP・plugin・skill・permission/trustを共有する。` +
     `aitermは完了相関stateだけをlaunch単位で所有する。起動されたagentにはsub-agent自己認識、親session、` +
     `delegation depth/lineage、delegation_allowed=trueを注入し、必要な追加委譲は許可する。`;
@@ -492,6 +505,7 @@ async function launchAgent(kind, args) {
             session_id: sid,
             managed_completion: true,
             event_cursor: eventCursor,
+            wait_process: eventCursor === null ? null : core.agentWaitProcess(sid, eventCursor),
             wait_command: eventCursor === null ? null : `aiterm-wait --session ${sid} --cursor ${eventCursor}`,
             submit_residue: submitResidue,
             ...(supportsWriteScope && write_scope !== undefined
@@ -558,9 +572,10 @@ function registerAgentTool(toolName, kind, desc) {
             harness: z.literal(core.agentHarness(kind)),
             session_id: z.string().regex(/^[A-Za-z0-9_-]{1,64}$/),
             managed_completion: z.boolean().describe("後方互換field。trueはaiterm完了相関が有効という意味で、project/user環境の隔離を意味しない"),
-            // 起動時 prompt でturnが走っている時だけ非null（additive拡張）。wait_command はそのままホストの
-            // バックグラウンドタスクとして実行できる完了待ちコマンド。
+            // 起動時promptでturnが走っている時だけ非null。wait_processがmachine向けprocess境界、
+            // wait_commandは人間向け互換表示。
             event_cursor: z.number().int().nullable(),
+            wait_process: waitProcessOutputSchema,
             wait_command: z.string().nullable(),
             // 初回prompt dispatch後のsubmit座礁観測（additive）。true=composerに残存を確認（submit未成立の疑い）/
             // false=残存を観測せず（submit成立の保証ではない）/ null=promptなし・判定不能。
@@ -593,6 +608,7 @@ server.registerTool("agent_launch", {
         session_id: z.string().regex(/^[A-Za-z0-9_-]{1,64}$/),
         managed_completion: z.boolean(),
         event_cursor: z.number().int().nullable(),
+        wait_process: waitProcessOutputSchema,
         wait_command: z.string().nullable(),
         submit_residue: z.boolean().nullable(),
         write_scope: z.string().optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiterm-mcp",
-  "version": "0.29.6",
+  "version": "0.29.7",
   "mcpName": "io.github.kitepon/aiterm-mcp",
   "description": "Persistent terminal MCP with one harness-based launcher for Claude Code, Codex CLI, Grok CLI, and Cursor Agent CLI, plus durable PTYs for SSH, containers, and REPLs.",
   "keywords": [