# rig 参照設計の導入実装方針

## 目的

`llm_worker_rs` の既存方針（Timeline中心、Worker主導）を維持しながら、`rig` 由来で有効だった設計を段階導入する。

対象は以下の5項目。

1. Tool 実行を `ToolServer` 的に分離する
2. Hook をストリーミング粒度まで拡張する
3. Typed output（構造化出力）の第一級 API 化
4. Provider 固有最適化を provider 層で吸収する
5. GenAI telemetry を標準実装にする

---

## 1. Tool 実行を `ToolServer` 的に分離する ✅

### 目的

Worker から「ツール登録・呼び出し・定義解決・動的選択」の責務を分離し、Worker は turn orchestration と hook 制御に集中させる。

### 実装状況: ✅ 完了

- `tool_server.rs` に `ToolServer` / `ToolServerHandle` を実装済み。
- `Worker` は `ToolServerHandle` を保持し、直接 `Tool` マップを持たない設計に移行済み。
- `Worker::register_tool()` は内部で `ToolServerHandle::register_tool()` を呼ぶ形に統一済み。
- ツール実行は `ToolServerHandle::call_tool(name, args)` 経由に統一済み。
- `tool_definitions_sorted()` で決定的順序のツール定義送信を実装済み。
- 単体テスト（重複登録・未登録呼び出し・ソート順）を `tool_server.rs` 内に実装済み。

### 計画との差分

- `ToolExecutor` trait 抽象は未導入。現状 `ToolServerHandle` が具象型として直接使われている。remote tool / MCP 対応時に trait 化する余地あり。

---

## 2. Hook をストリーミング粒度まで拡張する ✅

### 目的

Text/Tool delta を受けた時点でフック介入できるようにし、監査・UI 連携・早期停止を改善する。

### 実装状況: ✅ 完了

- `hook.rs` に以下の streaming 系イベント種別を追加済み:
  - `OnTextDelta` (入力: `TextDeltaContext`)
  - `OnToolCallDelta` (入力: `ToolCallDeltaContext`)
  - `OnStreamChunk` (入力: `StreamChunkContext`)
  - `OnStreamComplete` (入力: `StreamCompleteContext`)
- 戻り値は `StreamHookResult { Continue | Abort(String) | Pause }` で統一済み。
- `Worker` に個別登録 API を実装済み:
  - `add_on_text_delta_hook()`
  - `add_on_tool_call_delta_hook()`
  - `add_on_stream_chunk_hook()`
  - `add_on_stream_complete_hook()`
- `HookRegistry` に全 streaming hook のストレージを追加済み。
- `worker.rs` の stream dispatch ループ内で `BlockDelta` 受信時に各 hook を順序保証付きで呼び出し済み。
- `Abort` / `Pause` の制御線が Worker の run ループに接続済み。

### 計画との差分

- 高レベル統合 API（subscriber/DSL）は `worker_api_plan` 側で別途進行中。
- 実行順序仕様の文書化は未完了（コード上は登録順実行を実装済み）。

---

## 3. Typed output（構造化出力）の第一級 API 化 ⬚

### 目的

「テキストを返して呼び出し側で JSON parse」から脱却し、型付きレスポンスを API レベルで保証する。

### 実装状況: ⬚ 未着手

- `run_typed<T>()` API は未実装。
- `output_schema` の request builder 統合は未実装。
- エラー種別（`StructuredOutputUnsupported` / `Deserialize` / `Empty`）は未追加。

### 次のステップ

1. `output_schema` を Worker request builder に追加
2. typed 実行 API と decode ロジックを実装
3. provider capability 判定を `llm_client` 層に追加
4. エラー型とユーザー向けメッセージを整理

---

## 4. Provider 固有最適化を provider 層で吸収する 🔄

### 目的

キャッシュ、beta header、細粒度 stream 差分などの provider 特有処理を Worker から排除する。

### 実装状況: 🔄 部分的に進行

- `llm_client/providers/*` に Anthropic / OpenAI / Gemini / Ollama の provider 実装が存在する。
- `llm_client/scheme/*` に各 provider の request/events 変換が分離済み。
- Worker は provider 非依存の `Event` を Timeline 経由で処理する設計に移行済み。
- ただし `ProviderOptions` 型や capability trait は未導入。

### 次のステップ

1. provider capability trait を追加
2. 既存 provider 実装を capability 駆動へ移行
3. Worker 側に残る provider 分岐があれば削除

---

## 5. GenAI telemetry を標準実装にする ⬚

### 目的

運用時に必要な追跡情報（turn、tool call、usage、latency、abort reason）を一貫して記録可能にする。

### 実装状況: ⬚ 未着手

- `tracing` クレートは依存に含まれており、`worker.rs` 内で `debug!` / `info!` / `trace!` / `warn!` マクロが使用されている。
- ただし GenAI semantic conventions に沿った構造化 span は未実装。
- `TelemetryConfig` / telemetry モジュールは未追加。

### 次のステップ

1. telemetry モジュール追加（field key 定義）
2. Worker/timeline/tool/hook に span 計装
3. usage と stop reason を終了イベントで集約
4. ログとメトリクス出力の最小 adapter を実装

---

## 導入順序（更新版）

1. ~~ToolServer 分離~~ ✅
2. ~~Streaming Hook 拡張~~ ✅
3. Telemetry 標準化 ⬚
4. Typed output API ⬚
5. Provider capability 移行の仕上げ 🔄

---

## チケット分解（実装順・進捗付き）

### Epic A: ToolServer 分離 ✅

| ID | タイトル | 状態 | 備考 |
| --- | --- | --- | --- |
| A1 | ToolServer 最小骨格の追加 | ✅ | `tool_server.rs` に `ToolServer` / `ToolServerHandle` 実装済み |
| A2 | Worker の tool map を ToolServerHandle に置換 | ✅ | `Worker` は `ToolServerHandle` を保持。`register_tool` / `call_tool` / `tool_definitions_sorted` 全て経由 |
| A3 | Hook context を ToolServer 参照へ接続 | ✅ | `pre_tool_call` / `post_tool_call` で `ToolCallContext` に `meta` / `tool` を `ToolServerHandle::get_tool()` から取得 |
| A4 | KV キャッシュ保護ルールの実装 | ✅ | `CacheLocked` 型状態パターンで実装。`lock()` 後は prefix の変更が型レベルで防止される |
| A5 | ToolServer 単体/統合テスト追加 | ✅ | `tool_server.rs` 内に重複登録・未登録呼び出し・ソート順のテスト実装済み |

### Epic B: Streaming Hook 拡張 ✅

| ID | タイトル | 状態 | 備考 |
| --- | --- | --- | --- |
| B1 | Hook event 種別追加（delta/stream） | ✅ | `OnTextDelta` / `OnToolCallDelta` / `OnStreamChunk` / `OnStreamComplete` 定義済み |
| B2 | Timeline dispatch に hook 呼び出し点追加 | ✅ | `BlockDelta` 受信時に hook 実行。stream dispatch ループ内に組み込み済み |
| B3 | Abort/Pause 制御線の接続 | ✅ | `StreamHookResult` の `Abort` / `Pause` が Worker の run ループに接続済み |
| B4 | 実行順序仕様と回帰テスト | 🔄 | コード上は登録順実行を実装。仕様文書化・専用回帰テストは未完了 |

### Epic C: Telemetry 標準化 ⬚

| ID | タイトル | 状態 | 備考 |
| --- | --- | --- | --- |
| C1 | telemetry モジュールと semantic key 定義 | ⬚ | 未着手 |
| C2 | worker/turn/llm/tool/hook span 計装 | ⬚ | 未着手。`tracing` の基本利用はあるが構造化 span は未実装 |
| C3 | マスキング設定と no-op 運用 | ⬚ | 未着手 |
| C4 | telemetry テスト/サンプル整備 | ⬚ | 未着手 |

### Epic D: Typed Output API ⬚

| ID | タイトル | 状態 | 備考 |
| --- | --- | --- | --- |
| D1 | Request builder に output_schema 追加 | ⬚ | 未着手 |
| D2 | `run_typed<T>` / `run_typed_with_history<T>` 実装 | ⬚ | 未着手 |
| D3 | 非対応 provider のフォールバックとエラー分離 | ⬚ | 未着手 |
| D4 | typed 出力の回帰テスト | ⬚ | 未着手 |

### Epic E: Provider Capability 移行 🔄

| ID | タイトル | 状態 | 備考 |
| --- | --- | --- | --- |
| E1 | provider capability trait 導入 | ⬚ | 未着手 |
| E2 | Anthropic/OpenAI/Gemini の capability 移行 | 🔄 | scheme 層での request/events 分離は完了。capability trait は未導入 |
| E3 | Worker 側 provider 分岐の削除 | 🔄 | Worker は Event ベースで provider 非依存に近いが、完全な分離は未検証 |
| E4 | snapshot テストと責務ドキュメント更新 | ⬚ | 未着手 |

---

## チケット運用ルール

- 各 ticket は `feature/<ID>-...` ブランチで実装する。
- 依存 ticket が `main` に入るまで、後続 ticket は着手しない。
- 各 ticket で最低 1 つ回帰テストを追加する（ドキュメント専用 ticket を除く）。
- `CacheLocked` の prefix 不変性を崩す変更は、A4 と同時に防止テストを追加する。
- tool 定義のリクエスト化は決定的順序にする（内部保持が `HashMap` でも送信順は固定）。

## 非目標

- 既存 Worker API の全面破壊的変更
- 1回の PR で5項目を同時に実装
- Open Responses 完全準拠の即時達成

## 備考

`llm_worker_rs` は Timeline 駆動設計が中核であり、この方針は維持する。`rig` の設計は部品として参照し、全体アーキテクチャは置換しない。