aiterm-mcp AGENTS.md

AGENTS.md

aiterm-mcpで働くAIのプロジェクト正典。利用者向け公開契約はREADME／ 日本語README、設計はDESIGN、文書地図は docs overview、公開工程はRELEASEを正とする。 版別の変更と完了証拠はCHANGELOG、docs/adr/、docs/archive/に置き、 このファイルへrelease日誌を複製しない。

製品と所有境界

本repositoryはAitermを単独で開発・導入・運用・診断・復旧・更新・releaseできる状態を所有する。 install、設定、PTY/session、agent相関state、schema、migration、diagnostics、recovery、公開物の正本は このrepository内に置く。dotagentsは任意の工場統合、host wire、製品間compatibilityと統合受入を担うが、 Aitermの製品判断・実行・releaseを制御せず、通常利用の必須依存でもない。

現行契約

• Node.js 18以上。POSIXはtmux、Windows nativeはpsmux 3.3.8以上＋Git for Windowsを使う。 Windowsの対話shellはPowerShell 7だけとし、Windows PowerShell 5.1、PowerShell 6、cmd.exe、 WSL bridgeへfallbackしない。
• 公開面は16 tools。PTY 6、標準agent_launch 1、deprecated互換launcher 4、 agent_configure、agent_steer、claude_turn、claude_approval、diagnosticsである。
• agent_launchはharnessとmodelを別軸にする。harnessはagent loop、認証、hook、session、 transcriptを所有し、modelはそのharness上で選ぶ。ComposerはGrok CLIのmodel presetである。
• launcherは直接CLIと同じ通常HOME、project／user設定、MCP、plugin、skill、permission、trust、 memory、historyを使う。Aitermはlaunch相関、完了event、bounded result、cleanup metadataだけを所有し、 credential／設定をcopy、snapshot、filterしない。
• agentへの送信は非ブロックdispatchで即返す。完了はreceiptのwait_processを別processとして起動し、 outcomeを判定する。親自身のturnをforeground waiterで止めない。回答回収は pty_read(agent_transcript:true)またはclaude_turn recoverを使い、timeout後にpromptを再送しない。
• 公開復旧はpty_listで対象を確認し、該当sessionをpty_closeして同じIDで作り直す。 公開toolに全session一括停止はない。core.killAll()は内部test cleanupであり、利用者へ案内しない。
• runtime error storeは製品所有のlocal stateで、network I/Oを持たない。工場reporter configによる収集は 明示opt-inの任意adapterであり、未設定でもPTY／agent／diagnosticsは単独で動く。prompt、transcript、 path、credential、生stack／stderrを保存・公開しない。

コード所有

• src/index.ts: MCP toolとschema。
• src/core.ts: PTY、入出力整形、出力削減、完了検出、harness共通進行。
• src/harnesses/: Claude／Codex／Grok／Cursor固有の起動、ready、完了、transcript、catalog。
• src/agent-shared.ts／src/state-root.ts: harness中立の相関state。
• src/tmux-runtime.ts／src/psmux-send-worker.ts／src/agent-resolver.ts: OS・multiplexer差。
• src/runtime-error-*.ts: 製品所有のoffline error aggregate。
• src/rtk.ts: 自前reducer。pytestはrtk 0.42.0と一致し、FAILED理由全文保持だけ意図的に異なる。
• prototype/python/: 旧MVPとreducer移植元。参照専用。