aiterm-mcp 0.4.1 → 0.7.1

package/README.ja.md

@@ -16,7 +16,7 @@
 >
 > *MCP = Model Context Protocol — Claude Code のようなツールが AI に機能を差し込むためのオープン標準。*
 
-`pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list` の 6 ツールだけ。バックエンドは tmux なので、MCP サーバや AI クライアントが再起動してもセッションは生き残る。
+`pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list` の PTY 6 ツールに加え、同じ永続端末の中にコーディングエージェントの TUI を起動する**対話エージェント起動 3 ツール**（`codex_agent` / `grok_agent` / `composer_agent`）。バックエンドは tmux なので、MCP サーバや AI クライアントが再起動してもセッションは生き残る。
 
 **状態:** 開発継続中 · 動作対象は Linux · WSL2 · macOS · Windows ネイティブ · MIT · [変更履歴](CHANGELOG.md)。
 
@@ -83,7 +83,7 @@ claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
 Claude Code を再起動して、接続を確認:
 
 ```bash
-/mcp        # aiterm が connected・6 ツール公開、と出る
+/mcp        # aiterm が connected・9 ツール公開、と出る
 ```
 
 最初のセッション — 4 回の呼び出しで、1 個の永続端末:
@@ -111,7 +111,7 @@ claude mcp add --scope user --transport stdio aiterm -- aiterm-mcp
 
 ```mermaid
 flowchart LR
-    AI["AI / MCP client"] -->|"pty_send"| S["aiterm-mcp<br/>stdio MCP · 6 tools"]
+    AI["AI / MCP client"] -->|"pty_send"| S["aiterm-mcp<br/>stdio MCP · 9 tools"]
     S -->|"pty_read<br/>token-reduced"| AI
     S -->|"tmux send-keys<br/>capture-pane"| P["one local PTY<br/>tmux · persistent"]
     P -->|"ssh · docker · repl"| R["nested<br/>remote · container · REPL"]
@@ -148,6 +148,18 @@ flowchart LR
 | `pty_close` | セッションを閉じる | `session_id` |
 | `pty_list` | セッション一覧 | （なし） |
 
+### 対話エージェント起動ツール
+
+各ツールは特定ベンダーの対話型コーディングエージェント TUI を新しい永続 PTY の中に起動し、`session_id` を返す。以後は他のセッションと同様に `pty_read` / `pty_send` で操作する。モデルごとに 1 ツール＝ツール名を見ればどのモデルか分かる。
+
+| ツール | 起動するもの | 主な引数 |
+| --- | --- | --- |
+| `codex_agent` | Codex CLI（OpenAI・モデルは CLI の既定） | `prompt?`, `reasoning_effort?`, `cwd?`, `session_name?` |
+| `grok_agent` | Grok Build の `grok-build` モデル（xAI） | `prompt?`, `reasoning_effort?`（`low`/`medium`/`high`/`xhigh`/`max`）, `cwd?`, `session_name?` |
+| `composer_agent` | Grok Build の `grok-composer-2.5-fast` モデル（xAI） | `grok_agent` と同じ |
+
+各ベンダーの CLI が導入・認証済みであること（`codex_agent` は `codex`、Grok 系 2 つは `grok`）。バイナリは `CODEX_BIN` / `GROK_BIN` → `~/.local/bin/codex` / `~/.grok/bin/grok` → `PATH` の順で解決する。前提はすべて**セッション作成前に検証**する——不正な `reasoning_effort`・CLI 不在・実在しない `cwd` は明示エラーになり、セッションの残骸を残さない。
+
 ### 完了検出（4 層）
 
 `pty_read({ wait: true })` は、プロセス終了 / `until` 正規表現一致 / 出力静止 ∧ シェル復帰（quiescence）/ timeout の 4 層で「コマンドが終わったか」を判定する。ネスト中（SSH 先）はシェル復帰判定が効かないので `until` でプロンプトを指定すると綺麗に判定できる。

package/README.md

@@ -16,7 +16,7 @@
 >
 > *MCP = Model Context Protocol — the open standard that lets tools like Claude Code plug capabilities into an AI.*
 
-Just six tools — `pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list`. The backend is **tmux**, so sessions survive even if the MCP server or the AI client restarts.
+Six PTY tools — `pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list` — plus three interactive **agent launchers** (`codex_agent` / `grok_agent` / `composer_agent`) that start a coding-agent TUI inside that same persistent terminal. The backend is **tmux**, so sessions survive even if the MCP server or the AI client restarts.
 
 **Status:** actively maintained · runs on Linux · WSL2 · macOS · native Windows · MIT · see the [CHANGELOG](CHANGELOG.md).
 
@@ -83,7 +83,7 @@ claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
 Restart Claude Code, then verify the connection:
 
 ```bash
-/mcp        # aiterm should show as connected, exposing 6 tools
+/mcp        # aiterm should show as connected, exposing 9 tools
 ```
 
 Your first session — four calls, one persistent terminal:
@@ -111,7 +111,7 @@ This registers it in `~/.claude.json`; you'll get an approval prompt the first t
 
 ```mermaid
 flowchart LR
-    AI["AI / MCP client"] -->|"pty_send"| S["aiterm-mcp<br/>stdio MCP · 6 tools"]
+    AI["AI / MCP client"] -->|"pty_send"| S["aiterm-mcp<br/>stdio MCP · 9 tools"]
     S -->|"pty_read<br/>token-reduced"| AI
     S -->|"tmux send-keys<br/>capture-pane"| P["one local PTY<br/>tmux · persistent"]
     P -->|"ssh · docker · repl"| R["nested<br/>remote · container · REPL"]
@@ -148,6 +148,18 @@ One PTY is the only primitive. Everything else — SSH, containers, REPLs — is
 | `pty_close` | Close a session | `session_id` |
 | `pty_list` | List sessions | (none) |
 
+### Interactive agent launchers
+
+Each launcher starts a specific vendor's interactive coding-agent TUI inside a fresh persistent PTY and returns its `session_id` — from there you drive it with plain `pty_read` / `pty_send`, exactly like any other session. One tool per model, so the tool name itself tells you which model you get.
+
+| Tool | Launches | Key args |
+| --- | --- | --- |
+| `codex_agent` | Codex CLI (OpenAI; the CLI's default model) | `prompt?`, `reasoning_effort?`, `cwd?`, `session_name?` |
+| `grok_agent` | Grok Build, model `grok-build` (xAI) | `prompt?`, `reasoning_effort?` (`low`/`medium`/`high`/`xhigh`/`max`), `cwd?`, `session_name?` |
+| `composer_agent` | Grok Build, model `grok-composer-2.5-fast` (xAI) | same as `grok_agent` |
+
+The vendor CLI must be installed and authenticated (`codex` for `codex_agent`; `grok` for both Grok tools). aiterm resolves the binary via `CODEX_BIN` / `GROK_BIN`, then `~/.local/bin/codex` / `~/.grok/bin/grok`, then `PATH`. All prerequisites are validated **before** a session is created — an invalid `reasoning_effort`, a missing CLI, or a nonexistent `cwd` fails with an explicit error and leaves no session behind.
+
 ### Completion detection (4 layers)
 
 `pty_read({ wait: true })` decides "is the command done?" via four layers: process exit / `until` regex match / output is quiescent ∧ the shell is back (quiescence) / timeout. While nested (inside SSH), the "shell is back" check cannot fire, so pass `until` with the remote prompt for a clean decision.

package/dist/core.js

@@ -11,7 +11,7 @@ import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
-import { createHash } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import * as rtk from "./rtk.js";
 // Windows ネイティブには tmux が無い。その場合だけ全 tmux 呼び出しを WSL 経由へ橋渡しする
 // （POSIX = Linux/WSL2/macOS は従来どおり tmux を直接叩く）。
@@ -305,6 +305,11 @@ function autoName() {
         i++;
     return `t${i}`;
 }
+// 衝突リトライ用の乱数名。線形 t{i} は高並行だと全員が同じ「最小の空き番号」を見て衝突し続ける
+// （TOCTOU）ため、2回目以降は 1600万通りの nonce 名に切り替えてリトライ上限内で実質確実に確保する。
+function nonceName() {
+    return `t-${randomBytes(3).toString("hex")}`;
+}
 function captureScreen(name, lines) {
     const args = ["capture-pane", "-p", "-J", "-t", name];
     if (lines)
@@ -417,26 +422,49 @@ function rtkRewrite(text) {
 // ---------------------------------------------------------------- 操作（return で返す / 失敗は AitermError）
 export function openSession(name, shell = "bash") {
     fs.mkdirSync(SOCKDIR, { recursive: true });
-    const nm = name || autoName();
-    assertSessionName(nm);
-    if (sessionExists(nm))
-        throw new AitermError(`session '${nm}' は既に存在します（list で確認）`, 2);
     // macOS の /bin/bash は 3.2 で、起動時に zsh 移行バナーを出して最初の read を汚す。darwin かつ bash の
     // ときだけ -e で環境変数を渡して抑止する。-e は tmux>=3.2 が必要だが macOS の Homebrew tmux は常に該当。
     // （古い tmux<3.2 が残る Linux/WSL で -e を渡すと new-session が落ちるため、darwin 限定にする。）
     const banner = process.platform === "darwin" && path.basename(shell) === "bash"
         ? ["-e", "BASH_SILENCE_DEPRECATION_WARNING=1"]
         : [];
-    const r = tmux("new-session", "-d", "-s", nm, ...banner, "-f", "/dev/null", shell);
-    if (r.code !== 0)
-        throw new AitermError("tmux new-session 失敗: " + r.stderr.trim(), 2);
+    // 並行性対策: 複数エージェントが同時に名前なし open すると autoName が同じ t{i} を返し得る（TOCTOU）。
+    // 自動採番は初回のみ読みやすい t{i}、衝突したら乱数 nonce 名でリトライする（線形リトライは高並行で
+    // 全員が同じ空き番号に殺到してスケールしない）。明示名は既存ならエラー（呼び手責任＝意図的共有と区別）。
+    const explicit = !!name;
+    let nm = name || autoName();
+    assertSessionName(nm);
+    for (let attempt = 0;; attempt++) {
+        if (attempt >= 20)
+            throw new AitermError("openSession: 自動採番のリトライ上限（tmux new-session が重複以外で失敗し続けている可能性）", 2);
+        if (sessionExists(nm)) {
+            if (explicit)
+                throw new AitermError(`session '${nm}' は既に存在します（list で確認）`, 2);
+        }
+        else {
+            const r = tmux("new-session", "-d", "-s", nm, ...banner, "-f", "/dev/null", shell);
+            if (r.code === 0)
+                break;
+            // 自動採番かつ「重複名」由来の失敗（他エージェントが同名を先に取った）なら次名でリトライ。
+            const dup = /duplicate|already exists/i.test(r.stderr);
+            if (explicit || !dup)
+                throw new AitermError("tmux new-session 失敗: " + r.stderr.trim(), 2);
+        }
+        nm = nonceName();
+        assertSessionName(nm);
+    }
     fs.closeSync(fs.openSync(logpath(nm), "a")); // touch
     // pipe-pane の引数は tmux 内部の /bin/sh -c で再解釈される（argv ではない）。パスは単一引用符で包み、
     // パス自身の ' は '\'' イディオムでエスケープする（名前は検証済みだが、Windows ユーザー名 O'Brien 等が
     // 一時パスに ' を持ち込み redirect を壊すのを防ぐ。空白対策も兼ねる）。Windows は WSL から見える /mnt/c 形へ。
     const pipeTarget = isWin ? toWslPath(logpath(nm)) : logpath(nm);
     const quoted = `'${pipeTarget.replace(/'/g, "'\\''")}'`;
-    tmux("pipe-pane", "-t", nm, "-o", `cat >> ${quoted}`);
+    const pr = tmux("pipe-pane", "-t", nm, "-o", `cat >> ${quoted}`);
+    if (pr.code !== 0) {
+        // 配管に失敗した session は pty_read が永遠に空を返す＝成功を装わない。作った session を片付けて明示エラー。
+        tmux("kill-session", "-t", nm);
+        throw new AitermError("tmux pipe-pane 失敗（出力ログを配管できないため session を破棄）: " + pr.stderr.trim(), 2);
+    }
     writeOffset(nm, 0);
     return [nm, attachHint(nm)];
 }
@@ -564,3 +592,101 @@ export function killAll() {
     tmux("kill-server");
     return "killed all sessions on this socket";
 }
+function resolveAgentBin(kind) {
+    const home = process.env.HOME ?? os.homedir();
+    const [envVar, rel, name] = kind === "codex"
+        ? ["CODEX_BIN", [".local", "bin", "codex"], "codex"]
+        : ["GROK_BIN", [".grok", "bin", "grok"], "grok"];
+    const fromEnv = process.env[envVar];
+    if (fromEnv)
+        return fromEnv;
+    const cand = path.join(home, ...rel);
+    if (fs.existsSync(cand))
+        return cand;
+    const w = spawnSync(isWin ? "where" : "which", [name], {
+        encoding: "utf8",
+        timeout: 5000,
+    });
+    if (w.status === 0 && (w.stdout ?? "").trim())
+        return w.stdout.trim().split(/\r?\n/)[0];
+    return null;
+}
+// 単一引用符で安全に包む（' は '\'' で脱出）。send は raw:true で送るため自前で quote する。
+function shq(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+function buildAgentCmd(kind, bin, effort, prompt) {
+    const parts = [shq(bin)];
+    if (kind === "codex") {
+        // codex は config override で reasoning effort（例: low/medium/high）を渡す。
+        if (effort)
+            parts.push("-c", `model_reasoning_effort=${shq(effort)}`);
+    }
+    else {
+        // grok / composer は同じ grok CLI をモデル違いで起動。effort は low/medium/high/xhigh/max。
+        parts.push("--model", kind === "composer" ? "grok-composer-2.5-fast" : "grok-build");
+        if (effort)
+            parts.push("--effort", shq(effort));
+    }
+    if (prompt)
+        parts.push(shq(prompt)); // 初手プロンプト（任意）
+    return parts.join(" ");
+}
+function agentLabel(kind) {
+    return kind === "composer"
+        ? "Grok Build(Composer)"
+        : kind === "grok"
+            ? "Grok Build(Grok)"
+            : "Codex";
+}
+// grok CLI の --effort が受ける値集合（codex は CLI 側の値集合が版で変わるため縛らない）。
+const GROK_EFFORTS = new Set(["low", "medium", "high", "xhigh", "max"]);
+export function openAgent(kind, opts = {}) {
+    const label = agentLabel(kind);
+    // 前提検証は session を作る前に全部済ませる（失敗の残骸 session を作らない）。
+    // effort → bin → cwd の順: effort 検証は CLI 不在の端末でも同じ結果になる（テスト可能性）。
+    const effort = opts.reasoning_effort ?? null;
+    if (effort && kind !== "codex" && !GROK_EFFORTS.has(effort)) {
+        throw new AitermError(`reasoning_effort '${effort}' は不正です（${label} は low/medium/high/xhigh/max）`, 2);
+    }
+    const bin = resolveAgentBin(kind);
+    if (!bin) {
+        const where = kind === "codex" ? "~/.local/bin/codex" : "~/.grok/bin/grok";
+        throw new AitermError(`${label} の CLI が見つかりません（${where} か PATH が必要）`, 2);
+    }
+    if (opts.cwd) {
+        // cd 失敗はシェル内で静かに死に、エージェント未起動のまま「起動した」と偽の成功を返してしまう。
+        // session を作る前に実在を検証して明示エラーにする。
+        let st = null;
+        try {
+            st = fs.statSync(opts.cwd);
+        }
+        catch {
+            st = null;
+        }
+        if (!st || !st.isDirectory()) {
+            throw new AitermError(`cwd '${opts.cwd}' がディレクトリとして存在しません`, 2);
+        }
+    }
+    const [sid, hint] = openSession(opts.session_name ?? null, "bash");
+    const cmd = buildAgentCmd(kind, bin, effort, opts.prompt ?? null);
+    const full = opts.cwd ? `cd ${shq(opts.cwd)} && ${cmd}` : cmd;
+    try {
+        send(sid, full, { enter: true, mark: false, force: false, rtk: false, raw: true });
+    }
+    catch (e) {
+        // 起動コマンドを投入できなかった session は空のまま残る＝残骸を作らない。片付けてから元エラーを伝える。
+        try {
+            closeSession(sid);
+        }
+        catch {
+            /* 片付け失敗より元エラーの伝達を優先 */
+        }
+        throw e;
+    }
+    return [
+        sid,
+        `${label} を session ${sid} で起動した。\n${hint}\n` +
+            `pty_read(${sid}) で TUI を読み、pty_send(${sid}, "...") で操作する（対話）。`,
+    ];
+}

package/dist/index.js

@@ -135,6 +135,45 @@ server.registerTool("pty_list", {
         return fail(e);
     }
 });
+// 対話型エージェント起動ツール（モデルごとに1つ＝ツール名/説明でどのモデルか一目で分かる）。
+// いずれも永続端末に TUI を起動し session_id を返す。以後 pty_read/pty_send で対話操作する。
+const agentEffortDesc = (grokLike) => "reasoning effort（思考レベル）。" +
+    (grokLike ? "low/medium/high/xhigh/max" : "low/medium/high 等") +
+    "。省略時は CLI 既定。";
+function registerAgentTool(toolName, kind, desc, grokLike) {
+    server.registerTool(toolName, {
+        description: desc,
+        inputSchema: {
+            prompt: z.string().nullish().describe("起動時に渡す初手プロンプト（任意）。省略で素のTUI起動"),
+            // grok/composer の effort は有限集合＝schema で拒否（session を作る前に弾く）。
+            // codex は CLI 側の値集合が版で変わるため縛らない（core 側も同方針）。
+            reasoning_effort: (grokLike ? z.enum(["low", "medium", "high", "xhigh", "max"]) : z.string())
+                .nullish()
+                .describe(agentEffortDesc(grokLike)),
+            cwd: z.string().nullish().describe("作業ディレクトリ（対象リポのルート等・任意）"),
+            session_name: z.string().nullish().describe("セッション名（省略で自動採番）"),
+        },
+    }, async ({ prompt, reasoning_effort, cwd, session_name }) => {
+        try {
+            const [sid, hint] = core.openAgent(kind, {
+                prompt: prompt ?? undefined,
+                reasoning_effort: reasoning_effort ?? undefined,
+                cwd: cwd ?? undefined,
+                session_name: session_name ?? undefined,
+            });
+            return ok(`session_id: ${sid}\n${hint}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}
+registerAgentTool("codex_agent", "codex", "【Codex (OpenAI・モデルは Codex CLI の既定)】の対話エージェント TUI を永続端末に起動する。実装・レビュー・調査を対話で回す。" +
+    "起動後は pty_read で画面を読み pty_send で操作する。reasoning_effort を引数で指定可。", false);
+registerAgentTool("grok_agent", "grok", "【Grok Build の Grok モデル (grok-build)】の対話エージェント TUI を永続端末に起動する。" +
+    "起動後は pty_read/pty_send で対話操作。reasoning_effort を引数で指定可。", true);
+registerAgentTool("composer_agent", "composer", "【Grok Build の Composer モデル (grok-composer-2.5-fast)】の対話エージェント TUI を永続端末に起動する。" +
+    "起動後は pty_read/pty_send で対話操作。reasoning_effort を引数で指定可。", true);
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiterm-mcp",
-  "version": "0.4.1",
+  "version": "0.7.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. Token-reducing reads.",
   "keywords": [