# llm-worker アーキテクチャ

## 概要

llm-workerは3層構成でLLMとのインタラクションを管理する。

```
┌─────────────────────────────────────────┐
│  Worker (オーケストレーション)            │
│  ターンループ / フック / ツール実行       │
│  Type-state: Mutable ↔ CacheLocked      │
└───────────┬─────────────────────────────┘
            │
┌───────────▼─────────────────────────────┐
│  Timeline (イベント処理)                 │
│  Handler dispatch / Block collectors     │
└───────────┬─────────────────────────────┘
            │
┌───────────▼─────────────────────────────┐
│  LLM Client (プロトコル)                 │
│  Provider (HTTP) / Scheme (変換)         │
│  Anthropic / OpenAI / Gemini / Ollama    │
└─────────────────────────────────────────┘
```

## モジュール構成

| モジュール | 責務 | 要件 |
|---|---|---|
| `worker` | ターンループ、フック統合、ツール実行、Pause/Resume | R1, R4 |
| `state` | Type-state (Mutable/CacheLocked) | R2 |
| `hook` | Hook trait、10フックポイント | R3, R4 |
| `tool` / `tool_server` | ツール定義・登録・実行 | R3 |
| `timeline` | イベントストリーム処理、Handler dispatch | — |
| `handler` | Handler/Kind trait、ブロック別ハンドラ | — |
| `callback` | クロージャベースイベント購読（`on_text_block`, `on_usage` 等） | — |
| `llm_client` | LLMプロバイダへのHTTPリクエスト/ストリーミング | — |
| `llm_client/scheme` | プロバイダ固有ワイヤーフォーマット変換 | — |
| `llm_client/providers` | Anthropic, OpenAI, Gemini, Ollama実装 | — |

## データフロー

### リクエスト（送信）
```
Worker.history (Vec<Item>)
  → build_request() → Request { items, tools, config }
    → Scheme.build_request() → プロバイダ固有JSON
      → Provider.stream() → HTTP POST
```

### レスポンス（受信）
```
HTTP SSE bytes
  → Provider → SSE events
    → Scheme.parse_event() → Event (統一型)
      → Timeline.dispatch() → Handler.on_event()
        → TextBlockCollector / ToolCallCollector
          → Worker: 履歴に追加、ツール実行判定
```

## 内部型

### Item (会話履歴の単位)
- `Item::Message` — テキストメッセージ (user/assistant)
- `Item::ToolCall` — ツール呼び出し
- `Item::ToolResult` — ツール実行結果
- `Item::Reasoning` — 思考 (Extended Thinking)

### Event (ストリーミングイベント)
- Meta: `Ping`, `Usage`, `Status`, `Error`
- Block: `BlockStart` → `BlockDelta`* → `BlockStop` / `BlockAbort`

単一の `Event` 型が全層で共有される（`llm_client::event` で定義、他層はre-export）。