# 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 の最小文法を確定する