aiterm-mcp 0.29.12 → 0.29.13

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.29.13] - 2026-09-01
+
+### Added
+
+- Add optional `throughline_supplement_file` to `agent_launch` and the four legacy launcher aliases. Aiterm passes the path unchanged to `throughline handoff-context`; Throughline alone reads, validates, scopes, and budgets the long-term-memory/RAG supplement.
+
 ## [0.29.12] - 2026-09-01
 
 ### Changed
@@ -1420,7 +1426,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.12...HEAD
+[Unreleased]: https://github.com/kitepon/aiterm-mcp/compare/v0.29.13...HEAD
+[0.29.13]: https://github.com/kitepon/aiterm-mcp/compare/v0.29.12...v0.29.13
 [0.29.12]: https://github.com/kitepon/aiterm-mcp/compare/v0.29.11...v0.29.12
 [0.29.11]: https://github.com/kitepon/aiterm-mcp/compare/v0.29.10...v0.29.11
 [0.29.10]: https://github.com/kitepon/aiterm-mcp/compare/v0.29.9...v0.29.10

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.12** · 動作対象は Linux · WSL2 · macOS · Windows ネイティブ · MIT · [変更履歴](CHANGELOG.md)。
+**状態:** 開発継続中 · 現行公開版 **v0.29.13** · 動作対象は Linux · WSL2 · macOS · Windows ネイティブ · MIT · [変更履歴](CHANGELOG.md)。
 
 ### 更新と巻き戻し
 
@@ -229,7 +229,8 @@ GrokのcredentialをAitermがlock、検査、書換えすることはない。
 portable forkは任意である。`throughline_source_session`を使う場合、`prompt`は必須の新ミッションとなり、
 `launch_operation_id`とは併用できない。aitermは`THROUGHLINE_BIN`、次に`PATH`からThroughlineを解決し、
 `throughline handoff-context --session <id> --json`のcontextを固定区切りとミッションの前へそのまま置く。
-この経路だけ`throughline >= 0.9.0`が必要で、元sessionのDB所属は変わらない。引数省略時には
+任意の`throughline_supplement_file`はThroughline 0.10.8以降を必要とし、`--supplement-file <path>`として内容を読まずにそのまま渡し、
+project束縛・検証・予算配分はThroughlineだけが所有する。この経路だけ`throughline >= 0.9.0`が必要で、元sessionのDB所属は変わらない。引数省略時には
 Throughline自体が不要である。
 
 エージェント間の隠れたプロトコルは無い。起動したharnessは利用者がattachできるもう1本の永続sessionであり、MCPクライアントが通常のPTY操作で駆動する。
@@ -408,7 +409,7 @@ aiterm は同じ核心の洞察——端末を出会いの場にする——を
 | `pty_key` | 制御キーを送る | `session_id`, `key`（`C-c`/`Enter`/`Up`…） |
 | `pty_close` | 冪等に閉じ、`closed` / `already_closed`を返す | `session_id` |
 | `pty_list` | セッション一覧（agent行は正規`harness=<id>`と互換`agent=<kind>`を含む） | （なし） |
-| `agent_launch` | harnessとmodelを別軸で選ぶ正規agent起動入口 | `harness`, `prompt?`, `model?`, `reasoning_effort?`, `cwd?`, `write_scope?` |
+| `agent_launch` | harnessとmodelを別軸で選ぶ正規agent起動入口 | `harness`, `prompt?`, `model?`, `reasoning_effort?`, `cwd?`, `write_scope?`, `throughline_source_session?`, `throughline_supplement_file?` |
 | `agent_steer` | 実行中のCodex／Grok turnへtextを差し込む。idleなら送信せず`idle`を返す | `session_id`, `text` |
 | `claude_agent` / `codex_agent` / `grok_agent` / `composer_agent` | deprecated互換alias | 旧launcher引数 |
 | `agent_configure` | 起動中のClaude／Codex／Grok／Composer／Cursorを再起動せずmodel／effort変更 | `session_id`, `model?`, `reasoning_effort?` |
@@ -443,6 +444,7 @@ consumer は `aiterm-runtime-errors snapshot` を読み、durable ingestion 後
 handoff contextを前置きできる。この任意経路は`throughline >= 0.9.0`を必要とし、
 `launch_operation_id`とは併用不可で、元sessionのDB所属を変更しない。Throughlineは
 `THROUGHLINE_BIN`、次に`PATH`から解決し、不在・不正・空のexportはPTY作成前に明示失敗する。
+任意の`throughline_supplement_file`はThroughline 0.10.8以降と`throughline_source_session`を必要とし、Aitermは内容を解釈せずThroughlineへ渡す。
 
 エージェントの回答が画面tailより長ければ、`pty_read({ agent_transcript:true })`で再promptなしに全文回収する。既存の人間向けcontentは診断suffixを維持し、機械呼出し側は`aiterm.pty-read-result.v1`の`structuredContent.text`から回答本文だけを取得する。Claudeはlaunch相関Stop hook、Codexは通常rollout、Grokは最後の実user行以後の最後の空でないassistantメッセージだけ、Cursorはlaunch IDでbindした通常agent transcriptから同じturnを回収する。
 

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.12** · 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.29.13** · 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
 
@@ -256,7 +256,9 @@ Portable fork is optional. When `throughline_source_session` is present, `prompt
 new mission and `launch_operation_id` cannot be combined with it. aiterm resolves Throughline via
 `THROUGHLINE_BIN` and then `PATH`, runs `throughline handoff-context --session <id> --json`, and
 places its returned context before a fixed separator and the mission. This route requires
-`throughline >= 0.9.0`; it reads the source memory without changing that database's session
+`throughline >= 0.9.0`; `throughline_supplement_file` requires Throughline 0.10.8 or later. Aiterm appends
+`--supplement-file <path>` without reading or interpreting the file. Throughline owns its project
+binding, validation, and shared context budget. The route reads source memory without changing database session
 ownership. No Throughline dependency is needed when the field is omitted.
 
 Harness adapters translate `model` and `reasoning_effort` into each CLI's public controls. Explicit Grok models are checked against `grok models`; Cursor combines a base model such as `gpt-5.6-luna` with a separate effort such as `high`, checks the resulting current catalog ID, and uses Cursor's standard model picker for in-session changes. Missing models are errors, with no cache, retry, or fallback. Claude adds only launch-local Stop-hook settings, Codex reads its normal rollout store, Grok reads its normal session event/history, and Cursor binds its normal agent transcript with the launch ID. Pass an absolute `cwd`; `~` is not expanded.
@@ -439,7 +441,7 @@ On top of that sits a productized layer a raw tmux bridge doesn't have: **token-
 | `pty_key` | Send a control key | `session_id`, `key` (`C-c`/`Enter`/`Up`…) |
 | `pty_close` | Close idempotently; return `closed` / `already_closed` | `session_id` |
 | `pty_list` | List sessions (agent rows carry canonical `harness=<id>` plus compatibility `agent=<kind>`) | (none) |
-| `agent_launch` | Canonical agent launch; harness and model are independent | `harness`, `prompt?`, `model?`, `reasoning_effort?`, `cwd?`, `write_scope?` |
+| `agent_launch` | Canonical agent launch; harness and model are independent | `harness`, `prompt?`, `model?`, `reasoning_effort?`, `cwd?`, `write_scope?`, `throughline_source_session?`, `throughline_supplement_file?` |
 | `agent_steer` | Inject text into the active Codex or Grok turn; return `idle` without sending when no turn is active | `session_id`, `text` |
 | `claude_agent` / `codex_agent` / `grok_agent` / `composer_agent` | Deprecated compatibility aliases | legacy launcher arguments |
 | `agent_configure` | Change model/effort in a running Claude, Codex, Grok, Composer, or Cursor session without restarting it | `session_id`, `model?`, `reasoning_effort?` |
@@ -473,7 +475,8 @@ The selected harness CLI must be installed and authenticated. Use each product o
 Set `throughline_source_session` together with a non-empty mission in `prompt` to prepend
 Throughline's read-only handoff context. This optional route requires `throughline >= 0.9.0`,
 cannot be combined with `launch_operation_id`, and leaves the source session's database ownership
-unchanged. Throughline is resolved through `THROUGHLINE_BIN` and then `PATH`; a missing or invalid
+unchanged. Optional `throughline_supplement_file` is passed unchanged to Throughline and requires
+`throughline_source_session` and Throughline 0.10.8 or later; Aiterm does not read or classify the supplement. Throughline is resolved through `THROUGHLINE_BIN` and then `PATH`; a missing or invalid
 export fails before the PTY exists instead of silently launching clean.
 
 When an agent's answer is longer than the on-screen tail (pane height ≈ 24 lines), callers recover it in full with `pty_read({ agent_transcript: true })`. It returns the most recently completed turn's final assistant message in plain text with no re-prompting. The existing human-readable content keeps its diagnostic suffix; machine callers read the answer alone from `structuredContent.text` in `aiterm.pty-read-result.v1`. Claude reads the bounded owner-only result captured by the launch-correlated Stop hook and verifies its digest/byte count; it never reads Claude's private transcript. Durable machine callers should use `claude_turn`: `issue` sends once, `recover` never sends, `pending` is distinct from unsafe or malformed state, and only `completed` carries the exact verified `raw_output`. Codex uses the normal rollout transcript's `task_complete.turn_id`; Grok/Composer return the last non-empty assistant message after the last real user row, excluding tool-use preambles; Cursor uses the normal agent transcript bound to the launch ID and current turn. Missing or ambiguous attribution remains an explicit error.

package/dist/agent-resolver.js

@@ -168,7 +168,10 @@ export function resolveThroughlineBin() {
     }).stdout?.split(/\r?\n/).find(Boolean) ?? null;
     return resolved && isUsableExecutableFile(resolved) ? resolved : null;
 }
-export function runThroughlineHandoffContext(bin, sessionId) {
+export function runThroughlineHandoffContext(bin, sessionId, supplementFile = null) {
+    const args = ["handoff-context", "--session", sessionId, "--json"];
+    if (supplementFile !== null)
+        args.push("--supplement-file", supplementFile);
     if (isWin && /\.(?:cmd|bat)$/i.test(bin)) {
         const ps1 = path.join(path.dirname(bin), `${path.basename(bin, path.extname(bin))}.ps1`);
         if (fs.existsSync(ps1)) {
@@ -180,14 +183,11 @@ export function runThroughlineHandoffContext(bin, sessionId) {
                 "Bypass",
                 "-File",
                 ps1,
-                "handoff-context",
-                "--session",
-                sessionId,
-                "--json",
+                ...args,
             ], { encoding: "utf8" });
         }
     }
-    return spawnSync(bin, ["handoff-context", "--session", sessionId, "--json"], {
+    return spawnSync(bin, args, {
         encoding: "utf8",
     });
 }

package/dist/core.js

@@ -2941,12 +2941,12 @@ const PORTABLE_FORK_MISSION_SEPARATOR = "\n\n---\n\n## Portable fork mission\n\n
 export function composePortableForkPrompt(context, mission) {
     return context + PORTABLE_FORK_MISSION_SEPARATOR + mission;
 }
-function portableForkPrompt(sourceSessionId, mission) {
+function portableForkPrompt(sourceSessionId, mission, supplementFile) {
     const bin = resolveThroughlineBin();
     if (!bin) {
         throw new AitermError("Throughline CLIが見つかりません。portable forkのsessionは作成していません", 2);
     }
-    const result = runThroughlineHandoffContext(bin, sourceSessionId);
+    const result = runThroughlineHandoffContext(bin, sourceSessionId, supplementFile);
     if (result.error || result.status !== 0) {
         throw new AitermError("Throughline handoff-contextの取得に失敗しました。portable forkのsessionは作成していません", 2);
     }
@@ -3243,9 +3243,16 @@ export function openAgent(kind, opts = {}) {
 export async function openAgentWithInitialPrompt(kind, opts = {}) {
     const mission = opts.prompt ?? null;
     const sourceSessionId = opts.throughline_source_session ?? null;
+    const supplementFile = opts.throughline_supplement_file ?? null;
     if (sourceSessionId !== null && !sourceSessionId.length) {
         throw new AitermError("throughline_source_sessionが空文字です", 2);
     }
+    if (supplementFile !== null && !supplementFile.length) {
+        throw new AitermError("throughline_supplement_fileが空文字です", 2);
+    }
+    if (supplementFile !== null && sourceSessionId === null) {
+        throw new AitermError("throughline_supplement_file指定時はthroughline_source_sessionが必要です", 2);
+    }
     if (sourceSessionId !== null && (mission === null || !mission.trim())) {
         throw new AitermError("throughline_source_session指定時はpromptにmissionが必要です", 2);
     }
@@ -3254,7 +3261,7 @@ export async function openAgentWithInitialPrompt(kind, opts = {}) {
     }
     const prompt = sourceSessionId === null
         ? mission
-        : portableForkPrompt(sourceSessionId, mission);
+        : portableForkPrompt(sourceSessionId, mission, supplementFile);
     if (opts.launch_operation_id != null && prompt !== null) {
         throw new AitermError("launch_operation_idはpromptなしのClaude相関launchだけで指定できます", 2);
     }

package/dist/index.js

@@ -544,7 +544,7 @@ 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, model, reasoning_effort, env_vars, cwd, session_name, launch_operation_id, write_scope } = args;
+    const { prompt, 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);
@@ -552,6 +552,7 @@ async function launchAgent(kind, args) {
         const [sid, hint, eventCursor, submitResidue] = await core.openAgentWithInitialPrompt(kind, {
             prompt: prompt ?? undefined,
             throughline_source_session,
+            throughline_supplement_file,
             model: model ?? undefined,
             reasoning_effort: reasoning_effort ?? undefined,
             env_vars,
@@ -619,6 +620,11 @@ function registerAgentTool(toolName, kind, desc) {
                 .min(1)
                 .optional()
                 .describe("同一端末のThroughline sessionから所有権を変えずに記憶を読み、promptのmissionより前へ注入する"),
+            throughline_supplement_file: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Throughline 0.10.8以降へそのまま渡すproject束縛済み長期記憶・知識の補足JSON path"),
             model: z.string().nullish().describe(agentModelDesc(kind)),
             // CLI／model側の値集合が版で変わるため公開enumでは縛らない（core側も同方針）。
             reasoning_effort: z.string().nullish().describe(agentEffortDesc(kind)),
@@ -655,6 +661,7 @@ server.registerTool("agent_launch", {
         harness: z.enum(["claude-code", "codex-cli", "grok-cli", "cursor-cli"]).describe("agent loop・session・hook・transcript・認証を所有する実行基盤"),
         prompt: z.string().nullish().describe("起動時に渡す初手プロンプト（任意）。送信後は待たずに即返る"),
         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"),
         reasoning_effort: z.string().nullish().describe("harness adapterが標準CLI表現へ変換する思考レベル。Cursorではmodel同時指定が必要"),
         env_vars: z.array(z.string()).optional().describe("現在のMCP processから継承する環境変数名"),

package/docs/DESIGN.md

@@ -21,6 +21,7 @@ Windows nativeではpsmux 3.3.8以上に保存され、MCP serverやclientの再
 標準入口`agent_launch`は`claude-code`、`codex-cli`、`grok-cli`、`cursor-cli`のharnessとmodelを別軸で選ぶ。
 harnessがagent loop、認証、hook、session、transcript、model catalogを所有する。Aitermは通常の
 project／user環境を置換せず、launch相関と完了回収に必要なstateだけを加える。
+Throughlineの補足記憶はpathを透過搬送するだけで、内容、project束縛、context予算はThroughlineが所有する。
 
 agent turnは常に非ブロックdispatchである。receiptの`event_cursor`がturn境界、`wait_process`が
 platform nativeな別process起動情報を返す。waiterは純readerで、親のforeground turnを塞がない。

package/package.json

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