yoi/crates/llm-worker/docs/plan/rig_adoption.md

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 の設計は部品として参照し、全体アーキテクチャは置換しない。