throughline 0.3.24 → 0.3.25

package/docs/THROUGHLINE_CODEX_MONITOR_IMPLEMENTATION_PLAN.md

@@ -0,0 +1,220 @@
+# Throughline Codex Monitor 実装計画
+
+Status: implemented
+Date: 2026-05-06
+
+この計画は、既存の Claude-primary monitor 経路を置き換えずに、
+`throughline monitor` へ Codex 対応を追加するためのもの。
+
+## 目的
+
+`throughline monitor` で、Claude セッションと並べて Codex セッションも
+active session として表示できるようにする。
+
+token monitor 自体はすでに Throughline の Node.js CLI であり、Claude ランタイム
+機能ではない。現時点の制約は、monitor に渡す state producer と usage reader が
+Claude 寄りになっている点にある。
+
+- Claude hooks は `~/.throughline/state/<session_id>.json` を書く。
+- Claude transcript JSONL には実測 `message.usage` token sample がある。
+- 実装前の Codex Stop hook は DB capture のみで、monitor 用 state / token usage を
+  書いていなかった。
+
+Codex 対応では、既存 monitor contract の周辺に Codex adapter / projection を追加する。
+Claude hooks、transcript parsing、slash command、baton、resume behavior は rename / 劣化
+させない。
+
+## 非目的
+
+- Claude transcript usage parsing を置き換えない。
+- `~/.codex/hooks.json` を手編集しない。hook 更新は `throughline install` に任せる。
+- Caveat / Spotter など既存 Codex hooks を削除・劣化させない。
+- Codex token count を、host 実測 sample が無いのに exact と主張しない。
+- 実測 usage が無い場合に、黙って estimate へ切り替えない。estimate は必ず表示上も
+  data 上も明示する。
+
+## 現在の contract
+
+Monitor reader:
+
+- `throughline monitor` は `src/token-monitor.mjs` に dispatch される。
+- `~/.throughline/state/` の session state files を読む。
+- 現在の state file は主に次を持つ。
+  `sessionId`, `projectPath`, `transcriptPath`, `pid`, `updatedAt`, optional `usage`
+- `state.usage` があれば monitor はそれをそのまま表示する。
+- `state.usage` が無く、`transcriptPath` があれば、
+  `src/transcript-usage.mjs` で Claude transcript usage を読む。
+- したがって `transcriptPath` は Claude transcript fallback 用の field として残す。
+  Codex rollout path を同じ field に詰めると、monitor が Claude transcript parser に
+  読ませてしまう可能性があるため、Codex 用には別 field を追加する。
+- `pid` は既存 state schema に残っているが、現行 stale 判定は `updatedAt` ベース。
+  Codex Stop hook は短命 process なので、Codex の active 判定に hook process PID を
+  意味づけない。
+
+Claude writer:
+
+- `src/turn-processor.mjs` が Claude Stop 時に state を書く。
+- 可能なら Claude transcript JSONL から usage snapshot を state に固定する。
+- `src/session-start.mjs` と `src/prompt-submit.mjs` も VSCode monitor task を
+  provision する。
+
+Codex writer:
+
+- `src/cli/codex-hook.mjs` は Codex rollout を DB capture する。
+- 実装後は `codex:<thread_id>` の monitor state も書く。
+- Codex Stop hook から VSCode monitor task を provision する。
+- Codex rollout の `event_msg` / `token_count` を monitor usage として渡す。
+
+## 提案設計
+
+### 1. Monitor state を host-aware にする
+
+state file に optional な host metadata を追加する。
+
+```json
+{
+  "sessionId": "codex:019df...",
+  "host": "codex",
+  "projectPath": "/repo",
+  "transcriptPath": null,
+  "rolloutPath": "/home/user/.codex/sessions/.../rollout.jsonl",
+  "updatedAt": 1770000000000,
+  "usage": {
+    "tokens": 12345,
+    "model": "codex",
+    "contextWindowSize": 200000,
+    "contextWindowEstimated": true,
+    "outputTokens": 0,
+    "estimated": true,
+    "source": "codex-rollout-chars-div-4"
+  }
+}
+```
+
+互換ルール:
+
+- `host` が無い既存 state は `claude` と扱う。
+- 既存 Claude state file はそのまま有効。
+- normalization は `readAllSessionStates()` 側で行い、monitor 本体が
+  `state.host ?? "claude"` を各所で繰り返さないようにする。
+
+### 2. Codex Stop hook から monitor state を書く
+
+Codex rollout capture 成功後、`runCodexStopHook` が state file を書く。
+
+- `sessionId`: `codex:<thread_id>`
+- `host`: `codex`
+- `projectPath`: payload cwd または process cwd
+- `pid`: hook process id を入れてよいが、Codex active 判定には使わない
+- `transcriptPath`: `null`。Claude transcript parser に Codex rollout を読ませない
+- `rolloutPath`: 現在の Codex rollout path が分かる場合だけ入れる
+- `updatedAt`: 現在時刻
+- `usage`: Codex usage sample が取れる場合は入れる。`token_count` が無い場合は
+  labeled estimate を入れる
+
+最初の milestone は、usage 無しでも Codex active session が monitor に出ることだった。
+実装では verified `token_count` usage または明示 estimate まで入れる。
+
+### 3. Codex usage adapter を追加する
+
+小さな adapter を追加する。候補は `src/codex-usage.mjs`。
+
+Codex data から monitor 用 usage sample を作る。
+
+優先順位:
+
+1. Codex rollout の `event_msg` / `token_count` が verified shape として存在するなら、
+   それを読む。実 rollout でこの shape を確認済み。
+2. 実測が無い場合は、active rollout text length から既存 `estimateTokens` helper で
+   `chars / 4` estimate を作る。
+
+estimate しか無い場合、usage sample は必ず次を持つ。
+
+- `estimated: true`
+- `source: "codex-rollout-chars-div-4"`
+- Codex の context window が未検証なら `contextWindowEstimated: true`
+
+monitor 表示でも compact に `est` と出す。
+
+### 4. Monitor core を小さく保つ
+
+`src/token-monitor.mjs` を Codex parser にしない。
+
+monitor は引き続き state を読んで描画するだけに寄せる。host 固有の解析は writer /
+adapter 側に置く。
+
+期待挙動:
+
+- Claude state + real usage: 既存どおり表示。
+- Codex state + estimated usage: token bar を表示し、`est` marker を付ける。
+- Codex state + usage 無し: active session として表示し、token usage は未取得扱い。
+
+### 5. VSCode monitor task provision を Codex にも接続する
+
+Codex Stop hook でも、Claude hooks と同じく
+`ensureMonitorTaskFile({ cwd, env })` を呼ぶ。
+
+これにより体験を揃える。
+
+- VSCode で project を開く。
+- Codex を使う。
+- Throughline Codex Stop hook が発火する。
+- monitor task が存在する。
+- Codex session が monitor に出る。
+
+## TODO
+
+- [x] `src/state-file.mjs` に host metadata support を追加する。
+- [x] `src/state-file.mjs` に optional `rolloutPath` support を追加する。
+- [x] `host` 無しの旧 state file を Claude として読む互換性を維持する。
+- [x] `readAllSessionStates()` で state normalization を行う。
+- [x] 旧 Claude state が読めることを test で固定する。
+- [x] Codex state が読め、project filter に乗ることを test で固定する。
+- [x] `src/token-monitor.mjs` の表示に compact な host 表示を足す。
+- [x] estimated usage sample には `est` marker を表示する。
+- [x] monitor UI は静かに保ち、説明文を増やしすぎない。
+- [x] `src/codex-usage.mjs` または同等の Codex usage adapter を追加する。
+- [x] Codex rollout JSONL に実測 token usage field があるか確認する。
+- [x] 実測 usage がある場合、verified shape だけを parse し fixture test を置く。
+- [x] 実測 usage が無い場合、active rollout text から labeled `chars / 4` estimate を作る。
+- [x] Codex usage estimate shape の test を追加する。
+- [x] Codex context window が未検証の場合は `contextWindowEstimated: true` を保持する。
+- [x] `src/cli/codex-hook.mjs` で Codex Stop hook state writing を追加する。
+- [x] monitor session id は `codex:<thread_id>` にする。
+- [x] Codex state の `pid` を active 判定に使わないことを test / docs で固定する。
+- [x] Codex state では `transcriptPath: null` とし、rollout path は `rolloutPath` に保存する。
+- [x] Codex Stop hook から `ensureMonitorTaskFile` を呼ぶ。
+- [x] Codex Stop hook が monitor state を書く test を追加する。
+- [x] Codex Stop hook が DB capture / L1 summarize を従来通り行うことを test で保つ。
+- [x] install tests で Caveat / Spotter hook preservation が壊れていないことを維持する。
+- [x] `README.md` に Claude/Codex monitor support を追記する。
+- [x] `CLAUDE.md` に Codex monitor adapter contract を追記する。
+- [x] 実装完了後、`docs/THROUGHLINE_CODEX_FIRST_ROADMAP.md` に結果を記録する。
+- [x] `CHANGELOG.md` を更新する。
+- [x] focused tests を実行する:
+  `rtk node --test src/state-file.test.mjs src/token-monitor.test.mjs src/codex-usage.test.mjs src/cli/codex-hook.test.mjs`
+- [x] full validation を実行する:
+  `rtk npm test`,
+  `rtk npm pack --dry-run --json`,
+  `rtk git diff --check`
+- [x] installed Codex-facing assets / hook behavior を変えた場合は
+  `rtk throughline install` を実行する。
+
+## 受け入れ条件
+
+- Codex Stop hook capture 後、`throughline monitor` に現在の Codex session が出る。
+- Claude monitor behavior は既存どおり。
+- Codex session は Codex と分かる。
+- Codex token usage が estimate の場合、estimate と分かる。
+- Codex context window が未検証の場合、分母も推定であることが data 上分かる。
+- Codex monitor path が Claude transcript parsing を置き換えない。
+- `~/.codex/hooks.json` の手編集は不要。
+
+## 実装順
+
+1. Host-aware state schema と互換 test。
+2. Codex Stop hook が usage 無しでも monitor state を書く。
+3. Monitor が Claude/Codex mixed state を描画する。
+4. Codex usage adapter で実測 usage または labeled estimate を追加する。
+5. Codex Stop hook から VSCode task provision を行う。
+6. docs / changelog / install / full validation を通す。