Hare/llm_worker_rs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: Hare:c281248bf8ab5db1db6e8f95f277142fe7449b92
Branches Tags
Hare:master
Hare:develop
Hare:feature/hook-and-tool-types-improvements
Hare:0.2.0
Hare:0.1.0
..
compare: Hare:33f1c218f265f5090128a0407b7b564eeb178249
Branches Tags
Hare:develop
Hare:master
Hare:feature/hook-and-tool-types-improvements
Hare:0.2.0
Hare:0.1.0

No commits in common. "c281248bf8ab5db1db6e8f95f277142fe7449b92" and "33f1c218f265f5090128a0407b7b564eeb178249" have entirely different histories.
c281248bf8 ... 33f1c218f2

25 changed files with 709 additions and 1754 deletions
Show Stats Expand all files Collapse all files

239
Cargo.lock generated
View File

@ -104,9 +104,9 @@ checksum = "b35204fbdc0b3f4446b89fc1ac2cf84a8a68971995d0bf2e925ec7cd960f9cb3"
[[package]]
name = "cc"
version = "1.2.52"
version = "1.2.51"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cd4932aefd12402b36c60956a4fe0035421f544799057659ff86f923657aada3"
checksum = "7a0aeaff4ff1a90589618835a598e545176939b97874f7abc7851caa0618f203"
dependencies = [
"find-msvc-tools",
"shlex",
@ -203,12 +203,6 @@ version = "1.0.20"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d0881ea181b1df73ff77ffaaf9c7544ecc11e82fba9b5f27b262a3c73a332555"
[[package]]
name = "equivalent"
version = "1.0.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
[[package]]
name = "errno"
version = "0.3.14"
@ -238,15 +232,9 @@ checksum = "37909eebbb50d72f9059c3b6d82c0463f2ff062c9e95845c43a6c9c0355411be"
[[package]]
name = "find-msvc-tools"
version = "0.1.7"
version = "0.1.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f449e6c6c08c865631d4890cfacf252b3d396c9bcc83adb6623cdb02a8336c41"
[[package]]
name = "fnv"
version = "1.0.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1"
checksum = "645cbb3a84e60b7531617d5ae4e57f7e27308f6445f5abf653209ea76dec8dff"
[[package]]
name = "foreign-types"
@ -361,17 +349,6 @@ dependencies = [
"slab",
]
[[package]]
name = "getrandom"
version = "0.2.16"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "335ff9f135e4384c8150d6f27c6daed433577f86b4750418338c01a1a2528592"
dependencies = [
"cfg-if",
"libc",
"wasi",
]
[[package]]
name = "getrandom"
version = "0.3.4"
@ -384,31 +361,6 @@ dependencies = [
"wasip2",
]
[[package]]
name = "h2"
version = "0.4.13"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2f44da3a8150a6703ed5d34e164b875fd14c2cdab9af1252a9a1020bde2bdc54"
dependencies = [
"atomic-waker",
"bytes",
"fnv",
"futures-core",
"futures-sink",
"http",
"indexmap",
"slab",
"tokio",
"tokio-util",
"tracing",
]
[[package]]
name = "hashbrown"
version = "0.16.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "841d1cc9bed7f9236f321df977030373f4a4163ae1a7dbfe1a51a2c1a51d9100"
[[package]]
name = "heck"
version = "0.5.0"
@ -464,7 +416,6 @@ dependencies = [
"bytes",
"futures-channel",
"futures-core",
"h2",
"http",
"http-body",
"httparse",
@ -476,22 +427,6 @@ dependencies = [
"want",
]
[[package]]
name = "hyper-rustls"
version = "0.27.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e3c93eb611681b207e1fe55d5a71ecf91572ec8a6705cdb6857f7d8d5242cf58"
dependencies = [
"http",
"hyper",
"hyper-util",
"rustls",
"rustls-pki-types",
"tokio",
"tokio-rustls",
"tower-service",
]
[[package]]
name = "hyper-tls"
version = "0.6.0"
@ -634,16 +569,6 @@ dependencies = [
"icu_properties",
]
[[package]]
name = "indexmap"
version = "2.13.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7714e70437a7dc3ac8eb7e6f8df75fd8eb422675fc7678aff7364301092b1017"
dependencies = [
"equivalent",
"hashbrown",
]
[[package]]
name = "ipnet"
version = "2.11.0"
@ -723,7 +648,6 @@ dependencies = [
"tempfile",
"thiserror",
"tokio",
"tokio-util",
"tracing",
"tracing-subscriber",
]
@ -971,12 +895,10 @@ dependencies = [
"bytes",
"futures-core",
"futures-util",
"h2",
"http",
"http-body",
"http-body-util",
"hyper",
"hyper-rustls",
"hyper-tls",
"hyper-util",
"js-sys",
@ -1001,20 +923,6 @@ dependencies = [
"web-sys",
]
[[package]]
name = "ring"
version = "0.17.14"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a4689e6c2294d81e88dc6261c768b63bc4fcdb852be6d1352498b114f61383b7"
dependencies = [
"cc",
"cfg-if",
"getrandom 0.2.16",
"libc",
"untrusted",
"windows-sys 0.52.0",
]
[[package]]
name = "rustix"
version = "1.1.3"
@ -1028,19 +936,6 @@ dependencies = [
"windows-sys 0.61.2",
]
[[package]]
name = "rustls"
version = "0.23.36"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c665f33d38cea657d9614f766881e4d510e0eda4239891eea56b4cadcf01801b"
dependencies = [
"once_cell",
"rustls-pki-types",
"rustls-webpki",
"subtle",
"zeroize",
]
[[package]]
name = "rustls-pki-types"
version = "1.13.2"
@ -1050,17 +945,6 @@ dependencies = [
"zeroize",
]
[[package]]
name = "rustls-webpki"
version = "0.103.8"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2ffdfa2f5286e2247234e03f680868ac2815974dc39e00ea15adc445d0aafe52"
dependencies = [
"ring",
"rustls-pki-types",
"untrusted",
]
[[package]]
name = "rustversion"
version = "1.0.22"
@ -1227,12 +1111,6 @@ version = "0.11.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
[[package]]
name = "subtle"
version = "2.6.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
[[package]]
name = "syn"
version = "2.0.114"
@ -1271,7 +1149,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "655da9c7eb6305c55742045d5a8d2037996d61d8de95806335c7c86ce0f82e9c"
dependencies = [
"fastrand",
"getrandom 0.3.4",
"getrandom",
"once_cell",
"rustix",
"windows-sys 0.61.2",
@ -1352,16 +1230,6 @@ dependencies = [
"tokio",
]
[[package]]
name = "tokio-rustls"
version = "0.26.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1729aa945f29d91ba541258c8df89027d5792d85a8841fb65e8bf0f4ede4ef61"
dependencies = [
"rustls",
"tokio",
]
[[package]]
name = "tokio-util"
version = "0.7.18"
@ -1493,12 +1361,6 @@ version = "1.0.22"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9312f7c4f6ff9069b165498234ce8be658059c6728633667c526e27dc2cf1df5"
[[package]]
name = "untrusted"
version = "0.9.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1"
[[package]]
name = "url"
version = "2.5.8"
@ -1646,22 +1508,13 @@ version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
[[package]]
name = "windows-sys"
version = "0.52.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
dependencies = [
"windows-targets 0.52.6",
]
[[package]]
name = "windows-sys"
version = "0.60.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f2f500e4d28234f72040990ec9d39e3a6b950f9f22d3dba18416c35882612bcb"
dependencies = [
"windows-targets 0.53.5",
"windows-targets",
]
[[package]]
@ -1673,22 +1526,6 @@ dependencies = [
"windows-link",
]
[[package]]
name = "windows-targets"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
dependencies = [
"windows_aarch64_gnullvm 0.52.6",
"windows_aarch64_msvc 0.52.6",
"windows_i686_gnu 0.52.6",
"windows_i686_gnullvm 0.52.6",
"windows_i686_msvc 0.52.6",
"windows_x86_64_gnu 0.52.6",
"windows_x86_64_gnullvm 0.52.6",
"windows_x86_64_msvc 0.52.6",
]
[[package]]
name = "windows-targets"
version = "0.53.5"
@ -1696,106 +1533,58 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4945f9f551b88e0d65f3db0bc25c33b8acea4d9e41163edf90dcd0b19f9069f3"
dependencies = [
"windows-link",
"windows_aarch64_gnullvm 0.53.1",
"windows_aarch64_msvc 0.53.1",
"windows_i686_gnu 0.53.1",
"windows_i686_gnullvm 0.53.1",
"windows_i686_msvc 0.53.1",
"windows_x86_64_gnu 0.53.1",
"windows_x86_64_gnullvm 0.53.1",
"windows_x86_64_msvc 0.53.1",
"windows_aarch64_gnullvm",
"windows_aarch64_msvc",
"windows_i686_gnu",
"windows_i686_gnullvm",
"windows_i686_msvc",
"windows_x86_64_gnu",
"windows_x86_64_gnullvm",
"windows_x86_64_msvc",
]
[[package]]
name = "windows_aarch64_gnullvm"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
[[package]]
name = "windows_aarch64_gnullvm"
version = "0.53.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a9d8416fa8b42f5c947f8482c43e7d89e73a173cead56d044f6a56104a6d1b53"
[[package]]
name = "windows_aarch64_msvc"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
[[package]]
name = "windows_aarch64_msvc"
version = "0.53.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b9d782e804c2f632e395708e99a94275910eb9100b2114651e04744e9b125006"
[[package]]
name = "windows_i686_gnu"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
[[package]]
name = "windows_i686_gnu"
version = "0.53.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "960e6da069d81e09becb0ca57a65220ddff016ff2d6af6a223cf372a506593a3"
[[package]]
name = "windows_i686_gnullvm"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
[[package]]
name = "windows_i686_gnullvm"
version = "0.53.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "fa7359d10048f68ab8b09fa71c3daccfb0e9b559aed648a8f95469c27057180c"
[[package]]
name = "windows_i686_msvc"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
[[package]]
name = "windows_i686_msvc"
version = "0.53.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1e7ac75179f18232fe9c285163565a57ef8d3c89254a30685b57d83a38d326c2"
[[package]]
name = "windows_x86_64_gnu"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
[[package]]
name = "windows_x86_64_gnu"
version = "0.53.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9c3842cdd74a865a8066ab39c8a7a473c0778a3f29370b5fd6b4b9aa7df4a499"
[[package]]
name = "windows_x86_64_gnullvm"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
[[package]]
name = "windows_x86_64_gnullvm"
version = "0.53.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0ffa179e2d07eee8ad8f57493436566c7cc30ac536a3379fdf008f47f6bb7ae1"
[[package]]
name = "windows_x86_64_msvc"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
[[package]]
name = "windows_x86_64_msvc"
version = "0.53.1"

3
README.md
View File

@ -11,7 +11,7 @@ Rusty, Efficient, and Agentic LLM Client Library
- Tool System: Define tools as async functions. The Worker automatically parses LLM tool calls, executes them in parallel, and feeds results back.
- Hook System: Intercept execution flow with `before_tool_call`, `after_tool_call`, and `on_turn_end` hooks for validation, logging, or self-correction.
- Event-Driven Streaming: Subscribe to real-time events (text deltas, tool calls, usage) for responsive UIs.
- Cache-Aware State Management: Type-state pattern (`Mutable` → `CacheLocked`) ensures KV cache efficiency by protecting the conversation prefix.
- Cache-Aware State Management: Type-state pattern (`Mutable` → `Locked`) ensures KV cache efficiency by protecting the conversation prefix.
## Quick Start
@ -33,3 +33,4 @@ let history = worker.run("What is 2+2?").await?;
## License
MIT

2
docs/spec/basis.md
View File

@ -17,7 +17,7 @@ LLMを用いたワーカーを作成する小型のSDK・ライブラリ。
module構成概念図
```plaintext
```
worker
├── context
├── llm_client

6
docs/spec/cache_lock.md
View File

@ -27,7 +27,7 @@ RustのType-stateパターンを利用し、Workerの状態によって利用可
* 自由な編集が可能な状態。
* システムプロンプトの設定・変更が可能。
* メッセージ履歴の初期構築（ロード、編集）が可能。
* **`CacheLocked` (キャッシュ保護状態)**
* **`Locked` (キャッシュ保護状態)**
* キャッシュの有効活用を目的とした、前方不変状態。
* **システムプロンプトの変更不可**。
* **既存メッセージ履歴の変更不可**（追記のみ許可）。
@ -47,7 +47,7 @@ worker.history_mut().push(initial_message);
// 3. ロックしてLocked状態へ遷移
// これにより、ここまでのコンテキストが "Fixed Prefix" として扱われる
let mut locked_worker: Worker<CacheLocked> = worker.lock();
let mut locked_worker: Worker<Locked> = worker.lock();
// 4. 利用 (Locked状態)
// 実行は可能。新しいメッセージは履歴の末尾に追記される。
@ -65,4 +65,4 @@ locked_worker.run(new_user_input).await?;
* **状態パラメータの導入**: `Worker<S: WorkerState>` の導入。
* **コンテキスト所有権の委譲**: `run` メソッドの引数でコンテキストを受け取るのではなく、`Worker` 内部に `history: Vec<Message>` を保持し管理する形へ移行する。
* **APIの分離**: `Mutable` 特有のメソッド（setter等）と、`CacheLocked` でも使えるメソッド（実行、参照等）をトレイト境界で分離する。
* **APIの分離**: `Mutable` 特有のメソッド（setter等）と、`Locked` でも使えるメソッド（実行、参照等）をトレイト境界で分離する。

70
docs/spec/cancellation.md
View File

@ -1,70 +0,0 @@
# 非同期キャンセル設計
Workerの非同期キャンセル機構についての設計ドキュメント。
## 概要
`tokio::sync::mpsc`の通知チャネルを用いて、別タスクからWorkerの実行を安全にキャンセルできる。
```rust
let worker = Arc::new(Mutex::new(Worker::new(client)));
// 実行タスク
let w = worker.clone();
let handle = tokio::spawn(async move {
w.lock().await.run("prompt").await
});
// キャンセル
worker.lock().await.cancel();
```
## キャンセル時の処理フロー
```
キャンセル検知
↓
timeline.abort_current_block() // 進行中ブロックの終端処理
↓
run_on_abort_hooks("Cancelled") // on_abort フック呼び出し
↓
Err(WorkerError::Cancelled) // エラー返却
```
## API
| メソッド | 説明 |
| ----------------- | ------------------------------ |
| `cancel()` | キャンセルをトリガー |
| `cancel_sender()` | キャンセル通知用のSenderを取得 |
## on_abort フック
`Hook::on_abort(&self, reason: &str)`がキャンセル時に呼ばれる。
クリーンアップ処理やログ記録に使用できる。
```rust
async fn on_abort(&self, reason: &str) -> Result<(), HookError> {
log::info!("Aborted: {}", reason);
Ok(())
}
```
呼び出しタイミング:
- `WorkerError::Cancelled` — reason: `"Cancelled"`
- `ControlFlow::Abort(reason)` — reason: フックが指定した理由
---
## 既知の問題
### on_abort の発火基準
`on_abort` は **interrupt（中断）** された場合に必ず発火する。
interrupt の例:
- `WorkerError::Cancelled`（キャンセル）
- `WorkerError::Aborted`（フックによるAbort）
- ストリーム/ツール/クライアント/Hook の各種エラーで処理が中断された場合

358
docs/spec/hooks_design.md
View File

@ -3,8 +3,7 @@
## 概要
HookはWorker層でのターン制御に介入するためのメカニズムです。
メッセージ送信・ツール実行・ターン終了等の各ポイントで処理を差し込むことができます。
Claude CodeのHooks機能に着想を得ており、メッセージ送信・ツール実行・ターン終了の各ポイントで処理を差し込むことができます。
## コンセプト
@ -12,184 +11,120 @@ HookはWorker層でのターン制御に介入するためのメカニズムで
- **Contextへのアクセス**: メッセージ履歴を読み書き可能
- **非破壊的チェーン**: 複数のHookを登録順に実行、後続Hookへの影響を制御
## Hook一覧
| Hook | タイミング | 主な用途 | 戻り値 |
| ------------------ | -------------------------- | -------------------------- | ---------------------- |
| `on_prompt_submit` | `run()` 呼び出し時 | ユーザーメッセージの前処理 | `OnPromptSubmitResult` |
| `pre_llm_request` | 各ターンのLLM送信前 | コンテキスト改変/検証 | `PreLlmRequestResult` |
| `pre_tool_call` | ツール実行前 | 実行許可/引数改変 | `PreToolCallResult` |
| `post_tool_call` | ツール実行後 | 結果加工/マスキング | `PostToolCallResult` |
| `on_turn_end` | ツールなしでターン終了直前 | 検証/リトライ指示 | `OnTurnEndResult` |
| `on_abort` | 中断時 | クリーンアップ/通知 | `()` |
## Hook Trait
```rust
#[async_trait]
pub trait Hook<E: HookEventKind>: Send + Sync {
async fn call(&self, input: &mut E::Input) -> Result<E::Output, HookError>;
pub trait WorkerHook: Send + Sync {
/// メッセージ送信前
/// リクエストに含まれるメッセージリストを改変できる
async fn on_message_send(
&self,
context: &mut Vec<Message>,
) -> Result<ControlFlow, HookError> {
Ok(ControlFlow::Continue)
}
/// ツール実行前
/// 実行をキャンセルしたり、引数を書き換えることができる
async fn before_tool_call(
&self,
tool_call: &mut ToolCall,
) -> Result<ControlFlow, HookError> {
Ok(ControlFlow::Continue)
}
/// ツール実行後
/// 結果を書き換えたり、隠蔽したりできる
async fn after_tool_call(
&self,
tool_result: &mut ToolResult,
) -> Result<ControlFlow, HookError> {
Ok(ControlFlow::Continue)
}
/// ターン終了時
/// 生成されたメッセージを検査し、必要ならリトライを指示できる
async fn on_turn_end(
&self,
messages: &[Message],
) -> Result<TurnResult, HookError> {
Ok(TurnResult::Finish)
}
}
```
## 制御フロー型
### HookEventKind / Result
### ControlFlow
Hookイベントごとに入力/出力型を分離し、意味のない制御フローを排除する。
Hook処理の継続/中断を制御する列挙型。
```rust
pub trait HookEventKind {
type Input;
type Output;
}
pub struct OnPromptSubmit;
pub struct PreLlmRequest;
pub struct PreToolCall;
pub struct PostToolCall;
pub struct OnTurnEnd;
pub struct OnAbort;
pub enum OnPromptSubmitResult {
Continue,
Cancel(String),
}
pub enum PreLlmRequestResult {
Continue,
Cancel(String),
}
pub enum PreToolCallResult {
pub enum ControlFlow {
/// 処理を続行（後続Hookも実行）
Continue,
/// 現在の処理をスキップ（ツール実行をスキップ等）
Skip,
/// 処理全体を中断（エラーとして扱う）
Abort(String),
Pause,
}
pub enum PostToolCallResult {
Continue,
Abort(String),
}
pub enum OnTurnEndResult {
Finish,
ContinueWithMessages(Vec<Message>),
Paused,
}
```
### Tool Call Context
### TurnResult
`pre_tool_call` / `post_tool_call` は、ツール実行の文脈を含む入力を受け取る。
ターン終了時の判定結果を表す列挙型。
```rust
pub struct ToolCallContext {
pub call: ToolCall,
pub meta: ToolMeta, // 不変メタデータ
pub tool: Arc<dyn Tool>, // 状態アクセス用
}
pub struct PostToolCallContext {
pub call: ToolCall,
pub result: ToolResult,
pub meta: ToolMeta,
pub tool: Arc<dyn Tool>,
pub enum TurnResult {
/// ターンを正常終了
Finish,
/// メッセージを追加してターン継続（自己修正など）
ContinueWithMessages(Vec<Message>),
}
```
## 呼び出しタイミング
```
Worker::run(user_input)
Worker::run() ループ
│
├─▶ on_prompt_submit ───────────────────────────┐
│ ユーザーメッセージの前処理・検証 │
│ （最初の1回のみ） │
├─▶ on_message_send ──────────────────────────────┐
│ コンテキストの改変、バリデーション、 │
│ システムプロンプト注入などが可能 │
│ │
└─▶ loop {
│
├─▶ pre_llm_request ──────────────────────│
│ コンテキストの改変、バリデーション、 │
│ システムプロンプト注入などが可能 │
│ （毎ターン実行） │
├─▶ LLMリクエスト送信 & ストリーム処理 │
│ │
├─▶ ツール呼び出しがある場合: │
│ │ │
│ ├─▶ before_tool_call (各ツールごと・逐次) │
│ │ 実行可否の判定、引数の改変 │
│ │ │
│ ├─▶ ツール並列実行 (join_all) │
│ │ │
│ └─▶ after_tool_call (各結果ごと・逐次) │
│ 結果の確認、加工、ログ出力 │
│ │
├─▶ ツール結果をコンテキストに追加 → ループ先頭へ │
│ │
└─▶ ツールなしの場合: │
│ │
├─▶ LLMリクエスト送信 & ストリーム処理 │
│ │
├─▶ ツール呼び出しがある場合: │
│ │ │
│ ├─▶ pre_tool_call (各ツールごと・逐次) │
│ │ 実行可否の判定、引数の改変 │
│ │ │
│ ├─▶ ツール並列実行 (join_all) │
│ │ │
│ └─▶ post_tool_call (各結果ごと・逐次) │
│ 結果の確認、加工、ログ出力 │
│ │
├─▶ ツール結果をコンテキストに追加 │
│ → ループ先頭へ │
│ │
└─▶ ツールなしの場合: │
│ │
└─▶ on_turn_end ───────────────────┘
└─▶ on_turn_end ─────────────────────────────┘
最終応答のチェック（Lint/Fmt等）
エラーがあればContinueWithMessagesでリトライ
}
※ 中断時は on_abort が呼ばれる
```
## 各Hookの詳細
### on_prompt_submit
### on_message_send
**呼び出しタイミング**: `run()`
でユーザーメッセージを受け取った直後（最初の1回のみ）
**呼び出しタイミング**: LLMへリクエスト送信前（ターンループの冒頭）
**用途**:
- ユーザー入力のバリデーション
- 入力のサニタイズ・フィルタリング
- ログ出力
- `OnPromptSubmitResult::Cancel` による実行キャンセル
**入力**: `&mut Message` - ユーザーメッセージ（改変可能）
**例**: 入力のバリデーション
```rust
struct InputValidator;
#[async_trait]
impl Hook<OnPromptSubmit> for InputValidator {
async fn call(
&self,
message: &mut Message,
) -> Result<OnPromptSubmitResult, HookError> {
if let MessageContent::Text(text) = &message.content {
if text.trim().is_empty() {
return Ok(OnPromptSubmitResult::Cancel("Empty input".to_string()));
}
}
Ok(OnPromptSubmitResult::Continue)
}
}
```
### pre_llm_request
**呼び出しタイミング**: 各ターンのLLMリクエスト送信前（ループの毎回）
**用途**:
- コンテキストへのシステムメッセージ注入
- メッセージのバリデーション
- 機密情報のフィルタリング
- リクエスト内容のログ出力
- `PreLlmRequestResult::Cancel` による送信キャンセル
**入力**: `&mut Vec<Message>` - コンテキスト全体（改変可能）
**例**: メッセージにタイムスタンプを追加
@ -197,33 +132,27 @@ impl Hook<OnPromptSubmit> for InputValidator {
struct TimestampHook;
#[async_trait]
impl Hook<PreLlmRequest> for TimestampHook {
async fn call(
impl WorkerHook for TimestampHook {
async fn on_message_send(
&self,
context: &mut Vec<Message>,
) -> Result<PreLlmRequestResult, HookError> {
) -> Result<ControlFlow, HookError> {
let timestamp = chrono::Local::now().to_rfc3339();
context.insert(0, Message::user(format!("[{}]", timestamp)));
Ok(PreLlmRequestResult::Continue)
Ok(ControlFlow::Continue)
}
}
```
### pre_tool_call
### before_tool_call
**呼び出しタイミング**: 各ツール実行前（並列実行フェーズの前）
**用途**:
- 危険なツールのブロック
- 引数のサニタイズ
- 確認プロンプトの表示（UIとの連携）
- 実行ログの記録
- `PreToolCallResult::Pause` による一時停止
**入力**:
- `ToolCallContext`（`ToolCall` + `ToolMeta` + `Arc<dyn Tool>`）
**例**: 特定ツールをブロック
@ -233,52 +162,46 @@ struct ToolBlocker {
}
#[async_trait]
impl Hook<PreToolCall> for ToolBlocker {
async fn call(
impl WorkerHook for ToolBlocker {
async fn before_tool_call(
&self,
ctx: &mut ToolCallContext,
) -> Result<PreToolCallResult, HookError> {
if self.blocked_tools.contains(&ctx.call.name) {
println!("Blocked tool: {}", ctx.call.name);
Ok(PreToolCallResult::Skip)
tool_call: &mut ToolCall,
) -> Result<ControlFlow, HookError> {
if self.blocked_tools.contains(&tool_call.name) {
println!("Blocked tool: {}", tool_call.name);
Ok(ControlFlow::Skip)
} else {
Ok(PreToolCallResult::Continue)
Ok(ControlFlow::Continue)
}
}
}
```
### post_tool_call
### after_tool_call
**呼び出しタイミング**: 各ツール実行後（並列実行フェーズの後）
**用途**:
- 結果の加工・フォーマット
- 機密情報のマスキング
- 結果のキャッシュ
- 実行結果のログ出力
**入力**:
- `PostToolCallContext`（`ToolCall` + `ToolResult` + `ToolMeta` +
`Arc<dyn Tool>`）
**例**: 結果にプレフィックスを追加
```rust
struct ResultFormatter;
#[async_trait]
impl Hook<PostToolCall> for ResultFormatter {
async fn call(
impl WorkerHook for ResultFormatter {
async fn after_tool_call(
&self,
ctx: &mut PostToolCallContext,
) -> Result<PostToolCallResult, HookError> {
if !ctx.result.is_error {
ctx.result.content = format!("[OK] {}", ctx.result.content);
tool_result: &mut ToolResult,
) -> Result<ControlFlow, HookError> {
if !tool_result.is_error {
tool_result.content = format!("[OK] {}", tool_result.content);
}
Ok(PostToolCallResult::Continue)
Ok(ControlFlow::Continue)
}
}
```
@ -288,22 +211,10 @@ impl Hook<PostToolCall> for ResultFormatter {
**呼び出しタイミング**: ツール呼び出しなしでターンが終了する直前
**用途**:
- 生成されたコードのLint/Fmt
- 出力形式のバリデーション
- 自己修正のためのリトライ指示
- 最終結果のログ出力
- `OnTurnEndResult::Paused` による一時停止
### on_abort
**呼び出しタイミング**: キャンセル/エラー/AbortなどでWorkerが中断された時
**用途**:
- クリーンアップ処理
- 中断理由のログ出力
- 外部システムへの通知
**例**: JSON形式のバリデーション
@ -311,11 +222,11 @@ impl Hook<PostToolCall> for ResultFormatter {
struct JsonValidator;
#[async_trait]
impl Hook<OnTurnEnd> for JsonValidator {
async fn call(
impl WorkerHook for JsonValidator {
async fn on_turn_end(
&self,
messages: &mut Vec<Message>,
) -> Result<OnTurnEndResult, HookError> {
messages: &[Message],
) -> Result<TurnResult, HookError> {
// 最後のアシスタントメッセージを取得
let last = messages.iter().rev()
.find(|m| m.role == Role::Assistant);
@ -325,25 +236,25 @@ impl Hook<OnTurnEnd> for JsonValidator {
// JSONとしてパースを試みる
if serde_json::from_str::<serde_json::Value>(text).is_err() {
// 失敗したらリトライ指示
return Ok(OnTurnEndResult::ContinueWithMessages(vec![
return Ok(TurnResult::ContinueWithMessages(vec![
Message::user("Invalid JSON. Please fix and try again.")
]));
}
}
}
Ok(OnTurnEndResult::Finish)
Ok(TurnResult::Finish)
}
}
```
## 複数Hookの実行順序
Hookは**イベントごとに登録順**に実行されます。
Hookは**登録順**に実行されます。
```rust
worker.add_pre_tool_call_hook(HookA); // 1番目に実行
worker.add_pre_tool_call_hook(HookB); // 2番目に実行
worker.add_pre_tool_call_hook(HookC); // 3番目に実行
worker.add_hook(HookA); // 1番目に実行
worker.add_hook(HookB); // 2番目に実行
worker.add_hook(HookC); // 3番目に実行
```
### 制御フローの伝播
@ -351,7 +262,6 @@ worker.add_pre_tool_call_hook(HookC); // 3番目に実行
- `Continue`: 後続Hookも実行
- `Skip`: 現在の処理をスキップし、後続Hookは実行しない
- `Abort`: 即座にエラーを返し、処理全体を中断
- `Pause`: Workerを一時停止（再開は`resume`）
```
Hook A: Continue → Hook B: Skip → (Hook Cは実行されない)
@ -361,39 +271,52 @@ Hook A: Continue → Hook B: Skip → (Hook Cは実行されない)
Hook A: Continue → Hook B: Abort("reason")
↓
WorkerError::Aborted
Hook A: Continue → Hook B: Pause
↓
WorkerResult::Paused
```
## 設計上のポイント
### 1. イベントごとの実装
### 1. デフォルト実装
必要なイベントのみ `Hook<Event>` を実装する。
全メソッドにデフォルト実装があるため、必要なメソッドだけオーバーライドすれば良い。
```rust
struct SimpleLogger;
#[async_trait]
impl WorkerHook for SimpleLogger {
// on_message_send だけ実装
async fn on_message_send(
&self,
context: &mut Vec<Message>,
) -> Result<ControlFlow, HookError> {
println!("Sending {} messages", context.len());
Ok(ControlFlow::Continue)
}
// 他のメソッドはデフォルト（Continue/Finish）
}
```
### 2. 可変参照による改変
`&mut`で引数を受け取るため、直接改変が可能。
```rust
async fn call(&self, ctx: &mut ToolCallContext) -> ... {
async fn before_tool_call(&self, tool_call: &mut ToolCall) -> ... {
// 引数を直接書き換え
ctx.call.input["sanitized"] = json!(true);
Ok(PreToolCallResult::Continue)
tool_call.input["sanitized"] = json!(true);
Ok(ControlFlow::Continue)
}
```
### 3. 並列実行との統合
- `pre_tool_call`: 並列実行**前**に逐次実行（許可判定のため）
- `before_tool_call`: 並列実行**前**に逐次実行（許可判定のため）
- ツール実行: `join_all`で**並列**実行
- `post_tool_call`: 並列実行**後**に逐次実行（結果加工のため）
- `after_tool_call`: 並列実行**後**に逐次実行（結果加工のため）
### 4. Send + Sync 要件
`Hook`は`Send + Sync`を要求するため、スレッドセーフな実装が必要。
`WorkerHook`は`Send + Sync`を要求するため、スレッドセーフな実装が必要。
状態を持つ場合は`Arc<Mutex<T>>`や`AtomicUsize`などを使用する。
```rust
@ -402,10 +325,10 @@ struct CountingHook {
}
#[async_trait]
impl Hook<PreToolCall> for CountingHook {
async fn call(&self, _: &mut ToolCallContext) -> Result<PreToolCallResult, HookError> {
impl WorkerHook for CountingHook {
async fn before_tool_call(&self, _: &mut ToolCall) -> Result<ControlFlow, HookError> {
self.count.fetch_add(1, Ordering::SeqCst);
Ok(PreToolCallResult::Continue)
Ok(ControlFlow::Continue)
}
}
```
@ -413,13 +336,13 @@ impl Hook<PreToolCall> for CountingHook {
## 典型的なユースケース
| ユースケース | 使用Hook | 処理内容 |
| ------------------ | -------------------- | -------------------------- |
| ツール許可制御 | `pre_tool_call` | 危険なツールをSkip |
| 実行ログ | `pre/post_tool_call` | 呼び出しと結果を記録 |
|-------------|----------|----------|
| ツール許可制御 | `before_tool_call` | 危険なツールをSkip |
| 実行ログ | `before/after_tool_call` | 呼び出しと結果を記録 |
| 出力バリデーション | `on_turn_end` | 形式チェック、リトライ指示 |
| コンテキスト注入 | `on_message_send` | システムメッセージ追加 |
| 結果のサニタイズ | `post_tool_call` | 機密情報のマスキング |
| レート制限 | `pre_tool_call` | 呼び出し頻度の制御 |
| 結果のサニタイズ | `after_tool_call` | 機密情報のマスキング |
| レート制限 | `before_tool_call` | 呼び出し頻度の制御 |
## TODO
@ -427,14 +350,11 @@ impl Hook<PreToolCall> for CountingHook {
現在のHooks実装は基本的なユースケースをカバーしているが、以下の点について将来的に厳密な仕様を定義する必要がある：
- **エラーハンドリングの明確化**:
`HookError`発生時のリカバリー戦略、部分的な失敗の扱い
- **エラーハンドリングの明確化**: `HookError`発生時のリカバリー戦略、部分的な失敗の扱い
- **Hook間の依存関係**: 複数Hookの実行順序が結果に影響する場合のセマンティクス
- **非同期キャンセル**: Hook実行中のキャンセル（タイムアウト等）の振る舞い
- **状態の一貫性**:
`on_message_send`で改変されたコンテキストが後続処理で期待通りに反映される保証
- **リトライ制限**:
`on_turn_end`での`ContinueWithMessages`による無限ループ防止策
- **状態の一貫性**: `on_message_send`で改変されたコンテキストが後続処理で期待通りに反映される保証
- **リトライ制限**: `on_turn_end`での`ContinueWithMessages`による無限ループ防止策
- **Hook優先度**: 登録順以外の優先度指定メカニズムの必要性
- **条件付きHook**: 特定条件でのみ有効化されるHookパターン
- **テスト容易性**: Hookのモック/スタブ作成のためのユーティリティ

191
docs/spec/tools_design.md
View File

@ -1,191 +0,0 @@
# Tool 設計
## 概要
`llm-worker`のツールシステムは、LLMが外部リソースにアクセスしたり計算を実行するための仕組みを提供する。
メタ情報の不変性とセッションスコープの状態管理を両立させる設計となっている。
## 主要な型
```
type ToolDefinition
Fn() -> (ToolMeta, Arc<dyn Tool>)
worker.register_tool() で呼び出し
▼
- struct ToolMeta (name, desc, schema)
不変・登録時固定
- trait Tool (executer)
登録時生成・セッション中再利用
```
### ToolMeta
ツールのメタ情報を保持する不変構造体。登録時に固定され、Worker内で変更されない。
```rust
pub struct ToolMeta {
pub name: String,
pub description: String,
pub input_schema: Value,
}
```
**目的:**
- LLM へのツール定義として送信
- Hook からの参照（読み取り専用）
- 登録後の不変性を保証
### Tool trait
ツールの実行ロジックのみを定義するトレイト。
```rust
#[async_trait]
pub trait Tool: Send + Sync {
async fn execute(&self, input_json: &str) -> Result<String, ToolError>;
}
```
**設計方針:**
- メタ情報（name, description, schema）は含まない
- 状態を持つことが可能（セッション中のカウンターなど）
- `Send + Sync` で並列実行に対応
**インスタンスのライフサイクル:**
1. `register_tool()` 呼び出し時にファクトリが実行され、インスタンスが生成される
2. LLM がツールを呼び出すと、既存インスタンスの `execute()` が実行される
3. 同じセッション中は同一インスタンスが再利用される
※ 「最初に呼ばれたとき」の遅延初期化ではなく、**登録時の即時初期化**である。
### ToolDefinition
メタ情報とツールインスタンスを生成するファクトリ。
```rust
pub type ToolDefinition = Arc<dyn Fn() -> (ToolMeta, Arc<dyn Tool>) + Send + Sync>;
```
**なぜファクトリか:**
- Worker への登録時に一度だけ呼び出される
- メタ情報とインスタンスを同時に生成し、整合性を保証
- クロージャでコンテキスト（`self.clone()`）をキャプチャ可能
## Worker でのツール管理
```rust
// Worker 内部
tools: HashMap<String, (ToolMeta, Arc<dyn Tool>)>
// 登録 API
pub fn register_tool(&mut self, factory: ToolDefinition) -> Result<(), ToolRegistryError>
```
登録時の処理:
1. ファクトリを呼び出し `(meta, instance)` を取得
2. 同名ツールが既に登録されていればエラー
3. HashMap に `(meta, instance)` を保存
## マクロによる自動生成
`#[tool_registry]` マクロは `{method}_definition()` メソッドを生成する。
```rust
#[tool_registry]
impl MyApp {
/// 検索を実行する
#[tool]
async fn search(&self, query: String) -> String {
// 実装
}
}
// 生成されるコード:
impl MyApp {
pub fn search_definition(&self) -> ToolDefinition {
let ctx = self.clone();
Arc::new(move || {
let meta = ToolMeta::new("search")
.description("検索を実行する")
.input_schema(/* schemars で生成 */);
let tool = Arc::new(ToolSearch { ctx: ctx.clone() });
(meta, tool)
})
}
}
```
## Hook との連携
Hook は `ToolCallContext` / `AfterToolCallContext`
を通じてメタ情報とインスタンスにアクセスできる。
```rust
pub struct ToolCallContext {
pub call: ToolCall, // 呼び出し情報（改変可能）
pub meta: ToolMeta, // メタ情報（読み取り専用）
pub tool: Arc<dyn Tool>, // インスタンス（状態アクセス用）
}
```
**用途:**
- `meta` で名前やスキーマを確認
- `tool` でツールの内部状態を読み取り（ダウンキャスト必要）
- `call` の引数を改変してツールに渡す
## 使用例
### 手動実装
```rust
struct Counter { count: AtomicUsize }
impl Tool for Counter {
async fn execute(&self, _: &str) -> Result<String, ToolError> {
let n = self.count.fetch_add(1, Ordering::SeqCst);
Ok(format!("count: {}", n))
}
}
let def: ToolDefinition = Arc::new(|| {
let meta = ToolMeta::new("counter")
.description("カウンターを増加")
.input_schema(json!({"type": "object"}));
(meta, Arc::new(Counter { count: AtomicUsize::new(0) }))
});
worker.register_tool(def)?;
```
### マクロ使用（推奨）
```rust
#[tool_registry]
impl App {
#[tool]
async fn greet(&self, name: String) -> String {
format!("Hello, {}!", name)
}
}
let app = App;
worker.register_tool(app.greet_definition())?;
```
## 設計上の決定
| 問題 | 決定 | 理由 |
| -------------------- | ------------------------------ | ---------------------------------------------- |
| メタ情報の変更可能性 | ToolMeta を分離・不変化 | 登録後の整合性を保証 |
| 状態管理 | 登録時にインスタンス生成 | セッション中の状態保持、同一インスタンス再利用 |
| Factory vs Instance | Factory + 登録時即時呼び出し | コンテキストキャプチャと登録時検証 |
| Hook からのアクセス | Context に meta と tool を含む | 柔軟な介入を可能に |

72
docs/spec/worker_design.md
View File

@ -178,60 +178,41 @@ Workerは生成されたラッパー構造体を `Box<dyn Tool>` として保持
```rust
#[async_trait]
pub trait Hook<E: HookEventKind>: Send + Sync {
async fn call(&self, input: &mut E::Input) -> Result<E::Output, Error>;
pub trait WorkerHook: Send + Sync {
/// メッセージ送信前。
/// リクエストに含まれるメッセージリストを改変できる。
async fn on_message_send(&self, context: &mut Vec<Message>) -> Result<ControlFlow, Error> {
Ok(ControlFlow::Continue)
}
/// ツール実行前。
/// 実行をキャンセルしたり、引数を書き換えることができる。
async fn before_tool_call(&self, tool_call: &mut ToolCall) -> Result<ControlFlow, Error> {
Ok(ControlFlow::Continue)
}
/// ツール実行後。
/// 結果を書き換えたり、隠蔽したりできる。
async fn after_tool_call(&self, tool_result: &mut ToolResult) -> Result<ControlFlow, Error> {
Ok(ControlFlow::Continue)
}
/// ターン終了時。
/// 生成されたメッセージを検査し、必要ならリトライ（ContinueWithMessages）を指示できる。
async fn on_turn_end(&self, messages: &[Message]) -> Result<TurnResult, Error> {
Ok(TurnResult::Finish)
}
}
pub trait HookEventKind {
type Input;
type Output;
}
pub struct OnMessageSend;
pub struct BeforeToolCall;
pub struct AfterToolCall;
pub struct OnTurnEnd;
pub struct OnAbort;
pub enum OnMessageSendResult {
Continue,
Cancel(String),
}
pub enum BeforeToolCallResult {
pub enum ControlFlow {
Continue,
Skip, // Tool実行などをスキップ
Abort(String), // 処理中断
Pause,
}
pub enum AfterToolCallResult {
Continue,
Abort(String),
}
pub enum OnTurnEndResult {
pub enum TurnResult {
Finish,
ContinueWithMessages(Vec<Message>), // メッセージを追加してターン継続（自己修正など）
Paused,
}
```
### Tool Call Context
`before_tool_call` / `after_tool_call` は、ツール実行の文脈を含む入力を受け取る。
```rust
pub struct ToolCallContext {
pub call: ToolCall,
pub meta: ToolMeta, // 不変メタデータ
pub tool: Arc<dyn Tool>, // 状態アクセス用
}
pub struct ToolResultContext {
pub result: ToolResult,
pub meta: ToolMeta,
pub tool: Arc<dyn Tool>,
}
```
@ -452,3 +433,4 @@ impl<C: LlmClient> Worker<C> {
3. **選択的購読**: on_*で必要なイベントだけ、またはSubscriberで一括
4. **累積イベントの追加**: Worker層でComplete系イベントを追加提供
5. **後方互換性**: 従来の`run()`も引き続き使用可能

31
llm-worker-macros/src/lib.rs
View File

@ -113,7 +113,7 @@ fn generate_tool_impl(self_ty: &Type, method: &syn::ImplItemFn) -> proc_macro2::
let pascal_name = to_pascal_case(&method_name.to_string());
let tool_struct_name = format_ident!("Tool{}", pascal_name);
let args_struct_name = format_ident!("{}Args", pascal_name);
let definition_name = format_ident!("{}_definition", method_name);
let factory_name = format_ident!("{}_tool", method_name);
// ドキュメントコメントから説明を取得
let description = extract_doc_comment(&method.attrs);
@ -247,24 +247,29 @@ fn generate_tool_impl(self_ty: &Type, method: &syn::ImplItemFn) -> proc_macro2::
#[async_trait::async_trait]
impl ::llm_worker::tool::Tool for #tool_struct_name {
fn name(&self) -> &str {
#tool_name
}
fn description(&self) -> &str {
#description
}
fn input_schema(&self) -> serde_json::Value {
let schema = schemars::schema_for!(#args_struct_name);
serde_json::to_value(schema).unwrap_or(serde_json::json!({}))
}
async fn execute(&self, input_json: &str) -> Result<String, ::llm_worker::tool::ToolError> {
#execute_body
}
}
impl #self_ty {
/// ToolDefinition を取得（Worker への登録用）
pub fn #definition_name(&self) -> ::llm_worker::tool::ToolDefinition {
let ctx = self.clone();
::std::sync::Arc::new(move || {
let schema = schemars::schema_for!(#args_struct_name);
let meta = ::llm_worker::tool::ToolMeta::new(#tool_name)
.description(#description)
.input_schema(serde_json::to_value(schema).unwrap_or(serde_json::json!({})));
let tool: ::std::sync::Arc<dyn ::llm_worker::tool::Tool> =
::std::sync::Arc::new(#tool_struct_name { ctx: ctx.clone() });
(meta, tool)
})
pub fn #factory_name(&self) -> #tool_struct_name {
#tool_struct_name {
ctx: self.clone()
}
}
}
}

3
llm-worker/Cargo.toml
View File

@ -15,8 +15,7 @@ tracing = "0.1"
async-trait = "0.1"
futures = "0.3"
tokio = { version = "1.49", features = ["macros", "rt-multi-thread"] }
tokio-util = "0.7"
reqwest = { version = "0.13.1", default-features = false, features = ["stream", "json", "native-tls", "http2"] }
reqwest = { version = "0.13.1", default-features = false, features = ["stream", "json", "native-tls"] }
eventsource-stream = "0.2"
llm-worker-macros = { path = "../llm-worker-macros", version = "0.1" }

71
llm-worker/examples/worker_cancel_demo.rs
View File

@ -1,71 +0,0 @@
//! Worker のキャンセル機能のデモンストレーション
//!
//! ストリーミング受信中に別スレッドからキャンセルする例
use llm_worker::llm_client::providers::anthropic::AnthropicClient;
use llm_worker::{Worker, WorkerResult};
use std::sync::Arc;
use std::time::Duration;
use tokio::sync::Mutex;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// .envファイルを読み込む
dotenv::dotenv().ok();
// ロギング初期化
tracing_subscriber::fmt()
.with_env_filter(
tracing_subscriber::EnvFilter::try_from_default_env()
.unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("info")),
)
.init();
let api_key =
std::env::var("ANTHROPIC_API_KEY").expect("ANTHROPIC_API_KEY environment variable not set");
let client = AnthropicClient::new(&api_key, "claude-sonnet-4-20250514");
let worker = Arc::new(Mutex::new(Worker::new(client)));
println!("🚀 Starting Worker...");
println!("💡 Will cancel after 2 seconds\n");
// キャンセルSenderを先に取得（ロックを保持しない）
let cancel_tx = {
let w = worker.lock().await;
w.cancel_sender()
};
// タスク1: Workerを実行
let worker_clone = worker.clone();
let task = tokio::spawn(async move {
let mut w = worker_clone.lock().await;
println!("📡 Sending request to LLM...");
match w.run("Tell me a very long story about a brave knight. Make it as detailed as possible with many paragraphs.").await {
Ok(WorkerResult::Finished) => {
println!("✅ Task completed normally");
}
Ok(WorkerResult::Paused) => {
println!("⏸️ Task paused");
}
Err(e) => {
println!("❌ Task error: {}", e);
}
}
});
// タスク2: 2秒後にキャンセル
tokio::spawn(async move {
tokio::time::sleep(Duration::from_secs(2)).await;
println!("\n🛑 Cancelling worker...");
let _ = cancel_tx.send(()).await;
});
// タスク完了を待つ
task.await?;
println!("\n✨ Demo complete!");
Ok(())
}

29
llm-worker/examples/worker_cli.rs
View File

@ -41,7 +41,7 @@ use tracing_subscriber::EnvFilter;
use clap::{Parser, ValueEnum};
use llm_worker::{
Worker,
hook::{Hook, HookError, PostToolCall, PostToolCallContext, PostToolCallResult},
hook::{ControlFlow, HookError, ToolResult, WorkerHook},
llm_client::{
LlmClient,
providers::{
@ -282,22 +282,25 @@ impl ToolResultPrinterHook {
}
#[async_trait]
impl Hook<PostToolCall> for ToolResultPrinterHook {
async fn call(&self, ctx: &mut PostToolCallContext) -> Result<PostToolCallResult, HookError> {
impl WorkerHook for ToolResultPrinterHook {
async fn after_tool_call(
&self,
tool_result: &mut ToolResult,
) -> Result<ControlFlow, HookError> {
let name = self
.call_names
.lock()
.unwrap()
.remove(&ctx.result.tool_use_id)
.unwrap_or_else(|| ctx.result.tool_use_id.clone());
.remove(&tool_result.tool_use_id)
.unwrap_or_else(|| tool_result.tool_use_id.clone());
if ctx.result.is_error {
println!(" Result ({}): ❌ {}", name, ctx.result.content);
if tool_result.is_error {
println!(" Result ({}): ❌ {}", name, tool_result.content);
} else {
println!(" Result ({}): ✅ {}", name, ctx.result.content);
println!(" Result ({}): ✅ {}", name, tool_result.content);
}
Ok(PostToolCallResult::Continue)
Ok(ControlFlow::Continue)
}
}
@ -438,10 +441,8 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
// ツール登録（--no-tools でなければ）
if !args.no_tools {
let app = AppContext;
worker
.register_tool(app.get_current_time_definition())
.unwrap();
worker.register_tool(app.calculate_definition()).unwrap();
worker.register_tool(app.get_current_time_tool());
worker.register_tool(app.calculate_tool());
}
// ストリーミング表示用ハンドラーを登録
@ -450,7 +451,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
.on_text_block(StreamingPrinter::new())
.on_tool_use_block(ToolCallPrinter::new(tool_call_names.clone()));
worker.add_post_tool_call_hook(ToolResultPrinterHook::new(tool_call_names));
worker.add_hook(ToolResultPrinterHook::new(tool_call_names));
// ワンショットモード
if let Some(prompt) = args.prompt {

217
llm-worker/src/hook.rs
View File

@ -8,110 +8,33 @@ use serde_json::Value;
use thiserror::Error;
// =============================================================================
// Hook Event Kinds
// Control Flow Types
// =============================================================================
pub trait HookEventKind: Send + Sync + 'static {
type Input;
type Output;
}
pub struct OnPromptSubmit;
pub struct PreLlmRequest;
pub struct PreToolCall;
pub struct PostToolCall;
pub struct OnTurnEnd;
pub struct OnAbort;
/// Hook処理の制御フロー
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum OnPromptSubmitResult {
Continue,
Cancel(String),
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum PreLlmRequestResult {
Continue,
Cancel(String),
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum PreToolCallResult {
pub enum ControlFlow {
/// 処理を続行
Continue,
/// 現在の処理をスキップ（Tool実行など）
Skip,
/// 処理を中断
Abort(String),
/// 処理を一時停止（再開可能）
Pause,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum PostToolCallResult {
Continue,
Abort(String),
}
/// ターン終了時の判定結果
#[derive(Debug, Clone)]
pub enum OnTurnEndResult {
pub enum TurnResult {
/// ターンを終了
Finish,
/// メッセージを追加してターン継続（自己修正など）
ContinueWithMessages(Vec<crate::Message>),
/// ターンを一時停止
Paused,
}
use std::sync::Arc;
use crate::tool::{Tool, ToolMeta};
/// PreToolCall の入力コンテキスト
pub struct ToolCallContext {
/// ツール呼び出し情報（改変可能）
pub call: ToolCall,
/// ツールメタ情報（不変）
pub meta: ToolMeta,
/// ツールインスタンス（状態アクセス用）
pub tool: Arc<dyn Tool>,
}
/// PostToolCall の入力コンテキスト
pub struct PostToolCallContext {
/// ツール呼び出し情報
pub call: ToolCall,
/// ツール実行結果（改変可能）
pub result: ToolResult,
/// ツールメタ情報（不変）
pub meta: ToolMeta,
/// ツールインスタンス（状態アクセス用）
pub tool: Arc<dyn Tool>,
}
impl HookEventKind for OnPromptSubmit {
type Input = crate::Message;
type Output = OnPromptSubmitResult;
}
impl HookEventKind for PreLlmRequest {
type Input = Vec<crate::Message>;
type Output = PreLlmRequestResult;
}
impl HookEventKind for PreToolCall {
type Input = ToolCallContext;
type Output = PreToolCallResult;
}
impl HookEventKind for PostToolCall {
type Input = PostToolCallContext;
type Output = PostToolCallResult;
}
impl HookEventKind for OnTurnEnd {
type Input = Vec<crate::Message>;
type Output = OnTurnEndResult;
}
impl HookEventKind for OnAbort {
type Input = String;
type Output = ();
}
// =============================================================================
// Tool Call / Result Types
// =============================================================================
@ -179,55 +102,85 @@ pub enum HookError {
}
// =============================================================================
// Hook Trait
// WorkerHook Trait
// =============================================================================
/// Hookイベントの処理を行うトレイト
/// ターンの進行・ツール実行に介入するためのトレイト
///
/// 各イベント種別は戻り値型が異なるため、`HookEventKind`を介して型を制約する。
/// Hookを使うと、メッセージ送信前、ツール実行前後、ターン終了時に
/// 処理を挟んだり、実行をキャンセルしたりできます。
///
/// # Examples
///
/// ```ignore
/// use llm_worker::hook::{ControlFlow, HookError, ToolCall, TurnResult, WorkerHook};
/// use llm_worker::Message;
///
/// struct ValidationHook;
///
/// #[async_trait::async_trait]
/// impl WorkerHook for ValidationHook {
/// async fn before_tool_call(&self, call: &mut ToolCall) -> Result<ControlFlow, HookError> {
/// // 危険なツールをブロック
/// if call.name == "delete_all" {
/// return Ok(ControlFlow::Skip);
/// }
/// Ok(ControlFlow::Continue)
/// }
///
/// async fn on_turn_end(&self, messages: &[Message]) -> Result<TurnResult, HookError> {
/// // 条件を満たさなければ追加メッセージで継続
/// if messages.len() < 3 {
/// return Ok(TurnResult::ContinueWithMessages(vec![
/// Message::user("Please elaborate.")
/// ]));
/// }
/// Ok(TurnResult::Finish)
/// }
/// }
/// ```
///
/// # デフォルト実装
///
/// すべてのメソッドにはデフォルト実装があり、何も行わず`Continue`を返します。
/// 必要なメソッドのみオーバーライドしてください。
#[async_trait]
pub trait Hook<E: HookEventKind>: Send + Sync {
async fn call(&self, input: &mut E::Input) -> Result<E::Output, HookError>;
}
pub trait WorkerHook: Send + Sync {
/// メッセージ送信前に呼ばれる
///
/// リクエストに含まれるメッセージリストを参照・改変できます。
/// `ControlFlow::Abort`を返すとターンが中断されます。
async fn on_message_send(
&self,
_context: &mut Vec<crate::Message>,
) -> Result<ControlFlow, HookError> {
Ok(ControlFlow::Continue)
}
// =============================================================================
// Hook Registry
// =============================================================================
/// ツール実行前に呼ばれる
///
/// ツール呼び出しの引数を書き換えたり、実行をスキップしたりできます。
/// `ControlFlow::Skip`を返すとこのツールの実行がスキップされます。
async fn before_tool_call(&self, _tool_call: &mut ToolCall) -> Result<ControlFlow, HookError> {
Ok(ControlFlow::Continue)
}
/// 全 Hook を保持するレジストリ
///
/// Worker 内部で使用され、各種 Hook を一括管理する。
pub struct HookRegistry {
/// on_prompt_submit Hook
pub(crate) on_prompt_submit: Vec<Box<dyn Hook<OnPromptSubmit>>>,
/// pre_llm_request Hook
pub(crate) pre_llm_request: Vec<Box<dyn Hook<PreLlmRequest>>>,
/// pre_tool_call Hook
pub(crate) pre_tool_call: Vec<Box<dyn Hook<PreToolCall>>>,
/// post_tool_call Hook
pub(crate) post_tool_call: Vec<Box<dyn Hook<PostToolCall>>>,
/// on_turn_end Hook
pub(crate) on_turn_end: Vec<Box<dyn Hook<OnTurnEnd>>>,
/// on_abort Hook
pub(crate) on_abort: Vec<Box<dyn Hook<OnAbort>>>,
}
/// ツール実行後に呼ばれる
///
/// ツールの実行結果を書き換えたり、隠蔽したりできます。
async fn after_tool_call(
&self,
_tool_result: &mut ToolResult,
) -> Result<ControlFlow, HookError> {
Ok(ControlFlow::Continue)
}
impl Default for HookRegistry {
fn default() -> Self {
Self::new()
}
}
impl HookRegistry {
/// 空の HookRegistry を作成
pub fn new() -> Self {
Self {
on_prompt_submit: Vec::new(),
pre_llm_request: Vec::new(),
pre_tool_call: Vec::new(),
post_tool_call: Vec::new(),
on_turn_end: Vec::new(),
on_abort: Vec::new(),
}
/// ターン終了時に呼ばれる
///
/// 生成されたメッセージを検査し、必要なら追加メッセージで継続を指示できます。
/// `TurnResult::ContinueWithMessages`を返すと、指定したメッセージを追加して
/// 次のターンに進みます。
async fn on_turn_end(&self, _messages: &[crate::Message]) -> Result<TurnResult, HookError> {
Ok(TurnResult::Finish)
}
}

11
llm-worker/src/lib.rs
View File

@ -6,7 +6,7 @@
//!
//! - [`Worker`] - LLMとの対話を管理する中心コンポーネント
//! - [`tool::Tool`] - LLMから呼び出し可能なツール
//! - [`hook::Hook`] - ターン進行への介入
//! - [`hook::WorkerHook`] - ターン進行への介入
//! - [`subscriber::WorkerSubscriber`] - ストリーミングイベントの購読
//!
//! # Quick Start
@ -19,7 +19,8 @@
//! .system_prompt("You are a helpful assistant.");
//!
//! // ツールを登録（オプション）
//! // worker.register_tool(my_tool_definition)?;
//! use llm_worker::tool::Tool;
//! worker.register_tool(my_tool);
//!
//! // 対話を実行
//! let history = worker.run("Hello!").await?;
@ -47,5 +48,9 @@ pub mod subscriber;
pub mod timeline;
pub mod tool;
// =============================================================================
// トップレベル公開（最も頻繁に使う型）
// =============================================================================
pub use message::{ContentPart, Message, MessageContent, Role};
pub use worker::{ToolRegistryError, Worker, WorkerConfig, WorkerError, WorkerResult};
pub use worker::{Worker, WorkerConfig, WorkerError};

2
llm-worker/src/llm_client/mod.rs
View File

@ -1,6 +1,6 @@
//! LLMクライアント層
//!
//! 各LLMプロバイダと通信し、統一された[`Event`]
//! 各LLMプロバイダと通信し、統一された[`Event`](crate::llm_client::event::Event)
//! ストリームを出力します。
//!
//! # サポートするプロバイダ

12
llm-worker/src/state.rs
View File

@ -1,7 +1,7 @@
//! Worker状態
//!
//! Type-stateパターンによるキャッシュ保護のための状態マーカー型。
//! Workerは`Mutable` → `CacheLocked`の状態遷移を持ちます。
//! Workerは`Mutable` → `Locked`の状態遷移を持ちます。
/// Worker状態を表すマーカートレイト
///
@ -19,7 +19,7 @@ mod private {
/// - メッセージ履歴の編集（追加、削除、クリア）
/// - ツール・Hookの登録
///
/// `Worker::lock()`により[`CacheLocked`]状態へ遷移できます。
/// `Worker::lock()`により[`Locked`]状態へ遷移できます。
///
/// # Examples
///
@ -42,7 +42,7 @@ pub struct Mutable;
impl private::Sealed for Mutable {}
impl WorkerState for Mutable {}
/// キャッシュロック状態（キャッシュ保護）
/// ロック状態（キャッシュ保護）
///
/// この状態では以下の制限があります：
/// - システムプロンプトの変更不可
@ -54,7 +54,7 @@ impl WorkerState for Mutable {}
/// `Worker::unlock()`により[`Mutable`]状態へ戻せますが、
/// キャッシュ保護が解除されることに注意してください。
#[derive(Debug, Clone, Copy, Default)]
pub struct CacheLocked;
pub struct Locked;
impl private::Sealed for CacheLocked {}
impl WorkerState for CacheLocked {}
impl private::Sealed for Locked {}
impl WorkerState for Locked {}

4
llm-worker/src/subscriber.rs
View File

@ -65,10 +65,10 @@ pub trait WorkerSubscriber: Send {
///
/// ブロック開始時にDefault::default()で生成され、
/// ブロック終了時に破棄される。
type TextBlockScope: Default + Send + Sync;
type TextBlockScope: Default + Send;
/// ツール使用ブロック処理用のスコープ型
type ToolUseBlockScope: Default + Send + Sync;
type ToolUseBlockScope: Default + Send;
// =========================================================================
// ブロックイベント（スコープ管理あり）

63
llm-worker/src/timeline/timeline.rs
View File

@ -17,7 +17,7 @@ use crate::handler::*;
/// 各Handlerは独自のScope型を持つため、Timelineで保持するには型消去が必要です。
/// 通常は直接使用せず、`Timeline::on_text_block()`などのメソッド経由で
/// 自動的にラップされます。
pub trait ErasedHandler<K: Kind>: Send + Sync {
pub trait ErasedHandler<K: Kind>: Send {
/// イベントをディスパッチ
fn dispatch(&mut self, event: &K::Event);
/// スコープを開始（Block開始時）
@ -54,9 +54,9 @@ where
impl<H, K> ErasedHandler<K> for HandlerWrapper<H, K>
where
H: Handler<K> + Send + Sync,
H: Handler<K> + Send,
K: Kind,
H::Scope: Send + Sync,
H::Scope: Send,
{
fn dispatch(&mut self, event: &K::Event) {
if let Some(scope) = &mut self.scope {
@ -78,7 +78,7 @@ where
// =============================================================================
/// ブロックハンドラーの型消去trait
trait ErasedBlockHandler: Send + Sync {
trait ErasedBlockHandler: Send {
fn dispatch_start(&mut self, start: &BlockStart);
fn dispatch_delta(&mut self, delta: &BlockDelta);
fn dispatch_stop(&mut self, stop: &BlockStop);
@ -112,8 +112,8 @@ where
impl<H> ErasedBlockHandler for TextBlockHandlerWrapper<H>
where
H: Handler<TextBlockKind> + Send + Sync,
H::Scope: Send + Sync,
H: Handler<TextBlockKind> + Send,
H::Scope: Send,
{
fn dispatch_start(&mut self, start: &BlockStart) {
if let Some(scope) = &mut self.scope {
@ -185,8 +185,8 @@ where
impl<H> ErasedBlockHandler for ThinkingBlockHandlerWrapper<H>
where
H: Handler<ThinkingBlockKind> + Send + Sync,
H::Scope: Send + Sync,
H: Handler<ThinkingBlockKind> + Send,
H::Scope: Send,
{
fn dispatch_start(&mut self, start: &BlockStart) {
if let Some(scope) = &mut self.scope {
@ -255,8 +255,8 @@ where
impl<H> ErasedBlockHandler for ToolUseBlockHandlerWrapper<H>
where
H: Handler<ToolUseBlockKind> + Send + Sync,
H::Scope: Send + Sync,
H: Handler<ToolUseBlockKind> + Send,
H::Scope: Send,
{
fn dispatch_start(&mut self, start: &BlockStart) {
if let Some(scope) = &mut self.scope {
@ -391,8 +391,8 @@ impl Timeline {
/// UsageKind用のHandlerを登録
pub fn on_usage<H>(&mut self, handler: H) -> &mut Self
where
H: Handler<UsageKind> + Send + Sync + 'static,
H::Scope: Send + Sync,
H: Handler<UsageKind> + Send + 'static,
H::Scope: Send,
{
// Meta系はデフォルトでスコープを開始しておく
let mut wrapper = HandlerWrapper::new(handler);
@ -404,8 +404,8 @@ impl Timeline {
/// PingKind用のHandlerを登録
pub fn on_ping<H>(&mut self, handler: H) -> &mut Self
where
H: Handler<PingKind> + Send + Sync + 'static,
H::Scope: Send + Sync,
H: Handler<PingKind> + Send + 'static,
H::Scope: Send,
{
let mut wrapper = HandlerWrapper::new(handler);
wrapper.start_scope();
@ -416,8 +416,8 @@ impl Timeline {
/// StatusKind用のHandlerを登録
pub fn on_status<H>(&mut self, handler: H) -> &mut Self
where
H: Handler<StatusKind> + Send + Sync + 'static,
H::Scope: Send + Sync,
H: Handler<StatusKind> + Send + 'static,
H::Scope: Send,
{
let mut wrapper = HandlerWrapper::new(handler);
wrapper.start_scope();
@ -428,8 +428,8 @@ impl Timeline {
/// ErrorKind用のHandlerを登録
pub fn on_error<H>(&mut self, handler: H) -> &mut Self
where
H: Handler<ErrorKind> + Send + Sync + 'static,
H::Scope: Send + Sync,
H: Handler<ErrorKind> + Send + 'static,
H::Scope: Send,
{
let mut wrapper = HandlerWrapper::new(handler);
wrapper.start_scope();
@ -440,8 +440,8 @@ impl Timeline {
/// TextBlockKind用のHandlerを登録
pub fn on_text_block<H>(&mut self, handler: H) -> &mut Self
where
H: Handler<TextBlockKind> + Send + Sync + 'static,
H::Scope: Send + Sync,
H: Handler<TextBlockKind> + Send + 'static,
H::Scope: Send,
{
self.text_block_handlers
.push(Box::new(TextBlockHandlerWrapper::new(handler)));
@ -451,8 +451,8 @@ impl Timeline {
/// ThinkingBlockKind用のHandlerを登録
pub fn on_thinking_block<H>(&mut self, handler: H) -> &mut Self
where
H: Handler<ThinkingBlockKind> + Send + Sync + 'static,
H::Scope: Send + Sync,
H: Handler<ThinkingBlockKind> + Send + 'static,
H::Scope: Send,
{
self.thinking_block_handlers
.push(Box::new(ThinkingBlockHandlerWrapper::new(handler)));
@ -462,8 +462,8 @@ impl Timeline {
/// ToolUseBlockKind用のHandlerを登録
pub fn on_tool_use_block<H>(&mut self, handler: H) -> &mut Self
where
H: Handler<ToolUseBlockKind> + Send + Sync + 'static,
H::Scope: Send + Sync,
H: Handler<ToolUseBlockKind> + Send + 'static,
H::Scope: Send,
{
self.tool_use_block_handlers
.push(Box::new(ToolUseBlockHandlerWrapper::new(handler)));
@ -578,21 +578,6 @@ impl Timeline {
pub fn current_block(&self) -> Option<BlockType> {
self.current_block
}
/// 現在アクティブなブロックを中断する
///
/// キャンセルやエラー時に呼び出し、進行中のブロックに対して
/// BlockAbortイベントを発火してスコープをクリーンアップする。
pub fn abort_current_block(&mut self) {
if let Some(block_type) = self.current_block {
let abort = crate::timeline::event::BlockAbort {
index: 0, // インデックスは不明なので0
block_type,
reason: "Cancelled".to_string(),
};
self.handle_block_abort(&abort);
}
}
}
#[cfg(test)]

126
llm-worker/src/tool.rs
View File

@ -3,8 +3,6 @@
//! LLMから呼び出し可能なツールを定義するためのトレイト。
//! 通常は`#[tool]`マクロを使用して自動実装します。
use std::sync::Arc;
use async_trait::async_trait;
use serde_json::Value;
use thiserror::Error;
@ -23,126 +21,64 @@ pub enum ToolError {
Internal(String),
}
// =============================================================================
// ToolMeta - 不変のメタ情報
// =============================================================================
/// ツールのメタ情報（登録時に固定、不変）
///
/// `ToolDefinition` ファクトリから生成され、Worker に登録後は変更されません。
/// LLM へのツール定義送信に使用されます。
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ToolMeta {
/// ツール名（LLMが識別に使用）
pub name: String,
/// ツールの説明（LLMへのプロンプトに含まれる）
pub description: String,
/// 引数のJSON Schema
pub input_schema: Value,
}
impl ToolMeta {
/// 新しい ToolMeta を作成
pub fn new(name: impl Into<String>) -> Self {
Self {
name: name.into(),
description: String::new(),
input_schema: Value::Object(Default::default()),
}
}
/// 説明を設定
pub fn description(mut self, desc: impl Into<String>) -> Self {
self.description = desc.into();
self
}
/// 引数スキーマを設定
pub fn input_schema(mut self, schema: Value) -> Self {
self.input_schema = schema;
self
}
}
// =============================================================================
// ToolDefinition - ファクトリ型
// =============================================================================
/// ツール定義ファクトリ
///
/// 呼び出すと `(ToolMeta, Arc<dyn Tool>)` を返します。
/// Worker への登録時に一度だけ呼び出され、メタ情報とインスタンスが
/// セッションスコープでキャッシュされます。
///
/// # Examples
///
/// ```ignore
/// let def: ToolDefinition = Arc::new(|| {
/// (
/// ToolMeta::new("my_tool")
/// .description("My tool description")
/// .input_schema(json!({"type": "object"})),
/// Arc::new(MyToolImpl { state: 0 }) as Arc<dyn Tool>,
/// )
/// });
/// worker.register_tool(def)?;
/// ```
pub type ToolDefinition = Arc<dyn Fn() -> (ToolMeta, Arc<dyn Tool>) + Send + Sync>;
// =============================================================================
// Tool trait
// =============================================================================
/// LLMから呼び出し可能なツールを定義するトレイト
///
/// ツールはLLMが外部リソースにアクセスしたり、
/// 計算を実行したりするために使用します。
/// セッション中の状態を保持できます。
///
/// # 実装方法
///
/// 通常は`#[tool_registry]`マクロを使用して自動実装します:
/// 通常は`#[tool]`マクロを使用して自動実装します:
///
/// ```ignore
/// #[tool_registry]
/// impl MyApp {
/// #[tool]
/// async fn search(&self, query: String) -> String {
/// use llm_worker::tool;
///
/// #[tool(description = "Search the web for information")]
/// async fn search(query: String) -> String {
/// // 検索処理
/// format!("Results for: {}", query)
/// }
/// }
///
/// // 登録
/// worker.register_tool(app.search_definition())?;
/// ```
///
/// # 手動実装
///
/// ```ignore
/// use llm_worker::tool::{Tool, ToolError, ToolMeta, ToolDefinition};
/// use std::sync::Arc;
/// use llm_worker::tool::{Tool, ToolError};
/// use serde_json::{json, Value};
///
/// struct MyTool { counter: std::sync::atomic::AtomicUsize }
/// struct MyTool;
///
/// #[async_trait::async_trait]
/// impl Tool for MyTool {
/// fn name(&self) -> &str { "my_tool" }
/// fn description(&self) -> &str { "My custom tool" }
/// fn input_schema(&self) -> Value {
/// json!({
/// "type": "object",
/// "properties": {
/// "query": { "type": "string" }
/// },
/// "required": ["query"]
/// })
/// }
/// async fn execute(&self, input: &str) -> Result<String, ToolError> {
/// self.counter.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
/// Ok("result".to_string())
/// }
/// }
///
/// let def: ToolDefinition = Arc::new(|| {
/// (
/// ToolMeta::new("my_tool")
/// .description("My custom tool")
/// .input_schema(serde_json::json!({"type": "object"})),
/// Arc::new(MyTool { counter: Default::default() }) as Arc<dyn Tool>,
/// )
/// });
/// ```
#[async_trait]
pub trait Tool: Send + Sync {
/// ツール名（LLMが識別に使用）
fn name(&self) -> &str;
/// ツールの説明（LLMへのプロンプトに含まれる）
fn description(&self) -> &str;
/// 引数のJSON Schema
///
/// LLMはこのスキーマに従って引数を生成します。
fn input_schema(&self) -> Value;
/// ツールを実行する
///
/// # Arguments

634
llm-worker/src/worker.rs
View File

@ -3,27 +3,19 @@ use std::marker::PhantomData;
use std::sync::{Arc, Mutex};
use futures::StreamExt;
use tokio::sync::mpsc;
use tracing::{debug, info, trace, warn};
use crate::{
ContentPart, Message, MessageContent, Role,
hook::{
Hook, HookError, HookRegistry, OnAbort, OnPromptSubmit, OnPromptSubmitResult, OnTurnEnd,
OnTurnEndResult, PostToolCall, PostToolCallContext, PostToolCallResult, PreLlmRequest,
PreLlmRequestResult, PreToolCall, PreToolCallResult, ToolCall, ToolCallContext, ToolResult,
},
llm_client::{
ClientError, ConfigWarning, LlmClient, Request, RequestConfig,
ToolDefinition as LlmToolDefinition,
},
state::{CacheLocked, Mutable, WorkerState},
hook::{ControlFlow, HookError, ToolCall, ToolResult, TurnResult, WorkerHook},
llm_client::{ClientError, ConfigWarning, LlmClient, Request, RequestConfig, ToolDefinition},
state::{Locked, Mutable, WorkerState},
subscriber::{
ErrorSubscriberAdapter, StatusSubscriberAdapter, TextBlockSubscriberAdapter,
ToolUseBlockSubscriberAdapter, UsageSubscriberAdapter, WorkerSubscriber,
},
timeline::{TextBlockCollector, Timeline, ToolCallCollector},
tool::{Tool, ToolDefinition, ToolError, ToolMeta},
tool::{Tool, ToolError},
};
// =============================================================================
@ -45,22 +37,11 @@ pub enum WorkerError {
/// 処理が中断された
#[error("Aborted: {0}")]
Aborted(String),
/// Cancellation Tokenによって中断された
#[error("Cancelled")]
Cancelled,
/// 設定に関する警告（未サポートのオプション）
#[error("Config warnings: {}", .0.iter().map(|w| w.to_string()).collect::<Vec<_>>().join(", "))]
ConfigWarnings(Vec<ConfigWarning>),
}
/// ツール登録エラー
#[derive(Debug, thiserror::Error)]
pub enum ToolRegistryError {
/// 同名のツールが既に登録されている
#[error("Tool with name '{0}' already registered")]
DuplicateName(String),
}
// =============================================================================
// Worker Config
// =============================================================================
@ -78,11 +59,11 @@ pub struct WorkerConfig {
/// Workerの実行結果（ステータス）
#[derive(Debug)]
pub enum WorkerResult {
pub enum WorkerResult<'a> {
/// 完了（ユーザー入力待ち状態）
Finished,
Finished(&'a [Message]),
/// 一時停止（再開可能）
Paused,
Paused(&'a [Message]),
}
/// 内部用: ツール実行結果
@ -96,7 +77,7 @@ enum ToolExecutionResult {
// =============================================================================
/// ターンイベントを通知するためのコールバック (型消去)
trait TurnNotifier: Send + Sync {
trait TurnNotifier: Send {
fn on_turn_start(&self, turn: usize);
fn on_turn_end(&self, turn: usize);
}
@ -131,7 +112,7 @@ impl<S: WorkerSubscriber + 'static> TurnNotifier for SubscriberTurnNotifier<S> {
/// # 状態遷移（Type-state）
///
/// - [`Mutable`]: 初期状態。システムプロンプトや履歴を自由に編集可能。
/// - [`CacheLocked`]: キャッシュ保護状態。`lock()`で遷移。前方コンテキストは不変。
/// - [`Locked`]: キャッシュ保護状態。`lock()`で遷移。前方コンテキストは不変。
///
/// # Examples
///
@ -166,15 +147,15 @@ pub struct Worker<C: LlmClient, S: WorkerState = Mutable> {
text_block_collector: TextBlockCollector,
/// ツールコールコレクター（Timeline用ハンドラ）
tool_call_collector: ToolCallCollector,
/// 登録されたツール (meta, instance)
tools: HashMap<String, (ToolMeta, Arc<dyn Tool>)>,
/// Hook レジストリ
hooks: HookRegistry,
/// 登録されたツール
tools: HashMap<String, Arc<dyn Tool>>,
/// 登録されたHook
hooks: Vec<Box<dyn WorkerHook>>,
/// システムプロンプト
system_prompt: Option<String>,
/// メッセージ履歴（Workerが所有）
history: Vec<Message>,
/// ロック時点での履歴長（CacheLocked状態でのみ意味を持つ）
/// ロック時点での履歴長（Locked状態でのみ意味を持つ）
locked_prefix_len: usize,
/// ターンカウント
turn_count: usize,
@ -182,11 +163,6 @@ pub struct Worker<C: LlmClient, S: WorkerState = Mutable> {
turn_notifiers: Vec<Box<dyn TurnNotifier>>,
/// リクエスト設定（max_tokens, temperature等）
request_config: RequestConfig,
/// 前回の実行が中断されたかどうか
last_run_interrupted: bool,
/// キャンセル通知用チャネル（実行中断用）
cancel_tx: mpsc::Sender<()>,
cancel_rx: mpsc::Receiver<()>,
/// 状態マーカー
_state: PhantomData<S>,
}
@ -196,57 +172,6 @@ pub struct Worker<C: LlmClient, S: WorkerState = Mutable> {
// =============================================================================
impl<C: LlmClient, S: WorkerState> Worker<C, S> {
fn reset_interruption_state(&mut self) {
self.last_run_interrupted = false;
}
/// ターンを実行
///
/// 新しいユーザーメッセージを履歴に追加し、LLMにリクエストを送信する。
/// ツール呼び出しがある場合は自動的にループする。
pub async fn run(
&mut self,
user_input: impl Into<String>,
) -> Result<WorkerResult, WorkerError> {
self.reset_interruption_state();
// Hook: on_prompt_submit
let mut user_message = Message::user(user_input);
let result = self.run_on_prompt_submit_hooks(&mut user_message).await;
let result = match result {
Ok(value) => value,
Err(err) => return self.finalize_interruption(Err(err)).await,
};
match result {
OnPromptSubmitResult::Cancel(reason) => {
self.last_run_interrupted = true;
return self.finalize_interruption(Err(WorkerError::Aborted(reason))).await;
}
OnPromptSubmitResult::Continue => {}
}
self.history.push(user_message);
let result = self.run_turn_loop().await;
self.finalize_interruption(result).await
}
fn drain_cancel_queue(&mut self) {
use tokio::sync::mpsc::error::TryRecvError;
loop {
match self.cancel_rx.try_recv() {
Ok(()) => continue,
Err(TryRecvError::Empty) | Err(TryRecvError::Disconnected) => break,
}
}
}
fn try_cancelled(&mut self) -> bool {
use tokio::sync::mpsc::error::TryRecvError;
match self.cancel_rx.try_recv() {
Ok(()) => true,
Err(TryRecvError::Empty) => false,
Err(TryRecvError::Disconnected) => true,
}
}
/// イベント購読者を登録する
///
/// 登録したSubscriberは、LLMからのストリーミングイベントを
@ -305,71 +230,52 @@ impl<C: LlmClient, S: WorkerState> Worker<C, S> {
/// ツールを登録する
///
/// 登録されたツールはLLMからの呼び出しで自動的に実行されます。
/// 同名のツールを登録するとエラーになります。
/// 同名のツールを登録した場合、後から登録したものが優先されます。
///
/// # Examples
///
/// ```ignore
/// use llm_worker::tool::{ToolMeta, ToolDefinition, Tool};
/// use std::sync::Arc;
/// use llm_worker::Worker;
/// use my_tools::SearchTool;
///
/// let def: ToolDefinition = Arc::new(|| {
/// (ToolMeta::new("search").description("..."), Arc::new(MyTool) as Arc<dyn Tool>)
/// });
/// worker.register_tool(def)?;
/// worker.register_tool(SearchTool::new());
/// ```
pub fn register_tool(&mut self, factory: ToolDefinition) -> Result<(), ToolRegistryError> {
let (meta, instance) = factory();
if self.tools.contains_key(&meta.name) {
return Err(ToolRegistryError::DuplicateName(meta.name.clone()));
}
self.tools.insert(meta.name.clone(), (meta, instance));
Ok(())
pub fn register_tool(&mut self, tool: impl Tool + 'static) {
let name = tool.name().to_string();
self.tools.insert(name, Arc::new(tool));
}
/// 複数のツールを登録
pub fn register_tools(
&mut self,
factories: impl IntoIterator<Item = ToolDefinition>,
) -> Result<(), ToolRegistryError> {
for factory in factories {
self.register_tool(factory)?;
pub fn register_tools(&mut self, tools: impl IntoIterator<Item = impl Tool + 'static>) {
for tool in tools {
self.register_tool(tool);
}
Ok(())
}
/// on_prompt_submit Hookを追加する
/// Hookを追加する
///
/// `run()` でユーザーメッセージを受け取った直後に呼び出される。
pub fn add_on_prompt_submit_hook(&mut self, hook: impl Hook<OnPromptSubmit> + 'static) {
self.hooks.on_prompt_submit.push(Box::new(hook));
}
/// pre_llm_request Hookを追加する
/// Hookはターンの進行・ツール実行に介入できます。
/// 複数のHookを登録した場合、登録順に実行されます。
///
/// 各ターンのLLMリクエスト送信前に呼び出される。
pub fn add_pre_llm_request_hook(&mut self, hook: impl Hook<PreLlmRequest> + 'static) {
self.hooks.pre_llm_request.push(Box::new(hook));
}
/// pre_tool_call Hookを追加する
pub fn add_pre_tool_call_hook(&mut self, hook: impl Hook<PreToolCall> + 'static) {
self.hooks.pre_tool_call.push(Box::new(hook));
}
/// post_tool_call Hookを追加する
pub fn add_post_tool_call_hook(&mut self, hook: impl Hook<PostToolCall> + 'static) {
self.hooks.post_tool_call.push(Box::new(hook));
}
/// on_turn_end Hookを追加する
pub fn add_on_turn_end_hook(&mut self, hook: impl Hook<OnTurnEnd> + 'static) {
self.hooks.on_turn_end.push(Box::new(hook));
}
/// on_abort Hookを追加する
pub fn add_on_abort_hook(&mut self, hook: impl Hook<OnAbort> + 'static) {
self.hooks.on_abort.push(Box::new(hook));
/// # Examples
///
/// ```ignore
/// use llm_worker::{Worker, WorkerHook, ControlFlow, ToolCall};
///
/// struct LoggingHook;
///
/// #[async_trait::async_trait]
/// impl WorkerHook for LoggingHook {
/// async fn before_tool_call(&self, call: &mut ToolCall) -> Result<ControlFlow, HookError> {
/// println!("Calling tool: {}", call.name);
/// Ok(ControlFlow::Continue)
/// }
/// }
///
/// worker.add_hook(LoggingHook);
/// ```
pub fn add_hook(&mut self, hook: impl WorkerHook + 'static) {
self.hooks.push(Box::new(hook));
}
/// タイムラインへの可変参照を取得（追加ハンドラ登録用）
@ -464,59 +370,19 @@ impl<C: LlmClient, S: WorkerState> Worker<C, S> {
self.request_config.stop_sequences.clear();
}
/// キャンセル通知用Senderを取得する
pub fn cancel_sender(&self) -> mpsc::Sender<()> {
self.cancel_tx.clone()
}
/// リクエスト設定を一括で設定
pub fn set_request_config(&mut self, config: RequestConfig) {
self.request_config = config;
}
/// 実行をキャンセルする
///
/// 現在実行中のストリーミングやツール実行を中断します。
/// 次のイベントループのチェックポイントでWorkerError::Cancelledが返されます。
///
/// # Examples
///
/// ```ignore
/// use std::sync::Arc;
/// let worker = Arc::new(Mutex::new(Worker::new(client)));
///
/// // 別スレッドで実行
/// let worker_clone = worker.clone();
/// tokio::spawn(async move {
/// let mut w = worker_clone.lock().unwrap();
/// w.run("Long task...").await
/// });
///
/// // キャンセル
/// worker.lock().unwrap().cancel();
/// ```
pub fn cancel(&self) {
let _ = self.cancel_tx.try_send(());
}
/// キャンセルされているかチェック
pub fn is_cancelled(&mut self) -> bool {
self.try_cancelled()
}
/// 前回の実行が中断されたかどうか
pub fn last_run_interrupted(&self) -> bool {
self.last_run_interrupted
}
/// 登録されたツールからLLM用ToolDefinitionのリストを生成
fn build_tool_definitions(&self) -> Vec<LlmToolDefinition> {
/// 登録されたツールからToolDefinitionのリストを生成
fn build_tool_definitions(&self) -> Vec<ToolDefinition> {
self.tools
.values()
.map(|(meta, _)| {
LlmToolDefinition::new(&meta.name)
.description(&meta.description)
.input_schema(meta.input_schema.clone())
.map(|tool| {
ToolDefinition::new(tool.name())
.description(tool.description())
.input_schema(tool.input_schema())
})
.collect()
}
@ -564,11 +430,7 @@ impl<C: LlmClient, S: WorkerState> Worker<C, S> {
}
/// リクエストを構築
fn build_request(
&self,
tool_definitions: &[LlmToolDefinition],
context: &[Message],
) -> Request {
fn build_request(&self, tool_definitions: &[ToolDefinition]) -> Request {
let mut request = Request::new();
// システムプロンプトを設定
@ -577,7 +439,7 @@ impl<C: LlmClient, S: WorkerState> Worker<C, S> {
}
// メッセージを追加
for msg in context {
for msg in &self.history {
// Message から llm_client::Message への変換
request = request.message(crate::llm_client::Message {
role: match msg.role {
@ -632,89 +494,37 @@ impl<C: LlmClient, S: WorkerState> Worker<C, S> {
request
}
/// Hooks: on_prompt_submit
///
/// `run()` でユーザーメッセージを受け取った直後に呼び出される（最初だけ）。
async fn run_on_prompt_submit_hooks(
&self,
message: &mut Message,
) -> Result<OnPromptSubmitResult, WorkerError> {
for hook in &self.hooks.on_prompt_submit {
let result = hook.call(message).await?;
match result {
OnPromptSubmitResult::Continue => continue,
OnPromptSubmitResult::Cancel(reason) => {
return Ok(OnPromptSubmitResult::Cancel(reason));
}
}
}
Ok(OnPromptSubmitResult::Continue)
}
/// Hooks: pre_llm_request
///
/// 各ターンのLLMリクエスト送信前に呼び出される（毎ターン）。
async fn run_pre_llm_request_hooks(
&self,
) -> Result<(PreLlmRequestResult, Vec<Message>), WorkerError> {
/// Hooks: on_message_send
async fn run_on_message_send_hooks(&self) -> Result<ControlFlow, WorkerError> {
for hook in &self.hooks {
// Note: Locked状態でも履歴全体を参照として渡す（変更は不可）
// HookのAPIを変更し、immutable参照のみを渡すようにする必要があるかもしれない
// 現在は空のVecを渡して回避（要検討）
let mut temp_context = self.history.clone();
for hook in &self.hooks.pre_llm_request {
let result = hook.call(&mut temp_context).await?;
let result = hook.on_message_send(&mut temp_context).await?;
match result {
PreLlmRequestResult::Continue => continue,
PreLlmRequestResult::Cancel(reason) => {
return Ok((PreLlmRequestResult::Cancel(reason), temp_context));
ControlFlow::Continue => continue,
ControlFlow::Skip => return Ok(ControlFlow::Skip),
ControlFlow::Abort(reason) => return Ok(ControlFlow::Abort(reason)),
ControlFlow::Pause => return Ok(ControlFlow::Pause),
}
}
}
Ok((PreLlmRequestResult::Continue, temp_context))
Ok(ControlFlow::Continue)
}
/// Hooks: on_turn_end
async fn run_on_turn_end_hooks(&self) -> Result<OnTurnEndResult, WorkerError> {
let mut temp_messages = self.history.clone();
for hook in &self.hooks.on_turn_end {
let result = hook.call(&mut temp_messages).await?;
async fn run_on_turn_end_hooks(&self) -> Result<TurnResult, WorkerError> {
for hook in &self.hooks {
let result = hook.on_turn_end(&self.history).await?;
match result {
OnTurnEndResult::Finish => continue,
OnTurnEndResult::ContinueWithMessages(msgs) => {
return Ok(OnTurnEndResult::ContinueWithMessages(msgs));
TurnResult::Finish => continue,
TurnResult::ContinueWithMessages(msgs) => {
return Ok(TurnResult::ContinueWithMessages(msgs));
}
OnTurnEndResult::Paused => return Ok(OnTurnEndResult::Paused),
}
}
Ok(OnTurnEndResult::Finish)
}
/// Hooks: on_abort
async fn run_on_abort_hooks(&self, reason: &str) -> Result<(), WorkerError> {
let mut reason = reason.to_string();
for hook in &self.hooks.on_abort {
hook.call(&mut reason).await?;
}
Ok(())
}
async fn finalize_interruption<T>(
&mut self,
result: Result<T, WorkerError>,
) -> Result<T, WorkerError> {
match result {
Ok(value) => Ok(value),
Err(err) => {
self.last_run_interrupted = true;
let reason = match &err {
WorkerError::Aborted(reason) => reason.clone(),
WorkerError::Cancelled => "Cancelled".to_string(),
_ => err.to_string(),
};
if let Err(hook_err) = self.run_on_abort_hooks(&reason).await {
self.last_run_interrupted = true;
return Err(hook_err);
}
Err(err)
TurnResult::Paused => return Ok(TurnResult::Paused),
}
}
Ok(TurnResult::Finish)
}
/// 未実行のツール呼び出しがあるかチェック（Pauseからの復帰用）
@ -737,83 +547,55 @@ impl<C: LlmClient, S: WorkerState> Worker<C, S> {
}
}
if calls.is_empty() { None } else { Some(calls) }
if calls.is_empty() {
None
} else {
Some(calls)
}
}
/// ツールを並列実行
///
/// 全てのツールに対してpre_tool_callフックを実行後、
/// 許可されたツールを並列に実行し、結果にpost_tool_callフックを適用する。
/// 全てのツールに対してbefore_tool_callフックを実行後、
/// 許可されたツールを並列に実行し、結果にafter_tool_callフックを適用する。
async fn execute_tools(
&mut self,
&self,
tool_calls: Vec<ToolCall>,
) -> Result<ToolExecutionResult, WorkerError> {
use futures::future::join_all;
// ツール呼び出しIDから (ToolCall, Meta, Tool) へのマップ
// PostToolCallフックで必要になるため保持する
let mut call_info_map = HashMap::new();
// Phase 1: pre_tool_call フックを適用（スキップ/中断を判定）
// Phase 1: before_tool_call フックを適用（スキップ/中断を判定）
let mut approved_calls = Vec::new();
for mut tool_call in tool_calls {
// ツール定義を取得
if let Some((meta, tool)) = self.tools.get(&tool_call.name) {
// コンテキストを作成
let mut context = ToolCallContext {
call: tool_call.clone(),
meta: meta.clone(),
tool: tool.clone(),
};
let mut skip = false;
for hook in &self.hooks.pre_tool_call {
let result = hook
.call(&mut context)
.await
.inspect_err(|_| self.last_run_interrupted = true)?;
for hook in &self.hooks {
let result = hook.before_tool_call(&mut tool_call).await?;
match result {
PreToolCallResult::Continue => {}
PreToolCallResult::Skip => {
ControlFlow::Continue => {}
ControlFlow::Skip => {
skip = true;
break;
}
PreToolCallResult::Abort(reason) => {
self.last_run_interrupted = true;
ControlFlow::Abort(reason) => {
return Err(WorkerError::Aborted(reason));
}
PreToolCallResult::Pause => {
self.last_run_interrupted = true;
ControlFlow::Pause => {
return Ok(ToolExecutionResult::Paused);
}
}
}
// フックで変更された内容を反映
tool_call = context.call;
// マップに保存（実行する場合のみ）
if !skip {
call_info_map.insert(
tool_call.id.clone(),
(tool_call.clone(), meta.clone(), tool.clone()),
);
approved_calls.push(tool_call);
}
} else {
// 未知のツールはそのまま承認リストに入れる（実行時にエラーになる）
// Hookは適用しない（Metaがないため）
approved_calls.push(tool_call);
}
}
// Phase 2: 許可されたツールを並列実行（キャンセル可能）
// Phase 2: 許可されたツールを並列実行
let futures: Vec<_> = approved_calls
.into_iter()
.map(|tool_call| {
let tools = &self.tools;
async move {
if let Some((_, tool)) = tools.get(&tool_call.name) {
if let Some(tool) = tools.get(&tool_call.name) {
let input_json =
serde_json::to_string(&tool_call.input).unwrap_or_default();
match tool.execute(&input_json).await {
@ -830,45 +612,26 @@ impl<C: LlmClient, S: WorkerState> Worker<C, S> {
})
.collect();
// ツール実行をキャンセル可能にする
let mut results = tokio::select! {
results = join_all(futures) => results,
cancel = self.cancel_rx.recv() => {
if cancel.is_some() {
info!("Tool execution cancelled");
}
self.timeline.abort_current_block();
self.last_run_interrupted = true;
return Err(WorkerError::Cancelled);
}
};
let mut results = join_all(futures).await;
// Phase 3: post_tool_call フックを適用
// Phase 3: after_tool_call フックを適用
for tool_result in &mut results {
// 保存しておいた情報を取得
if let Some((tool_call, meta, tool)) = call_info_map.get(&tool_result.tool_use_id) {
let mut context = PostToolCallContext {
call: tool_call.clone(),
result: tool_result.clone(),
meta: meta.clone(),
tool: tool.clone(),
};
for hook in &self.hooks.post_tool_call {
let result = hook
.call(&mut context)
.await
.inspect_err(|_| self.last_run_interrupted = true)?;
for hook in &self.hooks {
let result = hook.after_tool_call(tool_result).await?;
match result {
PostToolCallResult::Continue => {}
PostToolCallResult::Abort(reason) => {
self.last_run_interrupted = true;
ControlFlow::Continue => {}
ControlFlow::Skip => break,
ControlFlow::Abort(reason) => {
return Err(WorkerError::Aborted(reason));
}
ControlFlow::Pause => {
// after_tool_callでのPauseは結果を受け入れた後、次の処理前に止まる動作とする
// ここではContinue扱いとし、on_message_send等でPauseすることを期待する
// あるいはここでのPauseをサポートする場合は戻り値を調整する必要がある
// 現状はログを出してContinue
warn!("ControlFlow::Pause in after_tool_call is treated as Continue");
}
}
// フックで変更された結果を反映
*tool_result = context.result;
}
}
@ -876,9 +639,7 @@ impl<C: LlmClient, S: WorkerState> Worker<C, S> {
}
/// 内部で使用するターン実行ロジック
async fn run_turn_loop(&mut self) -> Result<WorkerResult, WorkerError> {
self.reset_interruption_state();
self.drain_cancel_queue();
async fn run_turn_loop(&mut self) -> Result<WorkerResult<'_>, WorkerError> {
let tool_definitions = self.build_tool_definitions();
info!(
@ -890,34 +651,18 @@ impl<C: LlmClient, S: WorkerState> Worker<C, S> {
// Resume check: Pending tool calls
if let Some(tool_calls) = self.get_pending_tool_calls() {
info!("Resuming pending tool calls");
match self.execute_tools(tool_calls).await {
Ok(ToolExecutionResult::Paused) => {
self.last_run_interrupted = true;
return Ok(WorkerResult::Paused);
}
Ok(ToolExecutionResult::Completed(results)) => {
match self.execute_tools(tool_calls).await? {
ToolExecutionResult::Paused => return Ok(WorkerResult::Paused(&self.history)),
ToolExecutionResult::Completed(results) => {
for result in results {
self.history
.push(Message::tool_result(&result.tool_use_id, &result.content));
self.history.push(Message::tool_result(&result.tool_use_id, &result.content));
}
// Continue to loop
}
Err(err) => {
self.last_run_interrupted = true;
return Err(err);
}
}
}
loop {
// キャンセルチェック
if self.try_cancelled() {
info!("Execution cancelled");
self.timeline.abort_current_block();
self.last_run_interrupted = true;
return Err(WorkerError::Cancelled);
}
// ターン開始を通知
let current_turn = self.turn_count;
debug!(turn = current_turn, "Turn start");
@ -925,25 +670,25 @@ impl<C: LlmClient, S: WorkerState> Worker<C, S> {
notifier.on_turn_start(current_turn);
}
// Hook: pre_llm_request
let (control, request_context) = self
.run_pre_llm_request_hooks()
.await
.inspect_err(|_| self.last_run_interrupted = true)?;
// Hook: on_message_send
let control = self.run_on_message_send_hooks().await?;
match control {
PreLlmRequestResult::Cancel(reason) => {
info!(reason = %reason, "Aborted by hook");
ControlFlow::Abort(reason) => {
warn!(reason = %reason, "Aborted by hook");
for notifier in &self.turn_notifiers {
notifier.on_turn_end(current_turn);
}
self.last_run_interrupted = true;
return Err(WorkerError::Aborted(reason));
}
PreLlmRequestResult::Continue => {}
ControlFlow::Pause | ControlFlow::Skip => {
// Skip or Pause -> Pause the worker
return Ok(WorkerResult::Paused(&self.history));
}
ControlFlow::Continue => {}
}
// リクエスト構築
let request = self.build_request(&tool_definitions, &request_context);
let request = self.build_request(&tool_definitions);
debug!(
message_count = request.messages.len(),
tool_count = request.tools.len(),
@ -953,29 +698,10 @@ impl<C: LlmClient, S: WorkerState> Worker<C, S> {
// ストリーム処理
debug!("Starting stream...");
let mut stream = self.client.stream(request).await?;
let mut event_count = 0;
// ストリームを取得（キャンセル可能）
let mut stream = tokio::select! {
stream_result = self.client.stream(request) => stream_result
.inspect_err(|_| self.last_run_interrupted = true)?,
cancel = self.cancel_rx.recv() => {
if cancel.is_some() {
info!("Cancelled before stream started");
}
self.timeline.abort_current_block();
self.last_run_interrupted = true;
return Err(WorkerError::Cancelled);
}
};
loop {
tokio::select! {
// ストリームからイベントを受信
event_result = stream.next() => {
match event_result {
Some(result) => {
match &result {
while let Some(event_result) = stream.next().await {
match &event_result {
Ok(event) => {
trace!(event = ?event, "Received event");
event_count += 1;
@ -984,25 +710,10 @@ impl<C: LlmClient, S: WorkerState> Worker<C, S> {
warn!(error = %e, "Stream error");
}
}
let event = result
.inspect_err(|_| self.last_run_interrupted = true)?;
let event = event_result?;
let timeline_event: crate::timeline::event::Event = event.into();
self.timeline.dispatch(&timeline_event);
}
None => break, // ストリーム終了
}
}
// キャンセル待機
cancel = self.cancel_rx.recv() => {
if cancel.is_some() {
info!("Stream cancelled");
}
self.timeline.abort_current_block();
self.last_run_interrupted = true;
return Err(WorkerError::Cancelled);
}
}
}
debug!(event_count = event_count, "Stream completed");
// ターン終了を通知
@ -1023,42 +734,29 @@ impl<C: LlmClient, S: WorkerState> Worker<C, S> {
if tool_calls.is_empty() {
// ツール呼び出しなし → ターン終了判定
let turn_result = self
.run_on_turn_end_hooks()
.await
.inspect_err(|_| self.last_run_interrupted = true)?;
let turn_result = self.run_on_turn_end_hooks().await?;
match turn_result {
OnTurnEndResult::Finish => {
self.last_run_interrupted = false;
return Ok(WorkerResult::Finished);
TurnResult::Finish => {
return Ok(WorkerResult::Finished(&self.history));
}
OnTurnEndResult::ContinueWithMessages(additional) => {
TurnResult::ContinueWithMessages(additional) => {
self.history.extend(additional);
continue;
}
OnTurnEndResult::Paused => {
self.last_run_interrupted = true;
return Ok(WorkerResult::Paused);
TurnResult::Paused => {
return Ok(WorkerResult::Paused(&self.history));
}
}
}
// ツール実行
match self.execute_tools(tool_calls).await {
Ok(ToolExecutionResult::Paused) => {
self.last_run_interrupted = true;
return Ok(WorkerResult::Paused);
}
Ok(ToolExecutionResult::Completed(results)) => {
match self.execute_tools(tool_calls).await? {
ToolExecutionResult::Paused => return Ok(WorkerResult::Paused(&self.history)),
ToolExecutionResult::Completed(results) => {
for result in results {
self.history
.push(Message::tool_result(&result.tool_use_id, &result.content));
self.history.push(Message::tool_result(&result.tool_use_id, &result.content));
}
}
Err(err) => {
self.last_run_interrupted = true;
return Err(err);
}
}
}
}
@ -1066,10 +764,8 @@ impl<C: LlmClient, S: WorkerState> Worker<C, S> {
/// 実行を再開（Pause状態からの復帰）
///
/// 新しいユーザーメッセージを履歴に追加せず、現在の状態からターン処理を再開する。
pub async fn resume(&mut self) -> Result<WorkerResult, WorkerError> {
self.reset_interruption_state();
let result = self.run_turn_loop().await;
self.finalize_interruption(result).await
pub async fn resume(&mut self) -> Result<WorkerResult<'_>, WorkerError> {
self.run_turn_loop().await
}
}
@ -1083,7 +779,6 @@ impl<C: LlmClient> Worker<C, Mutable> {
let text_block_collector = TextBlockCollector::new();
let tool_call_collector = ToolCallCollector::new();
let mut timeline = Timeline::new();
let (cancel_tx, cancel_rx) = mpsc::channel(1);
// コレクターをTimelineに登録
timeline.on_text_block(text_block_collector.clone());
@ -1095,16 +790,13 @@ impl<C: LlmClient> Worker<C, Mutable> {
text_block_collector,
tool_call_collector,
tools: HashMap::new(),
hooks: HookRegistry::new(),
hooks: Vec::new(),
system_prompt: None,
history: Vec::new(),
locked_prefix_len: 0,
turn_count: 0,
turn_notifiers: Vec::new(),
request_config: RequestConfig::default(),
last_run_interrupted: false,
cancel_tx,
cancel_rx,
_state: PhantomData,
}
}
@ -1254,11 +946,11 @@ impl<C: LlmClient> Worker<C, Mutable> {
self
}
/// ロックしてCacheLocked状態へ遷移
/// ロックしてLocked状態へ遷移
///
/// この操作により、現在のシステムプロンプトと履歴が「確定済みプレフィックス」として
/// 固定される。以降は履歴への追記のみが可能となり、キャッシュヒットが保証される。
pub fn lock(self) -> Worker<C, CacheLocked> {
pub fn lock(self) -> Worker<C, Locked> {
let locked_prefix_len = self.history.len();
Worker {
client: self.client,
@ -1273,20 +965,57 @@ impl<C: LlmClient> Worker<C, Mutable> {
turn_count: self.turn_count,
turn_notifiers: self.turn_notifiers,
request_config: self.request_config,
last_run_interrupted: self.last_run_interrupted,
cancel_tx: self.cancel_tx,
cancel_rx: self.cancel_rx,
_state: PhantomData,
}
}
/// ターンを実行（Mutable状態）
///
/// 新しいユーザーメッセージを履歴に追加し、LLMにリクエストを送信する。
/// ツール呼び出しがある場合は自動的にループする。
///
/// 注意: この関数は履歴を変更するため、キャッシュ保護が必要な場合は
/// `lock()` を呼んでからLocked状態で `run` を使用すること。
pub async fn run(&mut self, user_input: impl Into<String>) -> Result<WorkerResult<'_>, WorkerError> {
self.history.push(Message::user(user_input));
self.run_turn_loop().await
}
/// 複数メッセージでターンを実行（Mutable状態）
///
/// 指定されたメッセージを履歴に追加してから実行する。
pub async fn run_with_messages(
&mut self,
messages: Vec<Message>,
) -> Result<WorkerResult<'_>, WorkerError> {
self.history.extend(messages);
self.run_turn_loop().await
}
}
// =============================================================================
// CacheLocked状態専用の実装
// Locked状態専用の実装
// =============================================================================
impl<C: LlmClient> Worker<C, CacheLocked> {
impl<C: LlmClient> Worker<C, Locked> {
/// ターンを実行（Locked状態）
///
/// 新しいユーザーメッセージを履歴の末尾に追加し、LLMにリクエストを送信する。
/// ロック時点より前の履歴（プレフィックス）は不変であるため、キャッシュヒットが保証される。
pub async fn run(&mut self, user_input: impl Into<String>) -> Result<WorkerResult<'_>, WorkerError> {
self.history.push(Message::user(user_input));
self.run_turn_loop().await
}
/// 複数メッセージでターンを実行（Locked状態）
pub async fn run_with_messages(
&mut self,
messages: Vec<Message>,
) -> Result<WorkerResult<'_>, WorkerError> {
self.history.extend(messages);
self.run_turn_loop().await
}
/// ロック時点のプレフィックス長を取得
pub fn locked_prefix_len(&self) -> usize {
self.locked_prefix_len
@ -1310,9 +1039,6 @@ impl<C: LlmClient> Worker<C, CacheLocked> {
turn_count: self.turn_count,
turn_notifiers: self.turn_notifiers,
request_config: self.request_config,
last_run_interrupted: self.last_run_interrupted,
cancel_tx: self.cancel_tx,
cancel_rx: self.cancel_rx,
_state: PhantomData,
}
}

103
llm-worker/tests/parallel_execution_test.rs
View File

@ -8,12 +8,9 @@ use std::time::{Duration, Instant};
use async_trait::async_trait;
use llm_worker::Worker;
use llm_worker::hook::{
Hook, HookError, PostToolCall, PostToolCallContext, PostToolCallResult, PreToolCall,
PreToolCallResult, ToolCallContext,
};
use llm_worker::hook::{ControlFlow, HookError, ToolCall, ToolResult, WorkerHook};
use llm_worker::llm_client::event::{Event, ResponseStatus, StatusEvent};
use llm_worker::tool::{Tool, ToolDefinition, ToolError, ToolMeta};
use llm_worker::tool::{Tool, ToolError};
mod common;
use common::MockLlmClient;
@ -42,24 +39,25 @@ impl SlowTool {
fn call_count(&self) -> usize {
self.call_count.load(Ordering::SeqCst)
}
/// ToolDefinition を作成
fn definition(&self) -> ToolDefinition {
let tool = self.clone();
Arc::new(move || {
let meta = ToolMeta::new(&tool.name)
.description("A tool that waits before responding")
.input_schema(serde_json::json!({
"type": "object",
"properties": {}
}));
(meta, Arc::new(tool.clone()) as Arc<dyn Tool>)
})
}
}
#[async_trait]
impl Tool for SlowTool {
fn name(&self) -> &str {
&self.name
}
fn description(&self) -> &str {
"A tool that waits before responding"
}
fn input_schema(&self) -> serde_json::Value {
serde_json::json!({
"type": "object",
"properties": {}
})
}
async fn execute(&self, _input_json: &str) -> Result<String, ToolError> {
self.call_count.fetch_add(1, Ordering::SeqCst);
tokio::time::sleep(Duration::from_millis(self.delay_ms)).await;
@ -105,9 +103,9 @@ async fn test_parallel_tool_execution() {
let tool2_clone = tool2.clone();
let tool3_clone = tool3.clone();
worker.register_tool(tool1.definition()).unwrap();
worker.register_tool(tool2.definition()).unwrap();
worker.register_tool(tool3.definition()).unwrap();
worker.register_tool(tool1);
worker.register_tool(tool2);
worker.register_tool(tool3);
let start = Instant::now();
let _result = worker.run("Run all tools").await;
@ -129,7 +127,7 @@ async fn test_parallel_tool_execution() {
println!("Parallel execution completed in {:?}", elapsed);
}
/// Hook: pre_tool_call でスキップされたツールは実行されないことを確認
/// Hook: before_tool_call でスキップされたツールは実行されないことを確認
#[tokio::test]
async fn test_before_tool_call_skip() {
let events = vec![
@ -153,24 +151,27 @@ async fn test_before_tool_call_skip() {
let allowed_clone = allowed_tool.clone();
let blocked_clone = blocked_tool.clone();
worker.register_tool(allowed_tool.definition()).unwrap();
worker.register_tool(blocked_tool.definition()).unwrap();
worker.register_tool(allowed_tool);
worker.register_tool(blocked_tool);
// "blocked_tool" をスキップするHook
struct BlockingHook;
#[async_trait]
impl Hook<PreToolCall> for BlockingHook {
async fn call(&self, ctx: &mut ToolCallContext) -> Result<PreToolCallResult, HookError> {
if ctx.call.name == "blocked_tool" {
Ok(PreToolCallResult::Skip)
impl WorkerHook for BlockingHook {
async fn before_tool_call(
&self,
tool_call: &mut ToolCall,
) -> Result<ControlFlow, HookError> {
if tool_call.name == "blocked_tool" {
Ok(ControlFlow::Skip)
} else {
Ok(PreToolCallResult::Continue)
Ok(ControlFlow::Continue)
}
}
}
worker.add_pre_tool_call_hook(BlockingHook);
worker.add_hook(BlockingHook);
let _result = worker.run("Test hook").await;
@ -187,9 +188,9 @@ async fn test_before_tool_call_skip() {
);
}
/// Hook: post_tool_call で結果が改変されることを確認
/// Hook: after_tool_call で結果が改変されることを確認
#[tokio::test]
async fn test_post_tool_call_modification() {
async fn test_after_tool_call_modification() {
// 複数リクエストに対応するレスポンスを準備
let client = MockLlmClient::with_responses(vec![
// 1回目のリクエスト: ツール呼び出し
@ -219,21 +220,21 @@ async fn test_post_tool_call_modification() {
#[async_trait]
impl Tool for SimpleTool {
fn name(&self) -> &str {
"test_tool"
}
fn description(&self) -> &str {
"Test"
}
fn input_schema(&self) -> serde_json::Value {
serde_json::json!({})
}
async fn execute(&self, _: &str) -> Result<String, ToolError> {
Ok("Original Result".to_string())
}
}
fn simple_tool_definition() -> ToolDefinition {
Arc::new(|| {
let meta = ToolMeta::new("test_tool")
.description("Test")
.input_schema(serde_json::json!({}));
(meta, Arc::new(SimpleTool) as Arc<dyn Tool>)
})
}
worker.register_tool(simple_tool_definition()).unwrap();
worker.register_tool(SimpleTool);
// 結果を改変するHook
struct ModifyingHook {
@ -241,19 +242,19 @@ async fn test_post_tool_call_modification() {
}
#[async_trait]
impl Hook<PostToolCall> for ModifyingHook {
async fn call(
impl WorkerHook for ModifyingHook {
async fn after_tool_call(
&self,
ctx: &mut PostToolCallContext,
) -> Result<PostToolCallResult, HookError> {
ctx.result.content = format!("[Modified] {}", ctx.result.content);
*self.modified_content.lock().unwrap() = Some(ctx.result.content.clone());
Ok(PostToolCallResult::Continue)
tool_result: &mut ToolResult,
) -> Result<ControlFlow, HookError> {
tool_result.content = format!("[Modified] {}", tool_result.content);
*self.modified_content.lock().unwrap() = Some(tool_result.content.clone());
Ok(ControlFlow::Continue)
}
}
let modified_content = Arc::new(std::sync::Mutex::new(None));
worker.add_post_tool_call_hook(ModifyingHook {
worker.add_hook(ModifyingHook {
modified_content: modified_content.clone(),
});

81
llm-worker/tests/tool_macro_test.rs
View File

@ -9,6 +9,7 @@ use std::sync::atomic::{AtomicUsize, Ordering};
use schemars;
use serde;
use llm_worker::tool::Tool;
use llm_worker_macros::tool_registry;
// =============================================================================
@ -50,31 +51,30 @@ async fn test_basic_tool_generation() {
prefix: "Hello".to_string(),
};
// ファクトリメソッドでToolDefinitionを取得
let greet_definition = ctx.greet_definition();
// ファクトリメソッドでツールを取得
let greet_tool = ctx.greet_tool();
// ファクトリを呼び出してMetaとToolを取得
let (meta, tool) = greet_definition();
// 名前の確認
assert_eq!(greet_tool.name(), "greet");
// メタ情報の確認
assert_eq!(meta.name, "greet");
// 説明の確認（docコメントから取得）
let desc = greet_tool.description();
assert!(
meta.description.contains("メッセージに挨拶を追加する"),
desc.contains("メッセージに挨拶を追加する"),
"Description should contain doc comment: {}",
meta.description
desc
);
// スキーマの確認
let schema = greet_tool.input_schema();
println!("Schema: {}", serde_json::to_string_pretty(&schema).unwrap());
assert!(
meta.input_schema.get("properties").is_some(),
schema.get("properties").is_some(),
"Schema should have properties"
);
println!(
"Schema: {}",
serde_json::to_string_pretty(&meta.input_schema).unwrap()
);
// 実行テスト
let result = tool.execute(r#"{"message": "World"}"#).await;
let result = greet_tool.execute(r#"{"message": "World"}"#).await;
assert!(result.is_ok(), "Should execute successfully");
let output = result.unwrap();
assert!(output.contains("Hello"), "Output should contain prefix");
@ -87,11 +87,11 @@ async fn test_multiple_arguments() {
prefix: "".to_string(),
};
let (meta, tool) = ctx.add_definition()();
let add_tool = ctx.add_tool();
assert_eq!(meta.name, "add");
assert_eq!(add_tool.name(), "add");
let result = tool.execute(r#"{"a": 10, "b": 20}"#).await;
let result = add_tool.execute(r#"{"a": 10, "b": 20}"#).await;
assert!(result.is_ok());
let output = result.unwrap();
assert!(output.contains("30"), "Should contain sum: {}", output);
@ -103,12 +103,12 @@ async fn test_no_arguments() {
prefix: "TestPrefix".to_string(),
};
let (meta, tool) = ctx.get_prefix_definition()();
let get_prefix_tool = ctx.get_prefix_tool();
assert_eq!(meta.name, "get_prefix");
assert_eq!(get_prefix_tool.name(), "get_prefix");
// 空のJSONオブジェクトで呼び出し
let result = tool.execute(r#"{}"#).await;
let result = get_prefix_tool.execute(r#"{}"#).await;
assert!(result.is_ok());
let output = result.unwrap();
assert!(
@ -124,10 +124,10 @@ async fn test_invalid_arguments() {
prefix: "".to_string(),
};
let (_, tool) = ctx.greet_definition()();
let greet_tool = ctx.greet_tool();
// 不正なJSON
let result = tool.execute(r#"{"wrong_field": "value"}"#).await;
let result = greet_tool.execute(r#"{"wrong_field": "value"}"#).await;
assert!(result.is_err(), "Should fail with invalid arguments");
}
@ -163,9 +163,9 @@ impl FallibleContext {
#[tokio::test]
async fn test_result_return_type_success() {
let ctx = FallibleContext;
let (_, tool) = ctx.validate_definition()();
let validate_tool = ctx.validate_tool();
let result = tool.execute(r#"{"value": 42}"#).await;
let result = validate_tool.execute(r#"{"value": 42}"#).await;
assert!(result.is_ok(), "Should succeed for positive value");
let output = result.unwrap();
assert!(output.contains("Valid"), "Should contain Valid: {}", output);
@ -174,9 +174,9 @@ async fn test_result_return_type_success() {
#[tokio::test]
async fn test_result_return_type_error() {
let ctx = FallibleContext;
let (_, tool) = ctx.validate_definition()();
let validate_tool = ctx.validate_tool();
let result = tool.execute(r#"{"value": -1}"#).await;
let result = validate_tool.execute(r#"{"value": -1}"#).await;
assert!(result.is_err(), "Should fail for negative value");
let err = result.unwrap_err();
@ -211,12 +211,12 @@ async fn test_sync_method() {
counter: Arc::new(AtomicUsize::new(0)),
};
let (_, tool) = ctx.increment_definition()();
let increment_tool = ctx.increment_tool();
// 3回実行
let result1 = tool.execute(r#"{}"#).await;
let result2 = tool.execute(r#"{}"#).await;
let result3 = tool.execute(r#"{}"#).await;
let result1 = increment_tool.execute(r#"{}"#).await;
let result2 = increment_tool.execute(r#"{}"#).await;
let result3 = increment_tool.execute(r#"{}"#).await;
assert!(result1.is_ok());
assert!(result2.is_ok());
@ -225,22 +225,3 @@ async fn test_sync_method() {
// カウンターは3になっているはず
assert_eq!(ctx.counter.load(Ordering::SeqCst), 3);
}
// =============================================================================
// Test: ToolMeta Immutability
// =============================================================================
#[tokio::test]
async fn test_tool_meta_immutability() {
let ctx = SimpleContext {
prefix: "Test".to_string(),
};
// 2回取得しても同じメタ情報が得られることを確認
let (meta1, _) = ctx.greet_definition()();
let (meta2, _) = ctx.greet_definition()();
assert_eq!(meta1.name, meta2.name);
assert_eq!(meta1.description, meta2.description);
assert_eq!(meta1.input_schema, meta2.input_schema);
}

1
llm-worker/tests/validation_test.rs
View File

@ -1,3 +1,4 @@
use llm_worker::llm_client::LlmClient;
use llm_worker::llm_client::providers::openai::OpenAIClient;
use llm_worker::{Worker, WorkerError};

28
llm-worker/tests/worker_fixtures.rs
View File

@ -12,7 +12,7 @@ use std::sync::atomic::{AtomicUsize, Ordering};
use async_trait::async_trait;
use common::MockLlmClient;
use llm_worker::Worker;
use llm_worker::tool::{Tool, ToolDefinition, ToolError, ToolMeta};
use llm_worker::tool::{Tool, ToolError};
/// フィクスチャディレクトリのパス
fn fixtures_dir() -> std::path::PathBuf {
@ -35,13 +35,20 @@ impl MockWeatherTool {
fn get_call_count(&self) -> usize {
self.call_count.load(Ordering::SeqCst)
}
}
fn definition(&self) -> ToolDefinition {
let tool = self.clone();
Arc::new(move || {
let meta = ToolMeta::new("get_weather")
.description("Get the current weather for a city")
.input_schema(serde_json::json!({
#[async_trait]
impl Tool for MockWeatherTool {
fn name(&self) -> &str {
"get_weather"
}
fn description(&self) -> &str {
"Get the current weather for a city"
}
fn input_schema(&self) -> serde_json::Value {
serde_json::json!({
"type": "object",
"properties": {
"city": {
@ -50,14 +57,9 @@ impl MockWeatherTool {
}
},
"required": ["city"]
}));
(meta, Arc::new(tool.clone()) as Arc<dyn Tool>)
})
}
}
#[async_trait]
impl Tool for MockWeatherTool {
async fn execute(&self, input_json: &str) -> Result<String, ToolError> {
self.call_count.fetch_add(1, Ordering::SeqCst);
@ -156,7 +158,7 @@ async fn test_worker_tool_call() {
// ツールを登録
let weather_tool = MockWeatherTool::new();
let tool_for_check = weather_tool.clone();
worker.register_tool(weather_tool.definition()).unwrap();
worker.register_tool(weather_tool);
// メッセージを送信
let _result = worker.run("What's the weather in Tokyo?").await;

12
llm-worker/tests/worker_state_test.rs
View File

@ -1,6 +1,6 @@
//! Worker状態管理のテスト
//!
//! Type-stateパターン（Mutable/CacheLocked）による状態遷移と
//! Type-stateパターン（Mutable/Locked）による状態遷移と
//! ターン間の状態保持をテストする。
mod common;
@ -95,7 +95,7 @@ fn test_mutable_extend_history() {
// 状態遷移テスト
// =============================================================================
/// lock()でMutable -> CacheLocked状態に遷移することを確認
/// lock()でMutable -> Locked状態に遷移することを確認
#[test]
fn test_lock_transition() {
let client = MockLlmClient::new(vec![]);
@ -108,13 +108,13 @@ fn test_lock_transition() {
// ロック
let locked_worker = worker.lock();
// CacheLocked状態でも履歴とシステムプロンプトにアクセス可能
// Locked状態でも履歴とシステムプロンプトにアクセス可能
assert_eq!(locked_worker.get_system_prompt(), Some("System"));
assert_eq!(locked_worker.history().len(), 2);
assert_eq!(locked_worker.locked_prefix_len(), 2);
}
/// unlock()でCacheLocked -> Mutable状態に遷移することを確認
/// unlock()でLocked -> Mutable状態に遷移することを確認
#[test]
fn test_unlock_transition() {
let client = MockLlmClient::new(vec![]);
@ -172,7 +172,7 @@ async fn test_mutable_run_updates_history() {
));
}
/// CacheLocked状態で複数ターンを実行し、履歴が正しく累積することを確認
/// Locked状態で複数ターンを実行し、履歴が正しく累積することを確認
#[tokio::test]
async fn test_locked_multi_turn_history_accumulation() {
// 2回のリクエストに対応するレスポンスを準備
@ -340,7 +340,7 @@ async fn test_unlock_edit_relock() {
// システムプロンプト保持のテスト
// =============================================================================
/// CacheLocked状態でもシステムプロンプトが保持されることを確認
/// Locked状態でもシステムプロンプトが保持されることを確認
#[test]
fn test_system_prompt_preserved_in_locked_state() {
let client = MockLlmClient::new(vec![]);