aiterm-mcp 0.29.31 → 0.30.0

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.30.0] - 2026-09-04
+
+### Added
+
+- `pty_send`（agent dispatch）、`agent_steer`、`agent_launch`に`image`（画像ファイルの絶対パスの配列）を追加した。aitermが本文末尾へ添付行を付け、Claude Code／Codex／Grok／Cursorはいずれも自分のfile読取toolでそのpathを画像として開く（実測 2026-09-04）。呼出し側が入力欄へパスを先打鍵する等のharness別手順を持つ必要を無くす。相対パス・未対応拡張子・不在fileは送信前にtyped errorで拒否し、通常PTY送信とforce送信では指定できない。
+
 ## [0.29.31] - 2026-09-04
 
 ### Fixed
@@ -1540,7 +1546,8 @@ prototype (preserved under `prototype/python/` as the porting source and referen
   `ubuntu-latest` for Node 18/20/22, publishing to npm on `v*` tags with
   provenance.
 
-[Unreleased]: https://github.com/kitepon/aiterm-mcp/compare/v0.29.31...HEAD
+[Unreleased]: https://github.com/kitepon/aiterm-mcp/compare/v0.30.0...HEAD
+[0.30.0]: https://github.com/kitepon/aiterm-mcp/compare/v0.29.31...v0.30.0
 [0.29.31]: https://github.com/kitepon/aiterm-mcp/compare/v0.29.30...v0.29.31
 [0.29.30]: https://github.com/kitepon/aiterm-mcp/compare/v0.29.29...v0.29.30
 [0.29.29]: https://github.com/kitepon/aiterm-mcp/compare/v0.29.28...v0.29.29

package/README.ja.md

@@ -153,7 +153,7 @@ runtime-error store は canonical dotagents config の `collection.enabled: true
 場合だけ収集し、既定OFF、network送信は行いません。tag起点CIのnpm provenance（OIDC Trusted
 Publishing）で公開し、GitHub Release が Official MCP Registry を再登録します。
 
-**状態:** 開発継続中 · 現行公開版 **v0.29.31** · 動作対象は Linux · WSL2 · macOS · Windows ネイティブ · MIT · [変更履歴](CHANGELOG.md)。
+**状態:** 開発継続中 · 現行公開版 **v0.30.0** · 動作対象は Linux · WSL2 · macOS · Windows ネイティブ · MIT · [変更履歴](CHANGELOG.md)。
 
 ### 更新と巻き戻し
 
@@ -189,6 +189,8 @@ pty_read(id, { wait: true })       → 削減済みの出力を読む（完了
 
 `aiterm.agent-launch-result.v1`は正規`harness`を返し、旧`provider`は互換fieldとして残す。同じ`harness`はagent dispatch、`aiterm-wait`、`agent_configure`、`pty_list`のagent行にも載り、旧vendor／provider／agent fieldは互換用に残る。Codexは通常rollout、Grok CLIは通常session event、Claudeはlaunch固有Stop hook、Cursorは通常agent transcript末尾の`turn_ended`を完了正本に使う。`pty_send`は非ブロックdispatchで、vendor別完了境界を表すopaqueな整数`event_cursor`を返し、完了通知は`aiterm-wait`を親のターンを塞がない別processで受ける。Cursorのsubmitキーはadapterが現行CLIのextended keyboard protocolへ変換する。送信textがCursorのcomposerへ残った場合は成功receiptを返さず失敗する。
 
+`agent_launch`・`pty_send`（agent dispatch）・`agent_steer`は任意の`image`（画像ファイルの絶対パスの配列。png/jpg/jpeg/gif/webp）を受ける。aitermが本文末尾へ添付行を付け、どのharnessも自分のfile読取toolでそのpathを画像として開く。呼出し側はharness別の添付手順を覚えない。不正なpathは送信前に拒否する。
+
 `agent_launch`は任意の`write_scope`も受ける。Codex／Grokのread-onlyは`--sandbox read-only`、Cursorは公式`--mode ask`で実効化する。path説明は同等CLI引数がないためdeclaration-only。
 
 ```text

package/README.md

@@ -169,7 +169,7 @@ collection is off by default and performs no network I/O. It ships via
 tag-triggered CI with npm provenance (OIDC Trusted Publishing); the GitHub
 Release re-registers the Official MCP Registry entry.
 
-**Status:** actively maintained · current public release **v0.29.31** · runs on Linux · WSL2 · macOS · native Windows (tmux on POSIX, the tmux-CLI-compatible [psmux](https://github.com/psmux/psmux) on native Windows — no WSL required) · MIT · see the [CHANGELOG](CHANGELOG.md).
+**Status:** actively maintained · current public release **v0.30.0** · runs on Linux · WSL2 · macOS · native Windows (tmux on POSIX, the tmux-CLI-compatible [psmux](https://github.com/psmux/psmux) on native Windows — no WSL required) · MIT · see the [CHANGELOG](CHANGELOG.md).
 
 ### Update and rollback
 
@@ -211,6 +211,8 @@ The same primitive hosts another agent's TUI. `agent_launch` starts a selected e
 
 The human-readable launch text is accompanied by an `aiterm.agent-launch-result.v1` structured receipt containing the canonical `harness`; the old `provider` field remains for compatibility. The same `harness` is carried by agent dispatch, `aiterm-wait`, `agent_configure`, and agent rows in `pty_list`, while their old vendor/provider/agent fields remain compatibility fields. Codex completion comes from its normal durable rollout transcript, Grok CLI from its normal session events, Claude Code from a launch-specific Stop hook settings addition, and Cursor from its normal agent transcript's terminal `turn_ended` record. Sending to any agent session is a non-blocking **dispatch** — the call returns immediately with an opaque, harness-specific integer `event_cursor`, and completion arrives via [`aiterm-wait`](#completion-push-for-parent-agents-aiterm-wait). The Cursor adapter translates submit into the current CLI's extended keyboard protocol. If submitted text remains in Cursor's composer, its dispatch fails instead of returning a successful receipt.
 
+`agent_launch`, `pty_send` (agent dispatch), and `agent_steer` accept an optional `image`: an array of absolute paths to image files (png/jpg/jpeg/gif/webp). Aiterm appends an attachment block to the prompt, and every harness opens the path with its own file-reading tool and sees the image; the caller never learns harness-specific attachment tricks. Invalid paths are rejected before anything is sent.
+
 `agent_launch` accepts an optional `write_scope`: either `"read-only"` or a human-readable description of writable paths. Codex/Grok use `--sandbox read-only`; Cursor uses its official read-only `--mode ask`. A path description remains declaration-only because these CLI launch surfaces provide no equivalent path allowlist flag.
 
 For a correlated Claude turn stopped at `Do you want to proceed?`, use `claude_approval(action: "inspect", ...)` to capture the active operation and SHA-256 screen digest, review the displayed command, then call `respond` with that exact digest and either `approve_once` or `deny`. The relay rechecks the operation and screen under the send lock, never exposes arbitrary input or permanent approval, keeps the active marker intact, and records a prompt-free owner-only receipt. `pty_send(force: true)` does not bypass this boundary.

package/dist/core.js

@@ -3049,6 +3049,37 @@ export function __testCodexConfigureChoices(screen, model, effort) {
 // v0.16.0: 親をブロックする wait 経路は廃止した。send は ready gate と submit 分離を内蔵した
 // dispatch として即返り、event_cursor（送信直前のharness完了正本境界）を receipt で返す。
 // 完了通知は aiterm-wait（--cursor で境界を渡す）、回収は pty_read / claude_turn recover が担う。
+const IMAGE_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp"]);
+/**
+ * 画像添付。Claude Code／Codex／Grok／Cursorの4 harnessは、本文に書かれた画像ファイルの絶対パスを
+ * 自分のfile読取toolで開いて画像として見る（実測 2026-09-04: 赤青の試験画像を全harnessが正しく答えた）。
+ * 入力欄へパスを先打鍵する等のharness別操作は不要であり、呼出し側にharnessの癖を覚えさせない。
+ * 添付の表現とpath検査はこの1箇所だけが所有する。検査は外部入力（呼出し側が渡すpath）の境界。
+ */
+export function attachImages(text, images) {
+    if (!images || images.length === 0)
+        return text;
+    const lines = images.map((image, index) => {
+        if (typeof image !== "string" || !path.isAbsolute(image)) {
+            throw new AitermError(`image[${index}] は画像ファイルの絶対パスで指定してください: ${String(image)}`, 2);
+        }
+        if (!IMAGE_EXTENSIONS.has(path.extname(image).toLowerCase())) {
+            throw new AitermError(`image[${index}] の拡張子に対応していません（png/jpg/jpeg/gif/webp）: ${image}`, 2);
+        }
+        let st;
+        try {
+            st = fs.statSync(image);
+        }
+        catch {
+            throw new AitermError(`image[${index}] が読めません: ${image}`, 2);
+        }
+        if (!st.isFile())
+            throw new AitermError(`image[${index}] はfileではありません: ${image}`, 2);
+        return `[aiterm 添付画像 ${index + 1}/${images.length}] ${image}`;
+    });
+    const body = text.trim().length > 0 ? text : "添付画像を確認してください。";
+    return `${body}\n\n${lines.join("\n")}\n添付画像は上のファイルを読んで確認する。`;
+}
 export async function dispatchAgentTurn(name, text, o = {}) {
     assertSessionName(name);
     const meta = loadAgentMetadata(name);

package/dist/index.js

@@ -136,6 +136,11 @@ server.registerTool("pty_send", {
             .describe("非Claude agent sessionでは自動dispatchせず素送信する。aiterm相関付きClaudeのactive turnには使えない"),
         rtk: z.boolean().default(false).describe("既知コマンドを rtk 形へ委譲して送る（rtk 不在なら素通し）"),
         raw: z.boolean().default(false).describe("送信前サニタイズを無効化"),
+        image: z
+            .array(z.string())
+            .optional()
+            .describe("添付する画像ファイルの絶対パス（png/jpg/jpeg/gif/webp）。agent session への dispatch だけで使え、" +
+            "harness別の添付手順はaitermが吸収する。通常PTY送信やforce送信では指定できない"),
     },
     outputSchema: {
         schema: z.literal("aiterm.pty-send-result.v1"),
@@ -152,7 +157,7 @@ server.registerTool("pty_send", {
         // dispatch前に行った pane 入力の回復（"fg" / "fg_stopped" / "stty_raw"）。通常送信では省略（additive）。
         pane_input_recovery: z.array(z.string()).optional(),
     },
-}, async ({ session_id, text, enter, mark, force, rtk, raw }) => {
+}, async ({ session_id, text, enter, mark, force, rtk, raw, image }) => {
     try {
         if (!force && core.isAgentSession(session_id)) {
             if (enter === false)
@@ -161,7 +166,7 @@ server.registerTool("pty_send", {
                 throw new Error("agent session への dispatch は mark:true と併用できません");
             if (rtk)
                 throw new Error("agent session への dispatch は rtk:true と併用できません");
-            const receipt = await core.dispatchAgentTurn(session_id, text, { raw });
+            const receipt = await core.dispatchAgentTurn(session_id, core.attachImages(text, image), { raw });
             const waitProcess = core.agentWaitProcess(receipt.session_id, receipt.event_cursor);
             return {
                 content: [
@@ -186,6 +191,9 @@ server.registerTool("pty_send", {
                 },
             };
         }
+        if (image && image.length > 0) {
+            throw new Error("image は agent session への dispatch（forceなし）だけで使えます。通常PTY送信では本文にpathを書いてください");
+        }
         const out = core.send(session_id, text, { enter, mark, force, rtk, raw });
         return {
             content: [{ type: "text", text: out }],
@@ -212,6 +220,7 @@ server.registerTool("agent_steer", {
     inputSchema: {
         session_id: z.string(),
         text: z.string().describe("現在のターンへ追加する文字列。UTF-8で最大64KiB"),
+        image: z.array(z.string()).optional().describe("添付する画像ファイルの絶対パス（png/jpg/jpeg/gif/webp）"),
     },
     outputSchema: {
         schema: z.literal("aiterm.agent-steer.v1"),
@@ -221,9 +230,9 @@ server.registerTool("agent_steer", {
         harness: z.enum(["codex-cli", "grok-cli"]),
         delivery: z.enum(["steered", "idle"]),
     },
-}, async ({ session_id, text }) => {
+}, async ({ session_id, text, image }) => {
     try {
-        const receipt = await core.steerAgentTurn(session_id, text);
+        const receipt = await core.steerAgentTurn(session_id, core.attachImages(text, image));
         return {
             content: [{ type: "text", text: `${receipt.delivery} ${receipt.session_id}` }],
             structuredContent: receipt,
@@ -547,13 +556,14 @@ const agentEnvironmentDesc = `通常CLIと同じHOME・cwd・project/user/local
     `delegation depth/lineage、delegation_allowed=trueを注入し、必要な追加委譲は許可する。`;
 async function launchAgent(kind, args) {
     const supportsWriteScope = kind !== "claude";
-    const { prompt, throughline_source_session, throughline_supplement_file, model, reasoning_effort, env_vars, cwd, session_name, launch_operation_id, write_scope } = args;
+    const { prompt, image, throughline_source_session, throughline_supplement_file, model, reasoning_effort, env_vars, cwd, session_name, launch_operation_id, write_scope } = args;
     try {
         if (!supportsWriteScope && write_scope !== undefined) {
             throw new core.AitermError("claude-code harnessはwrite_scopeに対応していません。指定を外してください", 2);
         }
+        const initialPrompt = image && image.length > 0 ? core.attachImages(prompt ?? "", image) : prompt ?? undefined;
         const [sid, hint, eventCursor, submitResidue] = await core.openAgentWithInitialPrompt(kind, {
-            prompt: prompt ?? undefined,
+            prompt: initialPrompt,
             throughline_source_session,
             throughline_supplement_file,
             model: model ?? undefined,
@@ -663,6 +673,7 @@ server.registerTool("agent_launch", {
     inputSchema: {
         harness: z.enum(["claude-code", "codex-cli", "grok-cli", "cursor-cli"]).describe("agent loop・session・hook・transcript・認証を所有する実行基盤"),
         prompt: z.string().nullish().describe("起動時に渡す初手プロンプト（任意）。送信後は待たずに即返る"),
+        image: z.array(z.string()).optional().describe("初手プロンプトへ添付する画像ファイルの絶対パス（png/jpg/jpeg/gif/webp）"),
         throughline_source_session: z.string().min(1).optional().describe("同一端末のThroughline sessionから読み取り専用contextを初手へ注入する"),
         throughline_supplement_file: z.string().min(1).optional().describe("Throughline 0.10.8以降へそのまま渡すproject束縛済み長期記憶・知識の補足JSON path"),
         model: z.string().nullish().describe("harnessが選ぶモデル。provider名ではなくlive catalog上のmodel ID"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiterm-mcp",
-  "version": "0.29.31",
+  "version": "0.30.0",
   "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": [