aiterm-mcp: Instructions file for Codex

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を制御せず、通常利用の必須依存でもない。

現行契約

• 導入後の正規入口はaiterm-setup。依存準備、MCP端末の実行、検出したAIのユーザー登録と読戻しを所有する。 npm lifecycleからは設定を変更せず、外部工場の設定補完を前提にしない。
• 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しない。
• 公開面は19 tools。PTY 7、標準agent_launch 1、deprecated互換launcher 3、agent_models、 agent_configure、agent_goal、agent_auth、agent_approval、claude_turn、claude_approval、diagnosticsである。
• pty_listは明示した非秘密envキーだけを照会し、pty_observeはpaneとharnessの生存・native PID・ 状態・活動を区別する。取得不能はnull／unknownで返し、生argvと画面本文を観測receiptへ出さない。
• trust_project:trueのlaunchはpromptなしでも既知の起動準備とharness生存を確認する。 初手の未送信・送信済み未確認・開始確認を区別し、終了したharnessの残画面へ送信しない。
• agent_launchはharnessとmodelを別軸にする。harnessはagent loop、認証、hook、session、 transcriptを所有し、modelはそのharness上で選ぶ。ComposerはCursorのmodelの一つで、harnessでもGrokのmodelでもない（cursor-cli + composer-2.5-fast）。
• 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で即返す。Codex親は公式queueへ配送し、macOS・WindowsのSteer選択時は公式の同期hookで 同じターンへ取り込み、終了後は公式queueで再開する。Claude Code親は公式asyncRewake hookで 回答本文を自動配送し、親はwaiterと回答回収を呼ばない。Cursor親は公式hookのadditional_contextで 次のツール返りへ本文を差し込み、idle時はreceiptのwait_process（cursor-parent-receive）の終了で起きる。 それ以外の親はreceiptのwait_processを別processとして起動し、 outcomeを判定してpty_read(agent_transcript:true)またはclaude_turn recoverで回収する。 親自身のturnをforeground waiterで止めず、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を保存・公開しない。
• BugHubへの報告は、利用者がaiterm-runtime-errors reporting enableで明示して有効にし、かつ合鍵のファイルがある端末だけが行う。 宛先は合鍵のファイルから読み、Aitermの中に書かない。送るのは別processで、MCP processは通信しない。定期的な見張りは置かず、 試験（node:testの子）からは送らない。受け取り済みにするのは、応答の署名まで確かめた時だけ（ADR 0079）。
• 実行時エラーとして記録するのは、Aitermがその端末で動く前提が欠けた時の3種類だけ（PTYの依存、出力の置き場、AIのCLIの起動）。 通信の失敗（別端末へのSSH、AIのCLIとサービスの間、BugHubへの送信）、取消、待ちの時間切れは記録せず、呼んだ側へ理由の分かる返りで返す。 重さは、エラーの値や回数ではなく、起きた時の実害と自力で戻るかで決める。種類を足す時の決まりはADR 0102。