feat: OpenResponses

docs/plan/worker_api_plan.md

@@ -0,0 +1,83 @@
+# Worker API/DSL 実装計画
+
+## 目的
+
+- [Open Responses](https://www.openresponses.org)(以後"OR")に準拠した正規化を前提に、
+  Item/Part の2段スコープを扱える Worker API を設計する。
+- APIの煩雑化を防ぐため、worker.on_xxx として公開するのを避けつつ、
+  Text/Thinking/Tool など型の違いを静的に扱える DSL を提供する。
+
+## 方針
+
+- 内部は Timeline が Event を正規化し、Item/Part/Meta
+  を単一ストリームとして扱う。
+- API では Item/Part 型ごとに ctx を持てるようにし、DSL
+  で記述の冗長さを削減する。
+- まず macro_rules! 版を作り、必要なら proc-macro に拡張する。
+- Item/Part の型パラメータはクレートが公開する Kind 型を使う。
+
+## 仕様の前提
+
+- Item は OR の item (message, function_call, reasoning など) に対応する。
+- Part は OR の content part (output_text, reasoning_text など) に対応する。
+- Item は必ず start/stop を持つ。Part は Item 内で複数発生し得る。
+- Item/Part の型指定は `Item<Message>` / `Part<ReasoningText>` のように書く。
+
+## 設計ステップ
+
+### 1. 内部イベントモデルの整理
+
+- Event を Item/Part/Meta の3層に整理する。
+- ItemEvent / PartEvent は型パラメータで区別する。
+- 例: ItemEvent<Message>, PartEvent<Message, OutputText>
+
+### 2. スコープの二段化
+
+- Item ctx: Item 型ごとに1つ
+- Part ctx: Part 型ごとに1つ
+- Part のイベントでは常に item ctx と part ctx の両方を渡す。
+
+### 3. Handler trait の再定義
+
+- Item/Part を型で指定できる trait を導入する。
+- 例:
+  - trait ItemHandler<I>
+  - trait PartHandler<I, P>
+- PartHandler には ItemHandler の ItemCtx を必須で渡す。
+- Part の ctx 型は `PartKind::Ctx` 方式 or enum 方式で切り替える。
+
+### 4. Timeline との結合
+
+- Timeline は ItemStart で ItemCtx を生成
+- PartStart で PartCtx を生成
+- Delta/Stop は対応 ctx に流す
+- ItemStop で ItemCtx を破棄
+
+### 5. DSL (macro_rules!) の導入
+
+- まず宣言的 DSL を提供する。
+- 例:
+  - handler! { Item<Message> { type ItemCtx = ...; Part<OutputText> { type
+    PartCtx = ...; } } }
+- DSL は ItemHandler / PartHandler 実装を生成する。
+- Item/Part の Kind 型はクレートが公開する型を参照する。
+
+### 6. 拡張ポイント
+
+- 追加 Part (output_image など) を DSL に追加しやすい形にする。
+- 必要なら proc-macro に移行して構文自由度を上げる。
+
+## 実装順序
+
+1. Event/Item/Part の型定義の整理
+2. Item/Part ctx を持つ Timeline 実装
+3. Handler trait の定義・既存コードの移行
+4. macro_rules! DSL の実装
+5. 既存ユースケースの移植
+
+## TODO
+
+- Item と Part の型対応表を整理する
+- OR と既存 llm_client の差分を再確認する
+- Tool args の delta を OR 拡張として扱うか検討する
+- macro_rules! で表現可能な DSL の最小文法を確定する