# AGENTS.md

aiterm-mcpで働くAIのプロジェクト正典。利用者向け公開契約は[README](README.md)／
[日本語README](README.ja.md)、設計は[DESIGN](docs/DESIGN.md)、文書地図は
[docs overview](docs/00_overview.md)、公開工程は[RELEASE](docs/RELEASE.md)を正とする。
版別の変更と完了証拠は[CHANGELOG](CHANGELOG.md)、`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。

## コード所有

- `src/setup.ts`／`src/setup-cli.ts`: 導入の順序・公開結果。`src/setup-platform.ts`: OSと公式導入経路。
  `src/setup-integrations.ts`: AI別のMCP登録と読戻し。
- `src/index.ts`: MCP toolとschema。
- `src/pty-output.ts`: 制御文字除去と表示縮約。coreの既存exportを保ち、入力・完了判定・RTK意味別縮約と分離する。
- `src/core.ts`: PTY、入出力進行、完了検出、harness共通進行。入力欄への投入（貼付→反映の確認→Enter）は
  `submitAgentComposerText`の1つの順序を、起動時prompt・dispatch・差し込みの送信口が共有する。席へ渡すAitermの環境変数は
  `agentEnvEntries`の1つの一覧から、POSIXの前置きとWindowsのPowerShell行を作る。
- `src/agent-model-ui.ts`／`src/harnesses/*-configure.ts`: Claude/Codexのmodel選択UI。coreが既存native作用を供給し、排他・goal・記録はcoreに残す。[設定図](docs/architecture/model-configuration.md)。
- `src/agent-screen-observation.ts`: sampleと時計を受け取るTUI準備・入力残存・画面安定の観測。打鍵やmetadata更新はcoreが持つ。
  harness別の画面の読みの振り分け（`agentPaneObservation`・`isAgentTuiBusy`）もこのmoduleだけが持ち、coreは`kind`を渡して呼ぶ。
- `src/harnesses/`: Claude／Codex／Grok／Cursor／Antigravity固有の起動、ready、完了、transcript、catalog。
  `src/model-catalog.ts`: `agent_models`のharness中立の形、effortの並び、形式検証。取得口と変換はadapterが持つ。
- `src/harnesses/grok.ts`: Grok／Composerのfolder trust、入力受付、sandbox起動拒否の検出と原因付きエラーも所有する。
  `src/core.ts`は該当harnessで判定を呼び出すだけとし、CLIの拒否文言や設定の修復処理を持たない。
- `src/agent-shared.ts`／`src/state-root.ts`: harness中立の相関state。
- `src/agent-resume-diagnostic.ts`: 世代別の最初に保存できた復帰失敗。固定enum/型付きcodeのみ、既runtime集計・外部報告とは別。[lifecycle図](docs/architecture/lifecycle-state-ownership.md)。
- `src/agent-metadata-reader.ts`: 起動記録の選択・旧形式/5harnessの検証と投影。書込・進行・表示の欠測cacheは持たない。機能図は[読取の責務](docs/architecture/metadata-reader.md)。
- `src/parent-delivery.ts`: 子の完了観測・回答保存・配送進行とreceipt投影。
  `src/parent-delivery-record.ts`: 既存記録schema・読取検証・回答本文形式。[責務と接続](docs/architecture/parent-delivery.md)。
  `src/codex-parent-receiver.ts`: Codex親の識別と公式キューの受信口。アプリが寝かせた会話は、共通パッケージの見張りが会話を開かせて起こす（ADR 0108）。
  `src/codex-parent-hooks.ts`／`src/codex-parent-hook.ts`／`src/codex-hook-state.ts`: 同一ターンへの公式hook配送と所有記録。
  `src/setup-codex-hooks.ts`: hookの選択導入、公式APIでの承認・読戻し、旧中継からの移行。
  `src/codex-relay-arguments.ts`／`src/codex-relay-stdio.ts`／`src/codex-relay-setup.ts`: 全OS共通の引数・中継・設定処理。
  その他の`src/codex-relay-*.ts`／`src/codex-stdio-relay.ts`: 公式socketの識別、接続、POSIX起動と終了の適合。
  `src/setup-codex-relay.ts`: 旧中継の互換読取り・解除と公式バイナリの検出。
  `src/windows-codex-*.ts`: Windowsの公式CLI起動、認証付き接続、native launcher、ACLと選択導入。
  `src/claude-parent-receiver.ts`／`src/claude-parent-hook.ts`: Claude親の要求相関と公式hookへの回答出力。
  `src/cursor-parent-receiver.ts`／`src/cursor-parent-hook.ts`／`src/cursor-parent-receive.ts`: Cursor親の会話束縛、公式hookへの差し込み、idle時の受け口。
- `src/tmux-runtime.ts`／`src/psmux-send-worker.ts`／`src/agent-resolver.ts`: OS・multiplexer差。
- `src/process-runtime.ts`: native process identity、親子関係、CPU時間のOS差。
- `src/parent-delivery-cli.ts`／`src/delivery-provider.ts`: ほかの製品がCodexの親への回答をAitermの親配送へ頼む入口（`aiterm-parent-delivery`）と、
  その場所の記録。製品のhookを増やさず、設定・受付・実際に届いた事を分けて返す（ADR 0098）。
- `src/delivery-wake-cli.ts`: 中継の後ろで眠っている本体を、親配送の引き取りのために起こすかの判定（`aiterm-delivery-wake`）。
  node builtinと`src/state-root.ts`だけに依存し、子processを起こさない。
- `src/runtime-error-*.ts`: 製品所有のerror aggregate。`src/runtime-error-report.ts`: BugHubへの報告（本文・署名・受領の確認・送信の頻度）。
- `src/rtk.ts`: 自前reducer。pytestとgrepはrtk 0.50.0と一致し、`FAILED`理由全文保持だけ意図的に異なる。
- `prototype/python/`: 旧MVPとreducer移植元。参照専用。

依存方向はcore → harnesses → agent-shared → runtime／errorsの一方向を保つ。harness差をcoreへ、
OS差をharnessへ戻さない。stdioはJSON-RPC通信路なのでproductionコードからstdoutへ出力しない。

## 作業規律

- 親配送の共通化は、稼働済みAitermの実装と挙動を正本として切り出す。他製品との差分はAitermへ揃え、
  Aitermの配送契約は維持する。抽出範囲と互換条件は[DESIGN](docs/DESIGN.md)の共通化設計を参照する。
- 原因を最小再現してから修理し、別経路へのfallback、retry、成功丸めで症状を隠さない。
- 変更に直結するfocused testを先に実行し、関連gate完了後に`npm test`を一度だけ行う。
- agentの認証・model catalog・設定・updateは各harness所有者の公式CLIへ委ねる。Aiterm独自の代替配布や
  credential操作を加えない。
- `.claude/settings.local.json`、`.vscode/tasks.json`、`Zone.Identifier`等の端末固有fileは触らない。
- 設計判断を変えたらDESIGNと関連ADR、公開挙動なら日英READMEとCHANGELOG、公開metadataなら
  package／server／MCPBを同じ変更で同期する。

## 文書の寿命

- currentには現行の契約、設計、運用、release手順だけを置く。
- 完了・棄却・中断・失効・置換により現行制御から外れたplan、audit、release receipt、旧promotion文書は`docs/archive/`へ移す。未解決で今も必要な作業はcurrent backlogへ移してからarchiveする。
- 同じ目的のcurrent文書を増やさず、README、DESIGN、RELEASE、CONTRIBUTING、SECURITYの既存正本へ統合する。
- `docs/adr/`と`docs/evidence/`は判断・証拠の履歴であり、current手順として列挙しない。
- Latticeや過去ADRが固定pathを参照する場合だけrootに短いhistory stubを残し、本文はarchiveへ置く。

## 調査資産

外部仕様を調べる前に`rag/INDEX.md`を読む。新しい一次資料は`rag/ingest.py`で取得し、front matter、
`rag/manifest.json`、INDEXを同期する。既存raw corpusは現行文言へ書き換えない。

## 検証とrelease

```bash
npm run build
npm test
```

GitHub Actionsは変更した実装の依存関係から必要なテストを選び、共通変更はmacOS native、Linux workstation、Windows nativeで実行する。依存を確定できない変更は全テストへ広げ、版番号だけの変更はLinuxの配布確認へ絞る。分類と検証範囲の詳細は[RELEASE](docs/RELEASE.md)を正とする。
製品の受入コマンドと3環境runner契約は、このrepositoryの`.github/workflows/product-full-ci.yml`が所有する。
dotagentsの工場CIは製品gateの結果を横断受入へ使えるが、製品workflowの正本ではない。
releaseは[docs/RELEASE.md](docs/RELEASE.md)のmain祖先gate、3環境CI、npm provenance、GitHub Release＋
MCPB、Official MCP Registry、公開package smokeまでを満たす。

remote入力のschema/type/説明は`src/remote-contract.ts`が所有し、`src/remote.ts`は既存名を再exportする。SSH中継・資格memory・接続状態はremoteが持つ。[接続図](docs/architecture/remote.svg)。