aiterm-mcp 0.19.3 → 0.20.1

package/README.ja.md

@@ -1,3 +1,5 @@
+> **Claude Code から Codex CLI の対話 TUI を操作する——スラッシュコマンドや [`$imagegen`](https://learn.chatgpt.com/docs/image-generation#generate-or-edit-an-image) のようなスキルまで、MCP越しに使える。**
+
 <p align="center">
   <img src=".github/og.svg" alt="aiterm-mcp — AI が握る 1 本の永続 MCP 端末。その中へ他のコーディングエージェント（Claude/Codex/Grok/Composer）を起動する（tmux ベースの stdio MCP サーバ）" width="100%">
 </p>
@@ -6,6 +8,7 @@
 
 [![CI](https://github.com/kitepon-rgb/aiterm-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/kitepon-rgb/aiterm-mcp/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/aiterm-mcp.svg)](https://www.npmjs.com/package/aiterm-mcp)
+[![週間ダウンロード](https://img.shields.io/npm/dw/aiterm-mcp.svg)](https://www.npmjs.com/package/aiterm-mcp)
 [![node](https://img.shields.io/node/v/aiterm-mcp)](https://nodejs.org)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![install size](https://packagephobia.com/badge?p=aiterm-mcp)](https://packagephobia.com/result?p=aiterm-mcp)
@@ -20,6 +23,70 @@
 >
 > *MCP = Model Context Protocol — Claude Code のようなツールが AI に機能を差し込むためのオープン標準。*
 
+kitepon.devを運営する[クオ（@QLyun35332）](https://x.com/QLyun35332)が
+開発・メンテナンスしています。
+
+## MCPクライアントへ導入
+
+cloneもビルドも不要。どのクライアントでも公開パッケージを次のコマンドで起動する:
+
+```bash
+npx -y aiterm-mcp
+```
+
+**Node.js ≥ 18** と **tmux** が必要。Codexを操作する場合は、Codex CLIの導入と認証も必要。
+
+### Claude Code
+
+ユーザー設定へ追加する:
+
+```bash
+claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
+```
+
+プロジェクト設定として共有する場合は、`.mcp.json` に次を置く:
+
+```json
+{
+  "mcpServers": {
+    "aiterm": {
+      "command": "npx",
+      "args": ["-y", "aiterm-mcp"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+`claude_desktop_config.json` に次のサーバーを追加する:
+
+```json
+{
+  "mcpServers": {
+    "aiterm": {
+      "command": "npx",
+      "args": ["-y", "aiterm-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+プロジェクトでは `.cursor/mcp.json`、全体設定では `~/.cursor/mcp.json` に保存する:
+
+```json
+{
+  "mcpServers": {
+    "aiterm": {
+      "command": "npx",
+      "args": ["-y", "aiterm-mcp"]
+    }
+  }
+}
+```
+
 **工場での役割:** aiterm-mcpはdotagents開発工場が管理する自作コア10製品の一つです。
 永続PTYと外部agent実行レーンを所有し、dotagentsが製品横断の導入・統合契約を所有します。
 
@@ -27,12 +94,14 @@
 
 13 ツール: 6 つの **PTY ツール**（`pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list`）で 1 本の永続端末を開き・操作し・読む。加えて 4 つの **エージェント起動ツール**（`claude_agent` / `codex_agent` / `grok_agent` / `composer_agent`）が別のコーディングエージェントの TUI を新しい端末の中に起動し、`claude_turn`がdurable caller向けの構造化issue／recoveryを、`claude_approval`がmanaged Claudeの相関済み承認UI中継を、`diagnostics`が安全なfactory readinessを返す。バックエンドは **tmux** なので、MCP サーバや AI クライアントが再起動してもセッションは生き残る。
 
-**v0.19.2 を 2026-07-20 に公開。** v0.19系では相関済みmanaged Claude approval中継を追加し、
-複数行shell配送を維持し、native Windowsのfactory diagnosticsを拡張しました。v0.18系では
-`submit_residue`、tmux bracketed paste、busyなCodex/Claude画面をreadyと数えないgateにより
-agent dispatchを強化しました。v0.16/0.17以来、親エージェントはaiterm上で一切ブロックしません:
+**v0.20.0 を 2026-07-26 に公開。** 待たずに一度だけ観測する
+`aiterm-wait --timeout 0` の未完了を、実際に待って終わらなかった`timeout`と区別し、
+`running`（exit 5）で返すようにしました。v0.19系では相関済みmanaged Claude approval中継を追加し、
+複数行shell配送を維持し、native Windowsのfactory diagnosticsを拡張しました。
+v0.16/0.17以来、親エージェントはaiterm上で一切ブロックしません:
 agent session への send は常に非ブロック dispatch になり、完了待ちは `aiterm-wait` 一本
-（exit code が receipt の outcome を映す: 0=done / 3=timeout=未完了 / 4=closed）、初回 prompt 付き
+（exit code が receipt の outcome を映す: 0=done / 3=timeout=未完了 /
+4=closed / 5=running=待たない観測）、初回 prompt 付き
 launch は structured receipt にコピペ可能な `wait_command` を含む。factory diagnostics と local
 runtime-error store は canonical dotagents config の `collection.enabled: true` が明示された
 場合だけ収集し、既定OFF、network送信は行いません。tag起点CIのnpm provenance（OIDC Trusted
@@ -134,13 +203,7 @@ $ aiterm-wait --session codex1 --cursor <event_cursor>   # exit 0=done / 3=timeo
 
 上の採取で私が触ったのは 2 本の `⋮` 行（長い head/tail を README 用に省略）と長すぎる grep 行 1 本の truncate だけ——`〈…〉` マーカー・トークン数・各 `is_complete` はツールが出した通り。（`until` は末尾スペース無しの `">>>"` を使う——採取されるプロンプトは末尾が削られるので `">>> "` だと外れて `timeout` に落ちる。）ネスト中は `until`（内側プロンプト）か `mark: true` を渡すこと——そこでは quiescence が原理的に効かないため（[完了検出](#完了検出5-層) / [既知の制約](#既知の制約バグではなく仕様)）。同じ tmux ソケットに人が `attach` すれば、これらをライブで覗ける（[人が覗く](#人が覗く)）。
 
-## クイックスタート（約60秒）
-
-Claude Code なら 1 コマンドで登録——clone もビルドも不要、`npx` が毎回取得して起動する:
-
-```bash
-claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
-```
+## 最初の実行（約60秒）
 
 Claude Code を再起動して、接続を確認:
 
@@ -170,7 +233,7 @@ npm i -g aiterm-mcp
 claude mcp add --scope user --transport stdio aiterm -- aiterm-mcp
 ```
 
-`~/.claude.json` に登録され、初回に承認プロンプトが出る。**他の MCP クライアント**（Cursor / Cline / Claude Desktop …）でも同様に動くはず——stdio で `npx -y aiterm-mcp`（または `aiterm-mcp`）を起動するだけ。**Node ≥ 18** と **tmux** が必要——[要件](#要件)参照。
+`~/.claude.json` に登録され、初回に承認プロンプトが出る。クライアント別のJSONは[MCPクライアントへ導入](#mcpクライアントへ導入)を参照。
 
 ## ヘッドレス: 端末に人が居ない
 

package/README.md

@@ -1,3 +1,5 @@
+> **Drive Codex CLI's interactive TUI from Claude Code — including slash commands and skills such as [`$imagegen`](https://learn.chatgpt.com/docs/image-generation#generate-or-edit-an-image) — through MCP.**
+
 <p align="center">
   <img src=".github/og.svg" alt="aiterm-mcp — one persistent MCP terminal your AI drives, and launches other coding agents (Claude/Codex/Grok/Composer) into (tmux-backed stdio MCP server)" width="100%">
 </p>
@@ -6,6 +8,7 @@
 
 [![CI](https://github.com/kitepon-rgb/aiterm-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/kitepon-rgb/aiterm-mcp/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/aiterm-mcp.svg)](https://www.npmjs.com/package/aiterm-mcp)
+[![weekly downloads](https://img.shields.io/npm/dw/aiterm-mcp.svg)](https://www.npmjs.com/package/aiterm-mcp)
 [![node](https://img.shields.io/node/v/aiterm-mcp)](https://nodejs.org)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![install size](https://packagephobia.com/badge?p=aiterm-mcp)](https://packagephobia.com/result?p=aiterm-mcp)
@@ -20,6 +23,69 @@
 >
 > *MCP = Model Context Protocol — the open standard that lets tools like Claude Code plug capabilities into an AI.*
 
+Built and maintained by [Quo](https://x.com/QLyun35332) at kitepon.dev.
+
+## Install in your MCP client
+
+No clone or build is required. Each client launches the published package with:
+
+```bash
+npx -y aiterm-mcp
+```
+
+Requires **Node.js ≥ 18** and **tmux**. Driving Codex also requires the Codex CLI to be installed and authenticated.
+
+### Claude Code
+
+Add it for your user account:
+
+```bash
+claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
+```
+
+Or commit this as a project-scoped `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "aiterm": {
+      "command": "npx",
+      "args": ["-y", "aiterm-mcp"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add this server to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "aiterm": {
+      "command": "npx",
+      "args": ["-y", "aiterm-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Save this as `.cursor/mcp.json` for the project, or `~/.cursor/mcp.json` globally:
+
+```json
+{
+  "mcpServers": {
+    "aiterm": {
+      "command": "npx",
+      "args": ["-y", "aiterm-mcp"]
+    }
+  }
+}
+```
+
 **Factory role:** aiterm-mcp is one of the ten self-owned core products managed by
 the dotagents development factory. It owns the persistent PTY and external-agent
 execution lane; dotagents owns the cross-product installation and integration
@@ -29,14 +95,15 @@ contract.
 
 Thirteen tools: six **PTY tools** — `pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list` — to open, drive, and read one persistent terminal, four **agent launchers** — `claude_agent` / `codex_agent` / `grok_agent` / `composer_agent` — that each start another coding agent's TUI inside a fresh one, `claude_turn` for durable structured issue/recovery, `claude_approval` for correlated managed-Claude approval prompts, and `diagnostics` for safe factory readiness. The backend is **tmux**, so sessions survive even if the MCP server or the AI client restarts.
 
-**v0.19.2 was published on 2026-07-20.** The v0.19 line adds the correlated
-managed-Claude approval relay, preserves multiline shell delivery, and extends
-factory diagnostics on native Windows. The v0.18 line hardened agent dispatch
-with `submit_residue`, tmux bracketed paste, and a ready gate that rejects busy
-Codex/Claude screens. As of v0.16/0.17 a parent agent never blocks on aiterm:
+**v0.20.0 was published on 2026-07-26.** It distinguishes a non-blocking
+`aiterm-wait --timeout 0` observation (`running`, exit 5) from a real timed-out
+wait. The v0.19 line added the correlated managed-Claude approval relay,
+preserved multiline shell delivery, and extended factory diagnostics on native
+Windows. As of v0.16/0.17 a parent agent never blocks on aiterm:
 every send to an agent session is a non-blocking dispatch, completion is one
 universal `aiterm-wait` waiter whose exit codes mirror the receipt outcome
-(`0`=done / `3`=timeout, not finished / `4`=closed), and a launch with an
+(`0`=done / `3`=timeout, not finished / `4`=closed / `5`=running for a
+zero-time observation), and a launch with an
 initial prompt returns a ready-made `wait_command` in its structured receipt.
 Factory diagnostics and the local runtime-error store collect only when
 canonical dotagents config explicitly sets `collection.enabled: true`;
@@ -151,13 +218,7 @@ Nesting is just text you send in — here a Python REPL *inside* the same PTY (a
 
 The only edits to the captures above are the two `⋮` lines (a long head/tail run abbreviated for the README) and one over-long grep line truncated to fit — the `⟨…⟩` marker, the token counts, and every `is_complete` verdict are exactly what the tool printed. (Use `until: ">>>"` without a trailing space — the captured prompt is trimmed, so `">>> "` would miss and fall through to `timeout`.) While nested, pass `until` (the inner prompt) or `mark: true`, because quiescence cannot fire there by design — see [Completion detection](#completion-detection-5-layers) and [Known constraints](#known-constraints-by-design-not-bugs). A human can `attach` to the same tmux socket and watch any of this live (see [A human can watch](#a-human-can-watch)).
 
-## Quickstart (≈60 seconds)
-
-One command registers it in Claude Code — no clone, no build, `npx` fetches it each run:
-
-```bash
-claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
-```
+## First run (≈60 seconds)
 
 Restart Claude Code, then verify the connection:
 
@@ -187,7 +248,7 @@ npm i -g aiterm-mcp
 claude mcp add --scope user --transport stdio aiterm -- aiterm-mcp
 ```
 
-This registers it in `~/.claude.json`; you'll get an approval prompt the first time. **Any other MCP client** (Cursor, Cline, Claude Desktop, …) should work too — just launch `npx -y aiterm-mcp` (or `aiterm-mcp`) over stdio. Needs **Node ≥ 18** and **tmux** — see [Requirements](#requirements).
+This registers it in `~/.claude.json`; you'll get an approval prompt the first time. For client-specific JSON, see [Install in your MCP client](#install-in-your-mcp-client).
 
 ## Headless: no human at the terminal
 
@@ -326,6 +387,8 @@ As of v0.16 a parent agent **never blocks** on aiterm — there is no wait param
 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.
 
+**If your host has no completion push** (no mechanism that re-invokes the agent when a background process exits), `--timeout 0` is a one-shot check instead of a wait: it scans the event file once and returns `running` (exit `5`) when the turn is still in flight, `done` (exit `0`) when it finished, `closed` (exit `4`) when the session is gone. It is deliberately absent from the receipts and tool descriptions — a host that *does* get pushed should be woken, not poll. An unknown session name is an error, never `running`, so a typo cannot masquerade as a child that is still working.
+
 `aiterm-wait` takes no locks, never writes session state, and never dispatches — any number can run beside the MCP server and each other, and `pty_close`/concurrent sends are unaffected.
 
 ### Token reduction

package/dist/aiterm-wait-cli.js

@@ -2,14 +2,16 @@
 // aiterm-wait — agent turn 完了eventの純リーダー観測CLI。
 // 完了/timeout/close を1行のJSON receiptで返してexitする。lock・PTY・dispatch状態には一切触れない。
 // 親AIホストのバックグラウンドタスクとして起動し、exitを「観測終了の通知」として使う。
-// exit≠完了: exit code は outcome を映す（0=done / 3=timeout=未完了 / 4=closed / 1=エラー）。
+// exit≠完了: exit code は outcome を映す（0=done / 5=running=未完了 / 3=timeout=未完了 / 4=closed / 1=エラー）。
+// --timeout 0 は待たずに一度だけ観測する照会で、未完了は running（timeout と混同させない）。
 // receipt の outcome が正で、done 以外は未完了。timeout の既定は core の DEFAULT_AGENT_DONE_TIMEOUT（600秒）。
 import { fileURLToPath } from "node:url";
 import * as fs from "node:fs";
 import { AitermError, observeAgentDone } from "./core.js";
 const SESSION_RE = /^[A-Za-z0-9_-]{1,64}$/;
 const OPERATION_RE = /^sha256:[0-9a-f]{64}$/;
-const USAGE = "usage: aiterm-wait --session <name> [--cursor <event_cursor>] [--operation sha256:<64hex>] [--timeout <sec>]";
+const USAGE = "usage: aiterm-wait --session <name> [--cursor <event_cursor>] [--operation sha256:<64hex>] [--timeout <sec>]" +
+    "（--timeout 0 は待たずに一度だけ観測する照会で、未完了は outcome=running / exit 5）";
 export function parseArgs(argv) {
     let session = null;
     let operationId = null;
@@ -65,7 +67,14 @@ function emit(value) {
     process.stdout.write(JSON.stringify(value) + "\n");
 }
 // outcome → exit code。exit status しか見えないホストでも done とそれ以外を誤読できないようにする。
-const OUTCOME_EXIT_CODES = { done: 0, timeout: 3, closed: 4 };
+// Record で全 outcome を型に強制する: 語を足して対応表を直し忘れると undefined→exit 0 になり、
+// 「まだ終わっていない」が「完了」として親へ届く。その取りこぼしを compile error で止める。
+const OUTCOME_EXIT_CODES = {
+    done: 0,
+    running: 5,
+    timeout: 3,
+    closed: 4,
+};
 export async function main(argv) {
     const cmd = parseArgs(argv);
     const result = await observeAgentDone(cmd.session, {

package/dist/core.js

@@ -2938,8 +2938,10 @@ export async function observeAgentDone(name, o = {}) {
             if (scanned.event)
                 return observation("done", scanned.event);
         }
+        // timeout=0 は「待たずに一度だけ見る」照会＝未完了は失敗ではなく running。
+        // 1秒以上を指定した待機の未完了は従来どおり timeout で、待ち方の意味は変えない。
         if (performance.now() >= deadline)
-            return observation("timeout");
+            return observation(timeout === 0 ? "running" : "timeout");
         await sleep(AGENT_DONE_POLL_MS);
     }
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "aiterm-mcp",
-  "version": "0.19.3",
+  "version": "0.20.1",
   "mcpName": "io.github.kitepon-rgb/aiterm-mcp",
-  "description": "AI-driven persistent terminal as a local stdio MCP server (tmux-backed). Holds one local PTY; SSH and containers are just commands you send into it. Also launches interactive Claude/Codex/Grok/Composer agent TUIs in a persistent terminal. Token-reducing reads.",
+  "description": "Persistent tmux terminal MCP that lets Claude Code drive Codex CLI's interactive TUI, including slash commands and $imagegen. Also runs durable PTY sessions for SSH, containers, REPLs, and coding agents.",
   "keywords": [
     "mcp",
     "mcp-server",
@@ -17,11 +17,18 @@
     "ai-agent",
     "agent",
     "codex",
+    "codex-cli",
     "grok",
-    "devtools"
+    "devtools",
+    "terminal-mcp",
+    "persistent-terminal",
+    "interactive-cli"
   ],
   "license": "MIT",
-  "author": "kitepon",
+  "author": {
+    "name": "Quo / クオ (kitepon.dev)",
+    "url": "https://x.com/QLyun35332"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kitepon-rgb/aiterm-mcp.git"
@@ -37,7 +44,7 @@
     "aiterm-wait": "dist/aiterm-wait-cli.js"
   },
   "files": [
-    "dist",
+    "dist/*.js",
     "README.md",
     "LICENSE"
   ],
@@ -46,6 +53,7 @@
   },
   "scripts": {
     "build": "tsc",
+    "mcpb:build": "npm run build && node scripts/build-mcpb.mjs && npm ci --omit=dev --ignore-scripts --no-audit --no-fund --prefix dist/mcpb-stage/server && npx --yes @anthropic-ai/mcpb@2.1.2 validate dist/mcpb-stage/manifest.json && npx --yes @anthropic-ai/mcpb@2.1.2 pack dist/mcpb-stage dist/aiterm-mcp.mcpb",
     "prepublishOnly": "npm run build",
     "start": "node dist/index.js",
     "test": "npm run build && node --test test/*.test.mjs"