fix: preserve worker run generations across restore

# Conflicts:
#	web/workspace/deno.json

.yoi/workflow/ticket-intake-workflow.md

@@ -70,13 +70,12 @@ Intake は以下を行う。
 
 利用可能なら、以下の typed Ticket tools を使う。
 
-- `TicketList`: 既存 Ticket の一覧・重複確認。
-- `TicketShow`: 関連 Ticket の詳細確認。
+- `QueryTicket`: 既存 Ticket の一覧・重複確認。
+- `ShowTicket`: 関連 Ticket の詳細確認。
 - `TicketCreate`: 合意済み Ticket の作成。
 - `TicketComment`: 既存 Ticket refinement / decision / plan の記録。
-- `TicketDoctor`: 必要に応じた整合性確認。
 
-Intake は `TicketReview`, `TicketWorkflowState`, `TicketClose` を通常使わない。review / state transition / close は Orchestrator または reviewer / maintainer workflow の責務である。
+Intake は `MergeRequest*`, `TicketWorkflowState`, `TicketClose` を通常使わない。review authority は assigned Coder が起動した read-only direct-child Reviewer の immutable Merge Request attempt に属し、completion / merge / close は各guarded workflowの責務である。
 
 Ticket tools が利用できない環境では、勝手に file write で代替しない。ユーザーまたは Orchestrator に「Ticket tools がないため materialize できない」と報告し、必要なら `yoi ticket` を使える人間/親 workflow に戻す。
 
@@ -96,7 +95,7 @@ Ticket tools が利用できない環境では、勝手に file write で代替
 
 ### 2. 既存 Ticket を確認する
 
-`TicketList` / `TicketShow` で duplicate / related work を探す。
+`QueryTicket` / `ShowTicket` で duplicate / related work を探す。
 
 確認観点:
 

.yoi/workflow/ticket-orchestrator-routing.md

@@ -36,8 +36,8 @@ TicketCreate / TicketComment
 
 Orchestrator は以下を行う。
 
-- Ticket を `TicketShow` で読む。
-- 必要に応じて関連 Ticket を `TicketList` / `TicketShow` で確認する。
+- Ticket を `ShowTicket` で読む。
+- 必要に応じて関連 Ticket を `QueryTicket` / `ShowTicket` で確認する。
 - Ticket body / thread / artifacts / resolution / review / implementation report を読む。
 - Ticket が Objective context と結びついている場合は、Objective を medium-term goal / motivation / strategy / success criteria / decision context として読む。ただし Objective context は判断背景であり、Ticket body/thread/artifacts や explicit Ticket relations / OrchestrationPlan records を読む代替ではない。
 - repository 状態、関連 docs/code、既存 worktree、visible Pods を必要に応じて明示的に確認する。
@@ -49,6 +49,7 @@ Orchestrator は以下を行う。
 - 既存 umbrella/progress-container Ticket が concrete follow-up Ticket / Objective context で置き換え済みなら、superseded/decomposed として退役・close する routing を検討する。
 - implementation-ready の場合は `multi-agent-workflow` に渡す `IntentPacket` を作る。
 - implementation-ready かつ Ticket が `queued` の場合は、worktree 作成 / implementation Pod `SpawnPod` / coder routing などの side effect の前に、既存の typed Ticket backend/tool path で `queued -> inprogress` を記録する。
+- 人間による `ready -> queued` は、記録済み Ticket scopeについて、実装、current MRのguarded merge、completion記録、Ticket closeまでをWorkspace Orchestratorへ委任するdurable gateである。Orchestratorは`queued -> inprogress`を受理した後、current-ref approval、repository evidence、blocking relations、merge CASを確認して完了まで進め、別のmerge確認を待たない。Ticketがseparate approval gateを明記する場合、またはqueued scope外の新しい判断が必要な場合だけ停止する。
 - 明示的な queue review 中に、他にも queued Ticket が見え、capacity が空いている場合は、各 Ticket について relation / orchestration-plan / dirty state / visible Pods / worktree / conflict risk を確認し、独立して受理できるものを同じ routing pass で追加の `queued -> inprogress` 候補にする。
 - queued Ticket を capacity が見える状態で idle のまま残す場合は、dependency / conflict / capacity / missing planning decision / dirty workspace / reviewer-coder bottleneck / migration boundary / human gate のいずれかに絞った bounded reason を Ticket thread または `TicketOrchestrationPlanRecord` に残す。
 - `ready` または `queued` に concrete missing decision / information がある場合だけ、typed state-change/routing event 付きで `planning` に戻す。その event/comment には missing item、checked context、implementation latitude では足りない理由、次の planning question/action を含める。
@@ -61,7 +62,7 @@ Orchestrator は以下を行う。
 - 人間/上位 Orchestrator の許可または明示的な routing acceptance なしに coder / reviewer Pod や read-only investigation helper Pod を起動しない。
 - unqueued Ticket を capacity 埋めのために開始しない。parallel start の候補は、個別に `queued` であり、人間が routing を許可済みの Ticket に限る。
 - 設計境界の未決定を勝手に implementation-ready として固定しない。
-- merge / close / cleanup 権限を持たない場面で勝手に完了処理しない。
+- Ticketが`ready -> queued`されておらず完了権限を委任されていない場合、またはTicketがseparate approval gateを明記する場合に、勝手にmerge / close / cleanupしない。queued delegationとguarded completion evidenceが揃っている場合は、追加のhuman gateを作らず完了まで進める。
 - Ticket tools があるからといって arbitrary filesystem write を行わない。
 - broad multi-Ticket effort のために新しい umbrella/progress-container Ticket を作らない。
 - parent/child、sub-ticket、umbrella、part-of、contains などの hierarchy/container relation を split/refinement の代替として扱わない。
@@ -73,21 +74,21 @@ Orchestrator は以下を行う。
 
 利用可能なら、以下を使う。
 
-- `TicketList`: routing 候補や関連 Ticket の確認。
-- `TicketShow`: 対象 Ticket の body / thread / artifacts / resolution / typed relation metadata と derived inverse/blocker view を確認。
+- `QueryTicket`: routing 候補、関連 Ticket、project-level forward relation (`depends_on` / `blocks` / `related` / `supersedes` / `duplicate_of`) と derived blocker summary を bounded filter/projection で確認する。`depends_on` と incoming unresolved `blocks` は queue/acceptance blocker であり、`related` は blocker ではない。`supersedes` / `duplicate_of` は visible diagnostic として扱い、自動的な lifecycle 変更や scheduler 判断にはしない。
+- `ShowTicket`: 対象 Ticket の body / thread / artifacts / resolution / typed relation metadata、linked Objective、assignment、implementation/review evidence を確認する。
 - `TicketComment`: routing decision / intent packet / blocked reason / next question の記録。
 - `TicketWorkflowState`: `queued -> inprogress` acceptance、`inprogress -> done`、または concrete missing decision/information reason を伴う `ready|queued -> planning` に使う。
-- `TicketRelationQuery`: project-level の forward relation (`depends_on` / `blocks` / `related` / `supersedes` / `duplicate_of`) を読む。`depends_on` と incoming unresolved `blocks` は queue/acceptance blocker であり、`related` は blocker ではない。`supersedes` / `duplicate_of` は visible diagnostic として扱い、自動的な lifecycle 変更や scheduler 判断にはしない。
+- `TicketDependencyCheck`: queue/acceptance 直前の typed dependency readiness guard に使う。
+- `TicketRelationRecord` / `TicketRelationRemove`: ユーザー合意済みの durable project relation を明示的に更新する場合だけ使う。
 - `TicketOrchestrationPlanQuery`: 対象 Ticket や関連 Ticket の ordering / blocker / conflict / waiting-capacity / accepted-plan 記録を読む。queued acceptance 前に必ず確認する。
 - `TicketOrchestrationPlanRecord`: Orchestrator が routing 中に project-relevant な ordering / dependency / conflict / capacity/waiting / accepted-plan decision を残す。これは queue reorder、自動起動、state 変更ではない。
 - `TicketClose`: 完了権限と resolution が揃っている場合だけ使う。
-- `TicketDoctor`: routing 前後の整合性確認。
 
 `TicketCreate` は通常 Intake の責務だが、routing 中に follow-up Ticket が必要だと判断した場合は、ユーザー/上位 Orchestrator の合意後にだけ使う。
 
 ## Queued acceptance contract
 
-- `queued -> inprogress` acceptance の直前に `TicketShow` / `TicketRelationQuery` の relation blockers を再確認する。unresolved `depends_on` や incoming unresolved `blocks` が残る場合は implementation side effect を始めず、理由を thread に残して `planning` へ戻すか blocked diagnostic として停止する。
+- `queued -> inprogress` acceptance の直前に `ShowTicket` / `QueryTicket` の relation blocker projection を再確認する。unresolved `depends_on` や incoming unresolved `blocks` が残る場合は implementation side effect を始めず、理由を thread に残して `planning` へ戻すか blocked diagnostic として停止する。
 - Relation metadata は project-level constraint であり、OrchestrationPlan は runtime ordering/capacity decision である。relation を OrchestrationPlan で代替しないし、OrchestrationPlan を durable dependency authority として扱わない。
 
 `state = queued` は、Ticket が routing 対象として人間により Orchestrator へ渡された状態である。Orchestrator は queued notification を受けたら、Ticket、workspace state、対象 Ticket の `TicketOrchestrationPlanQuery` 記録、risk domain に応じた bounded project context を読んで、次のどちらかを行う。
@@ -100,7 +101,7 @@ Orchestrator は以下を行う。
 
 Parallel acceptance pass:
 
-- 明示的な queue review 中に複数の queued Ticket が見える場合、Orchestrator は最初の1件の完了待ちを default にしない。各 Ticket について Ticket body/thread/artifacts、TicketRelationQuery、TicketOrchestrationPlanQuery、workspace/worktree dirty state、visible Pods、既存 branches、conflict/dependency notes を確認する。
+- 明示的な queue review 中に複数の queued Ticket が見える場合、Orchestrator は最初の1件の完了待ちを default にしない。各 Ticket について Ticket body/thread/artifacts、QueryTicket の relation/blocker projection、TicketOrchestrationPlanQuery、workspace/worktree dirty state、visible Pods、既存 branches、conflict/dependency notes を確認する。
 - 追加で開始してよいのは、blocking relation/dependency がなく、`do_not_parallelize` または applicable conflict record がなく、source/write surfaces が disjoint または conflict risk が小さく機械的で、coder/reviewer follow-up capacity があり、acceptance basis となる Ticket thread/plan/workspace records を side effect 前に記録・commit でき、別 worktree/branch/scope を切れる Ticket だけである。
 - capacity が見えるのに queued Ticket を idle にする場合は、dependency / conflict / capacity / missing planning decision / dirty workspace / reviewer-coder bottleneck / migration boundary / human gate のいずれかの bounded reason を記録する。
 - この pass は scheduler、background runner、resource graph solver、automatic queue drain loop ではない。unqueued Ticket を開始せず、各 Ticket の `queued -> inprogress` acceptance を個別に記録する。
@@ -269,8 +270,8 @@ Action:
 ### 1. 状態確認
 
 - `git state --short --branch`
-- `TicketShow <target>`
-- 関連 Ticket の `TicketList` / `TicketShow`
+- `ShowTicket <target>`
+- 関連 Ticket の `QueryTicket` / `ShowTicket`
 - 必要に応じて docs/code/workflow/history
 - 必要に応じて visible Pods / worktrees / branches
 

AGENTS.md

@@ -1,38 +1,19 @@
-すでにシステムのドッグフーディングに成功しているが、一旦安定した旧バージョンで、ブラウザ/TUI Client/backend/runtimeの分離とチームスペースとしてのworkspaceを作るObjectiveを進めている。
+すでにシステムのドッグフーディングに成功しており、ブラウザ/TUI Client/backend/runtimeの分離とチームスペースとしてのworkspaceの実装を進めている。
 
 ## このシステムに置ける設計要旨
 
-- プロンプトはすべて resources/promptsに集約している。管理効率の向上と同時に、ユーザーがオーバーライドする形式でもある。
+- プロンプトはすべて`resources/prompts`に集約している。管理効率の向上のためであると同時に、ユーザーがオーバーライドする形式でもある。
 - 変更量を最小にするために設計を歪めたり、設計問題に対して不必要な後方互換性を作らない。長期的なメンテナンスと型安全性を追求すること。
 
 ### LLM コンテキストの加工原則
 
-LLM に投げる context への割り込みは、大きく2種類に分かれる。**前者は許されるが、後者は禁止**。
+LLM に投げる context はappend-onlyが基本であり、またその永続化形式からAPIコールの形式を純粋に再現可能である必要が有る。
 
-Workerの状態から純粋に再現可能で、且つ揮発性の無い操作であることが望ましい。（pruning、tool result の content 切り詰め、prompt cache anchor の付与等）。
-原則として、コンテキストは積み重ねるものであり、一時的にメッセージを差し込むことや、過去のメッセージを改ざんすることはKVキャッシュのヒット率を下げる。
+一時的にメッセージを差し込む等の、揮発性の有るコンテキストの改変や、過去のメッセージを改ざんすることは基本的に禁止されている。
+これを行うと、 LLM はそのコンテキストに基づいて生成を行う一方、次以降のターンでhistoryに残らないため、「自分がなぜその発言/tool call をしたか」の根拠が消えるうえ、prompt cache のヒット率も低下させることになる。
 
-**禁止**: ターンを跨ぐことができない情報に基づいて、history に記録せずに context だけにコンテンツを差し込むこと。これをやると LLM はそれに反応して生成を行う一方、次以降のターンでhistoryに残らないため、「自分がなぜその発言/tool call をしたか」の根拠が消えるうえ、prompt cache のヒット率も低下させることになる。
-
-新しい input を context に乗せたいなら、必ず先に `worker.history` に append して commit すること。`history.json` への永続化はそこから自動的についてくる。Notify / WorkerEvent / `<system-reminder>` 系はこの原則で扱う。
-また、キャッシュを破壊するタイミングは正確にコントロールされる必要があり、キャッシュ破壊とトークン消費のトレードオフに基づいて慎重に設計されるべきである。
-
----
-
-## 実際のセッションを読んでデバッグする
-
-`~/.yoi/sessions`にすべてのセッションがある。jsonlなので、いい感じにBashで読むこと。
-
----
-
-## Git操作
-
-明示的に指示されない限り、読み取り以外の操作は控えること。
-基本はworktree上の一時的なブランチでコミットを重ね、メインブランチに取り込む運用をしている。
-Orchestrator の cwd が orchestration 用ブランチ/worktree の場合、通常作業では親ブランチの dirty state を気にしない。
-コミットメッセージは適当に`<prefix>: *簡潔な1行*`で書いている。
-
-外部の参考プロジェクトは必要に応じてローカルの外部 checkout からReadすること。
+過去のコンテキストの圧縮は、キャッシュ破壊とトークン消費のトレードオフであり、必要であれば行っている。
+しかし、キャッシュを破壊するタイミングと頻度は正確にコントロールされる必要があり、実際のセッションデータの解析に基づいて慎重に設計されるべきである。
 
 ---
 
@@ -43,17 +24,26 @@ Orchestrator の cwd が orchestration 用ブランチ/worktree の場合、通
 ```sh
 cargo test -p <crate> --lib <test-or-module-filter>
 cargo test -p <crate> --test <test-target> <test-filter>
-cargo check -p <crate> -p <dependent-crate>
 ```
 
-完了前には変更内容に応じて、対象crate全体のtest、影響するfeature構成、依存crateのcheckを追加する。通常の差分検証には以下を使う。
+完了前には、workspace rootで必ず`cargo check`を実行する。rootの`cargo check`は
+`default-members`に含まれるTUIやServerを含む通常のcompile closureを確認するため、公開型の
+変更ごとにLLMがreverse dependencyを推測して`-p`を列挙する運用にはしない。
 
 ```sh
+cargo check
+cargo test -p <changed-crate>
 cargo fmt --all -- --check
 git diff --check HEAD
 ```
 
-workspace全体、E2E、Nix/Docker buildなどの重い検証は、変更した境界を狭い検証では証明できない場合や明示的に要求された場合に選ぶ。実行した検証が何を証明するのかを意識し、広い検証を形式的に回すだけにしない。
+変更したcrate全体のtestに加え、影響するfeature構成やtest-only targetがある場合は、その検証を
+追加する。`cargo check`はtestを実行せず、通常有効でないfeatureまでは確認しないため、semanticな
+証明とfeature境界の検証はtargeted test/checkで補う。
+
+workspace全体のtest、`--all-targets`、E2E、Nix/Docker buildなどの重い検証は、変更した境界を
+通常のroot checkと狭い検証では証明できない場合や、明示的に要求された場合に選ぶ。実行した検証が
+何を証明するのかを意識し、広い検証を形式的に回すだけにしない。
 
 ---
 
@@ -61,7 +51,6 @@ workspace全体、E2E、Nix/Docker buildなどの重い検証は、変更した
 
 Yoi Worker で作業する場合、Ticket の authority・ライフサイクル・操作方法は Yoi
 system instructions と、その Worker に提供された typed Ticket tools に従うこと。
-backend や CLI の具体的な手順はこのリポジトリの `AGENTS.md` では重複して定義しない。
 
 Codex など typed Ticket tools が提供されていないクライアントでは、`yoi ticket`
 CLI や保存先の直接操作で Ticket tools を代替しないこと。Ticket の作成・更新は
@@ -70,3 +59,8 @@ Yoi Worker に委ねる。
 ---
 
 YoiでYoiを開発している際、AI自身のフィードバックを元に改善を回すために `docs/report/`ディレクトリに感じた障壁や改善案等を書き残す形にした。 明確に力不足な点/ツールの問題があった場合や、ユーザーからの指示があった際に作ること。
+
+---
+
+絶対に自身が動作しているプロセスを止めないこと。
+マージ後のドッグフーディング環境の更新は必ずユーザーの操作で行う。

Cargo.toml

@@ -2,9 +2,10 @@
 resolver = "2"
 members = [
     "crates/client",
-    "crates/llm-engine",
-    "crates/llm-engine-macros",
+    "crates/agen",
+    "crates/agen-macros",
     "crates/session-store",
+    "crates/standalone",
     "crates/secrets",
     "crates/manifest",
     "crates/mcp",
@@ -17,18 +18,26 @@ members = [
     "crates/session-analytics",
     "crates/lint-common",
     "crates/tools",
+    "crates/fs-operation",
+    "crates/flow",
+    "crates/config-source",
+    "crates/config-source-wasm",
+    "crates/workdir",
     "crates/tui",
     "crates/memory",
     "crates/ticket",
+    "crates/merge-request",
     "crates/project-record",
+    "crates/workspace-api",
     "crates/workspace-server",
     "tests/e2e",
 ]
 default-members = [
     "crates/client",
-    "crates/llm-engine",
-    "crates/llm-engine-macros",
+    "crates/agen",
+    "crates/agen-macros",
     "crates/session-store",
+    "crates/standalone",
     "crates/secrets",
     "crates/manifest",
     "crates/mcp",
@@ -41,10 +50,17 @@ default-members = [
     "crates/session-analytics",
     "crates/lint-common",
     "crates/tools",
+    "crates/fs-operation",
+    "crates/flow",
+    "crates/config-source",
+    "crates/config-source-wasm",
+    "crates/workdir",
     "crates/tui",
     "crates/memory",
     "crates/ticket",
+    "crates/merge-request",
     "crates/project-record",
+    "crates/workspace-api",
     "crates/workspace-server",
 ]
 
@@ -52,27 +68,39 @@ default-members = [
 edition = "2024"
 license = "MIT"
 
+[profile.dev]
+debug = "line-tables-only"
+
+[profile.dev.package."*"]
+debug = false
+
 [workspace.dependencies]
 # Internal crates
 client = { path = "crates/client" }
-llm-engine = { path = "crates/llm-engine", version = "0.2" }
-llm-engine-macros = { path = "crates/llm-engine-macros", version = "0.2" }
+agen = { path = "crates/agen", version = "0.2" }
+agen-macros = { path = "crates/agen-macros", version = "0.2" }
 manifest = { path = "crates/manifest" }
 mcp = { path = "crates/mcp" }
 lint-common = { path = "crates/lint-common" }
 memory = { path = "crates/memory" }
+merge-request = { path = "crates/merge-request" }
 ticket = { path = "crates/ticket" }
 project-record = { path = "crates/project-record" }
 worker = { path = "crates/worker" }
 worker-runtime = { path = "crates/worker-runtime" }
+workspace-api = { path = "crates/workspace-api" }
 yoi-plugin-pdk = { path = "crates/plugin-pdk" }
 yoi = { path = "crates/yoi" }
 protocol = { path = "crates/protocol" }
 session-metrics = { path = "crates/session-metrics" }
 session-analytics = { path = "crates/session-analytics" }
 session-store = { path = "crates/session-store" }
+standalone = { path = "crates/standalone" }
 secrets = { path = "crates/secrets" }
 tools = { path = "crates/tools" }
+config-source = { path = "crates/config-source" }
+fs-operation = { path = "crates/fs-operation" }
+workdir = { path = "crates/workdir" }
 tui = { path = "crates/tui" }
 yoi-workspace-server = { path = "crates/workspace-server" }
 
@@ -82,7 +110,9 @@ yoi-workspace-server = { path = "crates/workspace-server" }
 async-trait = "0.1"
 axum = "0.8"
 base64 = "0.22.1"
-decodal = "0.1.1"
+decodal = "0.4.0"
+decodal-language-service = "0.4.0"
+decodal-language-tools = "0.4.0"
 fs4 = "0.13"
 futures = "0.3"
 libc = "0.2"
@@ -91,9 +121,10 @@ serde = "1.0"
 serde_json = "1.0"
 serde_yaml = "0.9.34"
 tar = "0.4"
-rusqlite = { version = "0.37", features = ["bundled"] }
+rusqlite = { version = "0.37", features = ["backup", "bundled"] }
 ring = "0.17.14"
 sha2 = "0.11"
+ssh-key = { version = "0.6.7", features = ["ed25519", "encryption"] }
 tempfile = "3.27"
 thiserror = "2.0"
 tokio = "1.52"
@@ -101,6 +132,8 @@ tokio-tungstenite = "0.29"
 tower = "0.5"
 toml = "1.1"
 tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
 url = "2.5"
 uuid = "1.23"
+zeroize = "1"
 webauthn-rs = { version = "0.5.2", features = ["danger-allow-state-serialisation", "danger-credential-internals"] }

compose.yaml

@@ -21,7 +21,7 @@ services:
       - "8787"
     volumes:
       - server-data:/server-data
-      - ./docker/workspace:/workspace:ro
+      - /etc/yoi/server.toml:/server-config/server.toml:ro
 
   webui:
     image: yoi-webui:latest

crates/agen-macros/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "agen-macros"
+description = "Procedural macros for declaring agen tools"
+version = "0.2.0"
+edition.workspace = true
+rust-version = "1.85"
+license.workspace = true
+readme = "README.md"
+repository = "https://gitea.hareworks.net/Hare/yoi"
+homepage = "https://gitea.hareworks.net/Hare/yoi"
+documentation = "https://docs.rs/agen-macros"
+keywords = ["llm", "agent", "tools", "macros"]
+categories = ["development-tools::procedural-macro-helpers"]
+include = ["src/**", "README.md", "LICENSE"]
+
+[lib]
+proc-macro = true
+
+[dependencies]
+proc-macro2 = "1"
+quote = "1"
+syn = { version = "2", features = ["full"] }
+
+[package.metadata.docs.rs]
+all-features = true

crates/agen-macros/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Hare
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

crates/agen-macros/README.md

@@ -0,0 +1,32 @@
+# agen-macros
+
+Procedural macros used by [`agen`](https://crates.io/crates/agen) to declare LLM tools from Rust methods.
+
+Applications should normally depend only on `agen` and import its re-exports:
+
+```rust
+use agen::tool_registry;
+
+#[derive(Clone)]
+struct Tools;
+
+#[tool_registry]
+impl Tools {
+    /// Returns the supplied text.
+    #[tool]
+    async fn echo(
+        &self,
+        #[description = "Text to return"] text: String,
+    ) -> Result<String, std::io::Error> {
+        Ok(text)
+    }
+}
+```
+
+`#[tool_registry]` generates the argument schema, a `Tool` implementation, and an `<method>_definition` constructor. It rejects arguments of its own, duplicate `#[tool]` markers, malformed or duplicate `#[description = "..."]` attributes, and non-identifier argument patterns.
+
+Generated code targets the canonical `::agen` path and uses implementation dependencies re-exported by `agen`; consumers do not need direct `serde`, `schemars`, `serde_json`, or `async-trait` dependencies. Renaming the `agen` dependency in `Cargo.toml` is not currently supported.
+
+This companion package is published before the matching `agen` release. Its public contract is the generated API consumed by `agen`, and its minor version compatibility follows the `agen` 0.2 series.
+
+Licensed under the [MIT License](https://gitea.hareworks.net/Hare/yoi/src/branch/develop/LICENSE).

crates/agen-macros/src/lib.rs

@@ -0,0 +1,482 @@
+//! Procedural macros for declaring [`agen`](https://docs.rs/agen) tools.
+//!
+//! [`tool_registry`] expands methods marked with `#[tool]` into `agen::tool::Tool`
+//! implementations and tool definitions. Applications normally use the re-exports from
+//! `agen`; this companion crate exists so those macros can be published and versioned
+//! independently.
+
+use proc_macro::TokenStream;
+use quote::{format_ident, quote};
+use syn::{
+    Attribute, FnArg, ImplItem, ItemImpl, Lit, Meta, Pat, ReturnType, Type, parse_macro_input,
+    spanned::Spanned,
+};
+
+/// Generates tools for methods marked with `#[tool]` in an `impl` block.
+///
+/// Method doc comments become the tool description. An argument can use
+/// `#[description = "..."]` to supply its JSON Schema description.
+///
+/// ```ignore
+/// #[derive(Clone)]
+/// struct MyApp;
+///
+/// #[agen::tool_registry]
+/// impl MyApp {
+///     /// Retrieves a user by ID.
+///     #[tool]
+///     async fn get_user(
+///         &self,
+///         #[description = "The user ID"] user_id: String,
+///     ) -> Result<String, std::io::Error> {
+///         todo!()
+///     }
+/// }
+/// ```
+///
+/// This generates a `ToolGetUser` wrapper, a `GetUserArgs` schema type, and
+/// `MyApp::get_user_definition()`.
+#[proc_macro_attribute]
+pub fn tool_registry(attr: TokenStream, item: TokenStream) -> TokenStream {
+    let attr = proc_macro2::TokenStream::from(attr);
+    let impl_block = parse_macro_input!(item as ItemImpl);
+
+    expand_tool_registry(attr, impl_block)
+        .unwrap_or_else(syn::Error::into_compile_error)
+        .into()
+}
+
+fn expand_tool_registry(
+    attr: proc_macro2::TokenStream,
+    mut impl_block: ItemImpl,
+) -> syn::Result<proc_macro2::TokenStream> {
+    if !attr.is_empty() {
+        return Err(syn::Error::new(
+            attr.span(),
+            "tool_registry does not accept arguments",
+        ));
+    }
+
+    let self_ty = impl_block.self_ty.as_ref().clone();
+    let mut generated_items = Vec::new();
+
+    for item in &mut impl_block.items {
+        let ImplItem::Fn(method) = item else {
+            continue;
+        };
+
+        let tool_attrs: Vec<_> = method
+            .attrs
+            .iter()
+            .filter(|attr| attr.path().is_ident("tool"))
+            .collect();
+        if tool_attrs.len() > 1 {
+            return Err(syn::Error::new_spanned(
+                tool_attrs[1],
+                "duplicate #[tool] attribute",
+            ));
+        }
+        let Some(tool_attr) = tool_attrs.first() else {
+            continue;
+        };
+        if !matches!(tool_attr.meta, Meta::Path(_)) {
+            return Err(syn::Error::new_spanned(
+                tool_attr,
+                "#[tool] does not accept arguments",
+            ));
+        }
+
+        method.attrs.retain(|attr| !attr.path().is_ident("tool"));
+        generated_items.push(generate_tool_impl(&self_ty, method)?);
+
+        for input in &mut method.sig.inputs {
+            if let FnArg::Typed(pat_type) = input {
+                pat_type
+                    .attrs
+                    .retain(|attr| !attr.path().is_ident("description"));
+            }
+        }
+    }
+
+    Ok(quote! {
+        #impl_block
+
+        #(#generated_items)*
+    })
+}
+
+fn extract_doc_comment(attrs: &[Attribute]) -> String {
+    let mut lines = Vec::new();
+
+    for attr in attrs {
+        if attr.path().is_ident("doc")
+            && let Meta::NameValue(meta) = &attr.meta
+            && let syn::Expr::Lit(expr_lit) = &meta.value
+            && let Lit::Str(lit_str) = &expr_lit.lit
+        {
+            let line = lit_str.value();
+            let trimmed = line.strip_prefix(' ').unwrap_or(&line);
+            lines.push(trimmed.to_string());
+        }
+    }
+
+    lines.join("\n")
+}
+
+fn extract_description_attr(attrs: &[Attribute]) -> syn::Result<Option<String>> {
+    let mut description = None;
+
+    for attr in attrs
+        .iter()
+        .filter(|attr| attr.path().is_ident("description"))
+    {
+        let value = match &attr.meta {
+            Meta::NameValue(meta) => match &meta.value {
+                syn::Expr::Lit(expr_lit) => match &expr_lit.lit {
+                    Lit::Str(value) => value.value(),
+                    _ => {
+                        return Err(syn::Error::new_spanned(
+                            attr,
+                            "description must be a string literal",
+                        ));
+                    }
+                },
+                _ => {
+                    return Err(syn::Error::new_spanned(
+                        attr,
+                        "description must be a string literal",
+                    ));
+                }
+            },
+            _ => {
+                return Err(syn::Error::new_spanned(
+                    attr,
+                    "expected #[description = \"...\"]",
+                ));
+            }
+        };
+
+        if description.replace(value).is_some() {
+            return Err(syn::Error::new_spanned(
+                attr,
+                "duplicate #[description] attribute",
+            ));
+        }
+    }
+
+    Ok(description)
+}
+
+fn argument_ident(pat: &Pat) -> syn::Result<&syn::Ident> {
+    match pat {
+        Pat::Ident(pat_ident) => Ok(&pat_ident.ident),
+        _ => Err(syn::Error::new_spanned(
+            pat,
+            "tool arguments must use simple identifier patterns",
+        )),
+    }
+}
+
+fn is_tool_execution_context_type(ty: &Type) -> bool {
+    let Type::Path(path) = ty else {
+        return false;
+    };
+    path.path
+        .segments
+        .last()
+        .is_some_and(|segment| segment.ident == "ToolExecutionContext")
+}
+
+fn generate_tool_impl(
+    self_ty: &Type,
+    method: &syn::ImplItemFn,
+) -> syn::Result<proc_macro2::TokenStream> {
+    let sig = &method.sig;
+    let method_name = &sig.ident;
+    let tool_name = method_name.to_string();
+
+    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 description = extract_doc_comment(&method.attrs);
+    let description = if description.is_empty() {
+        format!("Tool: {}", tool_name)
+    } else {
+        description
+    };
+
+    let method_args: Vec<_> = sig
+        .inputs
+        .iter()
+        .filter_map(|arg| match arg {
+            FnArg::Typed(pat_type) => Some(pat_type),
+            FnArg::Receiver(_) => None,
+        })
+        .collect();
+    let json_args: Vec<_> = method_args
+        .iter()
+        .copied()
+        .filter(|pat_type| !is_tool_execution_context_type(pat_type.ty.as_ref()))
+        .collect();
+
+    let arg_fields: Vec<_> = json_args
+        .iter()
+        .map(|pat_type| {
+            let field_name = argument_ident(pat_type.pat.as_ref())?;
+            let ty = &pat_type.ty;
+            let description = extract_description_attr(&pat_type.attrs)?;
+
+            Ok(if let Some(description) = description {
+                quote! {
+                    #[schemars(description = #description)]
+                    pub #field_name: #ty
+                }
+            } else {
+                quote! {
+                    pub #field_name: #ty
+                }
+            })
+        })
+        .collect::<syn::Result<_>>()?;
+
+    let call_args: Vec<_> = method_args
+        .iter()
+        .map(|pat_type| {
+            if is_tool_execution_context_type(pat_type.ty.as_ref()) {
+                Ok(quote! { ctx.clone() })
+            } else {
+                let ident = argument_ident(pat_type.pat.as_ref())?;
+                Ok(quote! { args.#ident })
+            }
+        })
+        .collect::<syn::Result<_>>()?;
+    let method_call = if call_args.is_empty() {
+        quote! { self.ctx.#method_name() }
+    } else {
+        quote! { self.ctx.#method_name(#(#call_args),*) }
+    };
+
+    let awaiter = if sig.asyncness.is_some() {
+        quote! { .await }
+    } else {
+        quote! {}
+    };
+
+    let result_handling = if is_result_type(&sig.output) {
+        quote! {
+            match result {
+                Ok(val) => Ok(format!("{:?}", val).into()),
+                Err(error) => Err(::agen::tool::ToolError::ExecutionFailed(format!("{}", error))),
+            }
+        }
+    } else {
+        quote! {
+            Ok(format!("{:?}", result).into())
+        }
+    };
+
+    let args_struct_def = quote! {
+        #[derive(
+            ::agen::__private::serde::Deserialize,
+            ::agen::__private::schemars::JsonSchema,
+        )]
+        #[serde(crate = "::agen::__private::serde")]
+        #[schemars(crate = "::agen::__private::schemars")]
+        struct #args_struct_name {
+            #(#arg_fields),*
+        }
+    };
+
+    let execute_body = if json_args.is_empty() {
+        quote! {
+            let _: #args_struct_name = ::agen::__private::serde_json::from_str(input_json)
+                .unwrap_or(#args_struct_name {});
+
+            let result = #method_call #awaiter;
+            #result_handling
+        }
+    } else {
+        quote! {
+            let args: #args_struct_name = ::agen::__private::serde_json::from_str(input_json)
+                .map_err(|error| ::agen::tool::ToolError::InvalidArgument(error.to_string()))?;
+
+            let result = #method_call #awaiter;
+            #result_handling
+        }
+    };
+
+    Ok(quote! {
+        #args_struct_def
+
+        #[derive(Clone)]
+        pub struct #tool_struct_name {
+            ctx: #self_ty,
+        }
+
+        #[::agen::__private::async_trait::async_trait]
+        impl ::agen::tool::Tool for #tool_struct_name {
+            async fn execute(
+                &self,
+                input_json: &str,
+                ctx: ::agen::tool::ToolExecutionContext,
+            ) -> Result<::agen::tool::ToolOutput, ::agen::tool::ToolError> {
+                let _ = &ctx;
+                #execute_body
+            }
+        }
+
+        impl #self_ty {
+            /// Returns a tool definition for registration with an `agen::Engine`.
+            pub fn #definition_name(&self) -> ::agen::tool::ToolDefinition {
+                let ctx = self.clone();
+                ::std::sync::Arc::new(move || {
+                    let schema = ::agen::__private::schemars::schema_for!(#args_struct_name);
+                    let meta = ::agen::tool::ToolMeta::new(#tool_name)
+                        .description(#description)
+                        .input_schema(
+                            ::agen::__private::serde_json::to_value(schema)
+                                .unwrap_or_else(|_| ::agen::__private::serde_json::json!({})),
+                        );
+                    let tool: ::std::sync::Arc<dyn ::agen::tool::Tool> =
+                        ::std::sync::Arc::new(#tool_struct_name { ctx: ctx.clone() });
+                    (meta, tool)
+                })
+            }
+        }
+    })
+}
+
+fn is_result_type(return_type: &ReturnType) -> bool {
+    match return_type {
+        ReturnType::Default => false,
+        ReturnType::Type(_, ty) => {
+            if let Type::Path(type_path) = ty.as_ref()
+                && let Some(segment) = type_path.path.segments.last()
+            {
+                return segment.ident == "Result";
+            }
+            false
+        }
+    }
+}
+
+fn to_pascal_case(s: &str) -> String {
+    s.split('_')
+        .map(|part| {
+            let mut chars = part.chars();
+            match chars.next() {
+                None => String::new(),
+                Some(first) => first.to_uppercase().chain(chars).collect(),
+            }
+        })
+        .collect()
+}
+
+/// Marker attribute interpreted by [`tool_registry`].
+#[proc_macro_attribute]
+pub fn tool(attr: TokenStream, item: TokenStream) -> TokenStream {
+    marker_attribute("tool", attr, item)
+}
+
+/// Argument description marker interpreted by [`tool_registry`].
+///
+/// Use it as `#[description = "The argument description"]` on a tool method argument.
+#[proc_macro_attribute]
+pub fn description(attr: TokenStream, item: TokenStream) -> TokenStream {
+    marker_attribute("description", attr, item)
+}
+
+fn marker_attribute(name: &str, attr: TokenStream, item: TokenStream) -> TokenStream {
+    if attr.is_empty() {
+        item
+    } else {
+        syn::Error::new(
+            proc_macro2::Span::call_site(),
+            format!("{name} is a marker interpreted by #[tool_registry]"),
+        )
+        .into_compile_error()
+        .into()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use quote::quote;
+    use syn::parse_quote;
+
+    #[test]
+    fn rejects_tool_registry_arguments() {
+        let implementation: ItemImpl = parse_quote!(impl Registry {});
+        let error = expand_tool_registry(quote!(unexpected), implementation).unwrap_err();
+
+        assert!(error.to_string().contains("does not accept arguments"));
+    }
+
+    #[test]
+    fn rejects_duplicate_tool_markers() {
+        let implementation: ItemImpl = parse_quote! {
+            impl Registry {
+                #[tool]
+                #[tool]
+                fn inspect(&self) {}
+            }
+        };
+        let error = expand_tool_registry(quote!(), implementation).unwrap_err();
+
+        assert!(error.to_string().contains("duplicate #[tool]"));
+    }
+
+    #[test]
+    fn rejects_invalid_description_attributes() {
+        let implementation: ItemImpl = parse_quote! {
+            impl Registry {
+                #[tool]
+                fn inspect(&self, #[description] input: String) {}
+            }
+        };
+        let error = expand_tool_registry(quote!(), implementation).unwrap_err();
+
+        assert!(error.to_string().contains("expected #[description"));
+    }
+
+    #[test]
+    fn rejects_duplicate_description_attributes() {
+        let implementation: ItemImpl = parse_quote! {
+            impl Registry {
+                #[tool]
+                fn inspect(
+                    &self,
+                    #[description = "first"]
+                    #[description = "second"]
+                    input: String,
+                ) {}
+            }
+        };
+        let error = expand_tool_registry(quote!(), implementation).unwrap_err();
+
+        assert!(error.to_string().contains("duplicate #[description]"));
+    }
+
+    #[test]
+    fn generated_code_uses_only_agen_runtime_paths() {
+        let implementation: ItemImpl = parse_quote! {
+            impl Registry {
+                #[tool]
+                fn inspect(&self, input: String) -> Result<String, Error> {
+                    unreachable!()
+                }
+            }
+        };
+        let expanded = expand_tool_registry(quote!(), implementation)
+            .unwrap()
+            .to_string();
+
+        assert!(expanded.contains(":: agen :: tool :: Tool"));
+        assert!(expanded.contains(":: agen :: __private :: serde_json"));
+        assert!(expanded.contains(":: agen :: __private :: serde"));
+        assert!(expanded.contains(":: agen :: __private :: schemars"));
+    }
+}

crates/agen/Cargo.toml

@@ -1,17 +1,27 @@
 [package]
-name = "llm-engine"
-description = "A library for building autonomous LLM-powered systems"
+name = "agen"
+description = "Provider-neutral orchestration for tool-using LLM applications"
 version = "0.2.1"
 edition.workspace = true
+rust-version = "1.86"
 license.workspace = true
+readme = "README.md"
+repository = "https://gitea.hareworks.net/Hare/yoi"
+homepage = "https://gitea.hareworks.net/Hare/yoi"
+documentation = "https://docs.rs/agen"
+keywords = ["llm", "agent", "tools", "streaming", "orchestration"]
+categories = ["api-bindings", "asynchronous"]
+include = ["src/**", "tests/**", "examples/*.rs", "docs/**", "README.md", "LICENSE"]
+autoexamples = false
 
 [features]
 default = []
-codex = ["dep:base64", "dep:chrono"]
+codex = ["dep:chrono"]
 
 [dependencies]
 serde = { workspace = true, features = ["derive"] }
 serde_json = { workspace = true }
+schemars = { workspace = true }
 thiserror = { workspace = true }
 tracing = { workspace = true }
 async-trait = { workspace = true }
@@ -21,15 +31,25 @@ tokio-util = "0.7"
 reqwest = { version = "0.13", default-features = false, features = ["stream", "json", "native-tls", "http2"] }
 eventsource-stream = "0.2"
 zstd = "0.13"
-base64 = { version = "0.22.1", optional = true }
+base64 = "0.22.1"
 chrono = { version = "0.4", default-features = false, features = ["serde", "clock"], optional = true }
-llm-engine-macros = { workspace = true }
+agen-macros = { workspace = true }
 
 [dev-dependencies]
 clap = { version = "4.5", features = ["derive", "env"] }
-schemars = { workspace = true }
 tempfile = { workspace = true }
 dotenv = "0.15"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 trybuild = "1.0.116"
 wiremock = "0.6.5"
+
+[[example]]
+name = "engine_cancel_demo"
+path = "examples/engine_cancel_demo.rs"
+
+[[example]]
+name = "engine_cli"
+path = "examples/engine_cli.rs"
+
+[package.metadata.docs.rs]
+all-features = true

crates/agen/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Hare
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

crates/agen/README.md

@@ -0,0 +1,91 @@
+# agen
+
+`agen` is a provider-neutral Rust engine for streaming LLM applications that use tools. It owns the turn loop, typed conversation history, provider wire-format adapters, tool execution, interceptors, usage accounting, and cache-aware state transitions.
+
+> `agen` is pre-1.0. Public APIs may change between minor releases.
+
+## Installation
+
+```toml
+[dependencies]
+agen = "0.2.1"
+```
+
+The default feature set is intentionally empty. Enable the experimental Codex/ChatGPT authentication adapter when needed:
+
+```toml
+agen = { version = "0.2.1", features = ["codex"] }
+```
+
+`agen` requires Rust 1.86 or newer. The companion `agen-macros` package requires Rust 1.85 or newer.
+
+## Quick start
+
+Supply an implementation of [`LlmClient`](https://docs.rs/agen/latest/agen/llm_client/trait.LlmClient.html), keep conversation history in your application, then run a turn. The first call consumes the mutable engine and returns a cache-locked engine for later turns.
+
+```no_run
+use agen::{Engine, EngineError, History};
+use agen::llm_client::LlmClient;
+
+async fn conversation<C: LlmClient>(client: C) -> Result<(), EngineError> {
+    let mut history = History::new();
+    let output = Engine::new(client)
+        .system_prompt("You are a concise assistant.")
+        .run(&mut history, "Explain typed state in one sentence.")
+        .await;
+
+    let mut engine = output.engine;
+    let _result = engine.run(&mut history, "Give a Rust example.").await;
+    Ok(())
+}
+```
+
+## Declaring tools
+
+The tool macros are re-exported by `agen`; applications do not need direct dependencies on `serde`, `schemars`, `serde_json`, or `async-trait` for generated code.
+
+```rust
+use agen::tool_registry;
+
+#[derive(Clone)]
+struct Tools;
+
+#[tool_registry]
+impl Tools {
+    /// Returns the supplied text.
+    #[tool]
+    async fn echo(
+        &self,
+        #[description = "Text to return"] text: String,
+    ) -> Result<String, std::io::Error> {
+        Ok(text)
+    }
+}
+
+let definition = Tools.echo_definition();
+assert_eq!(definition().0.name, "echo");
+```
+
+The generated API uses the canonical crate name `agen`. Renaming the `agen` dependency in `Cargo.toml` is not currently supported by these macros.
+
+## Features
+
+| Feature | Default | Adds |
+|---|---:|---|
+| `codex` | No | Experimental Codex/ChatGPT auth-file loading and token refresh support |
+
+The base crate includes provider-neutral transport and Anthropic, OpenAI-compatible, Gemini, and Ollama wire-format schemes. See [`llm_client`](https://docs.rs/agen/latest/agen/llm_client/) for the client boundary.
+
+## Architecture and API scope
+
+The current public modules cover the engine, typed history, client transport/schemes, timeline events, tools, interceptors, pruning, token estimation, and usage records. Their relationships are described in [Architecture](https://gitea.hareworks.net/Hare/yoi/src/branch/develop/crates/agen/docs/architecture.md); behavioral requirements are summarized in [Requirements](https://gitea.hareworks.net/Hare/yoi/src/branch/develop/crates/agen/docs/requirements.md).
+
+Low-level modules remain public in the 0.2 series because downstream Yoi components implement custom clients, event handlers, pruning policies, and tool registries against them. This surface is versioned as pre-1.0 API rather than declared stable.
+
+## Packaging and security
+
+The published package contains source, public documentation, curated examples, and deterministic tests/fixtures. Credentialed fixture-recording utilities are intentionally excluded. Examples that contact a provider read credentials from environment variables and never embed production credentials.
+
+## License
+
+Licensed under the [MIT License](https://gitea.hareworks.net/Hare/yoi/src/branch/develop/LICENSE).

crates/agen/docs/architecture.md

@@ -0,0 +1,62 @@
+# agen architecture
+
+`agen` separates orchestration, event projection, and provider transport so applications can replace an LLM client without changing the turn loop or tool model.
+
+```text
+┌────────────────────────────────────────────┐
+│ Engine                                     │
+│ turn loop · interceptors · tool execution  │
+│ typed state: Mutable → Locked → Mutable    │
+└─────────────────────┬──────────────────────┘
+                      │
+┌─────────────────────▼──────────────────────┐
+│ Timeline                                   │
+│ event dispatch · block collectors          │
+└─────────────────────┬──────────────────────┘
+                      │
+┌─────────────────────▼──────────────────────┐
+│ LlmClient                                  │
+│ transport · provider wire-format schemes   │
+└────────────────────────────────────────────┘
+```
+
+## Main modules
+
+| Module | Responsibility |
+|---|---|
+| `engine` | Turn execution, pause/resume, retries, tool integration, and callbacks |
+| `state` | Sealed `Mutable` and `Locked` type-state markers |
+| `interceptor` | Application-owned control decisions at orchestration boundaries |
+| `tool` / `tool_server` | Tool metadata, registration, execution, and bounded output |
+| `timeline` | Streaming event dispatch, handlers, and block assembly |
+| `llm_client` | Provider-neutral request, response, auth, transport, and scheme contracts |
+| `providers` | Optional higher-level provider adapters such as the `codex` feature |
+| `prune` / `token_counter` | Cache-aware history reduction and token estimation |
+| `usage_record` | Request and token usage accounting |
+
+## Request flow
+
+```text
+Engine history
+  → provider-neutral Request
+    → Scheme::build_request
+      → Provider transport
+```
+
+## Response flow
+
+```text
+streaming response bytes
+  → Scheme event parsing
+    → unified Event values
+      → Timeline handlers and collectors
+        → Engine history/tool decisions
+```
+
+## Type state and cache protection
+
+`Engine<C, Mutable>` permits configuration and history editing. `Engine::run` or `Engine::lock` commits the current prefix and produces `Engine<C, Locked>`. The locked engine may append turns without mutating the committed prefix. `Engine::unlock` explicitly returns to mutable state when an application accepts losing that cache guarantee.
+
+## Public surface
+
+The 0.2 series exposes the low-level client, timeline, tool, pruning, and usage modules because custom clients and orchestration hosts build directly on them. These APIs are intentionally provider-neutral but remain pre-1.0 and may change in later minor releases.

crates/agen/docs/requirements.md

@@ -0,0 +1,39 @@
+# agen requirements
+
+## R1: Turn execution and continuation
+
+- `Engine::run` starts a turn and loops through provider output and tool calls.
+- An `Interceptor` may continue, cancel, or pause work at defined orchestration boundaries.
+- `Engine::resume` continues paused generation without fabricating another user message.
+- Cancellation and provider errors are represented as typed `EngineError` values.
+
+## R2: Explicit cache-preserving state
+
+- `Engine<C, Mutable>` permits configuration and history edits.
+- `Engine::run` or `Engine::lock` transitions to `Engine<C, Locked>` and records the committed prefix.
+- A locked engine appends turns but cannot mutate that prefix through mutable-only APIs.
+- `Engine::unlock` explicitly abandons the lock before configuration or history changes.
+
+## R3: Tool declarations and execution
+
+- `#[tool_registry]` generates a schema and `Tool` implementation for methods marked `#[tool]`.
+- `#[description = "..."]` supplies argument descriptions in generated JSON Schema.
+- Generated code resolves its runtime and helper dependencies through `::agen`.
+- Invalid and duplicate marker attributes produce compile errors rather than panics.
+- Tools execute through `ToolServer` with typed context, errors, and output limits.
+
+## R4: Provider-neutral orchestration
+
+- `LlmClient` is the boundary between the engine and provider-specific transport.
+- Request/response schemes translate provider wire formats into shared request and event types.
+- Interceptors, tool execution, timeline collection, and pruning stay above the provider transport.
+- Provider-specific capabilities are optional features when they require additional policy or dependencies.
+
+## R5: Publication quality
+
+- crates.io metadata includes license, repository, documentation, README, categories, keywords, and MSRV.
+- The default feature set and each optional feature compile and test independently.
+- Macro expansion compiles in a downstream-style integration test without direct helper dependencies.
+- rustdoc builds without dependency documentation.
+- Package contents are explicitly bounded and exclude credentialed fixture-recording utilities.
+- `cargo package` and `cargo publish --dry-run` are run for `agen-macros` before `agen` because the main package depends on its companion package.

crates/agen/examples/engine_cancel_demo.rs

@@ -2,9 +2,9 @@
 //!
 //! Example of cancelling from another thread during streaming
 
-use llm_engine::llm_client::scheme::{Scheme, anthropic::AnthropicScheme};
-use llm_engine::llm_client::transport::{HttpTransport, ResolvedAuth};
-use llm_engine::{Engine, EngineResult};
+use agen::llm_client::scheme::{Scheme, anthropic::AnthropicScheme};
+use agen::llm_client::transport::{HttpTransport, ResolvedAuth};
+use agen::{Engine, EngineRunExit, RunInterruptionReason};
 use std::time::Duration;
 
 #[tokio::main]
@@ -29,6 +29,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     let base_url = scheme.default_base_url().to_string();
     let client = HttpTransport::new(scheme, model, base_url, ResolvedAuth::ApiKey(api_key), cap);
     let engine = Engine::new(client);
+    let mut history = agen::History::new();
 
     println!("🚀 Starting Engine...");
     println!("💡 Will cancel after 2 seconds\n");
@@ -45,16 +46,15 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
     println!("📡 Sending request to LLM...");
 
-    match engine.run("Tell me a very long story about a brave knight. Make it as detailed as possible with many paragraphs.").await {
-        Ok(out) => match out.result {
-            EngineResult::Finished => println!("✅ Task completed normally"),
-            EngineResult::Paused => println!("⏸️  Task paused"),
-            EngineResult::LimitReached => println!("🔒 Turn limit reached"),
-            EngineResult::Yielded => println!("↩️  Task yielded"),
-        },
-        Err(e) => {
-            println!("❌ Task error: {}", e);
+    let output = engine.run(&mut history, "Tell me a very long story about a brave knight. Make it as detailed as possible with many paragraphs.").await;
+    match output.result {
+        EngineRunExit::Finished => println!("✅ Task completed normally"),
+        EngineRunExit::Paused => println!("⏸️  Task paused"),
+        EngineRunExit::Yielded => println!("↩️  Task yielded"),
+        EngineRunExit::Interrupted(RunInterruptionReason::LimitReached) => {
+            println!("🔒 Turn limit reached")
         }
+        EngineRunExit::Interrupted(reason) => println!("❌ Task interrupted: {reason:?}"),
     }
 
     println!("\n✨ Demo complete!");

crates/agen/examples/engine_cli.rs

@@ -38,10 +38,9 @@ use async_trait::async_trait;
 use tracing::info;
 use tracing_subscriber::EnvFilter;
 
-use clap::{Parser, ValueEnum};
-use llm_engine::{
-    Engine,
-    interceptor::{Interceptor, PostToolAction, ToolResultInfo},
+use agen::{
+    Engine, EngineRunExit, RunInterruptionReason,
+    interceptor::{Interceptor, InterceptorResult, PostToolAction, ToolResultInfo},
     llm_client::{
         LlmClient,
         capability::{CacheStrategy, ModelCapability, StructuredOutput, ToolCallingSupport},
@@ -51,12 +50,9 @@ use llm_engine::{
         transport::{HttpTransport, ResolvedAuth},
     },
     timeline::{Handler, TextBlockEvent, TextBlockKind, ToolUseBlockEvent, ToolUseBlockKind},
+    tool_registry,
 };
-use llm_engine_macros::tool_registry;
-
-// Required imports for macro expansion
-use schemars;
-use serde;
+use clap::{Parser, ValueEnum};
 
 // =============================================================================
 // Provider Definition
@@ -284,7 +280,10 @@ impl ToolResultPrinterPolicy {
 
 #[async_trait]
 impl Interceptor for ToolResultPrinterPolicy {
-    async fn post_tool_call(&self, info: &mut ToolResultInfo) -> PostToolAction {
+    async fn post_tool_call(
+        &self,
+        info: &ToolResultInfo<'_, ()>,
+    ) -> InterceptorResult<PostToolAction> {
         let name = self
             .call_names
             .lock()
@@ -298,7 +297,7 @@ impl Interceptor for ToolResultPrinterPolicy {
             println!("   Result ({}): ✅ {}", name, info.result.summary);
         }
 
-        PostToolAction::Continue
+        Ok(PostToolAction::Continue)
     }
 }
 
@@ -455,6 +454,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
     // Create Engine
     let mut engine = Engine::new(client);
+    let mut history = agen::History::new();
 
     let tool_call_names = Arc::new(Mutex::new(HashMap::new()));
 
@@ -480,12 +480,10 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
     // One-shot mode
     if let Some(prompt) = args.prompt {
-        match engine.run(&prompt).await {
-            Ok(_) => {}
-            Err(e) => {
-                eprintln!("\n❌ Error: {}", e);
-                std::process::exit(1);
-            }
+        let output = engine.run(&mut history, &prompt).await;
+        if let EngineRunExit::Interrupted(RunInterruptionReason::Unexpected(error)) = output.result
+        {
+            eprintln!("\n❌ Error: {error}");
         }
 
         return Ok(());
@@ -504,13 +502,8 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         return Ok(());
     }
 
-    let mut locked = match engine.run(first_input).await {
-        Ok(out) => out.engine,
-        Err(e) => {
-            eprintln!("\n❌ Error: {}", e);
-            return Ok(());
-        }
-    };
+    let output = engine.run(&mut history, first_input).await;
+    let mut locked = output.engine;
 
     loop {
         print!("\n👤 You: ");
@@ -529,11 +522,10 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
             break;
         }
 
-        match locked.run(input).await {
-            Ok(_) => {}
-            Err(e) => {
-                eprintln!("\n❌ Error: {}", e);
-            }
+        if let EngineRunExit::Interrupted(RunInterruptionReason::Unexpected(error)) =
+            locked.run(&mut history, input).await
+        {
+            eprintln!("\n❌ Error: {error}");
         }
     }
 

crates/agen/examples/record_test_fixtures/main.rs

@@ -19,11 +19,11 @@
 mod recorder;
 mod scenarios;
 
-use clap::{Parser, ValueEnum};
-use llm_engine::llm_client::scheme::{
+use agen::llm_client::scheme::{
     Scheme, anthropic::AnthropicScheme, gemini::GeminiScheme, openai_chat::OpenAIScheme,
 };
-use llm_engine::llm_client::transport::{HttpTransport, ResolvedAuth};
+use agen::llm_client::transport::{HttpTransport, ResolvedAuth};
+use clap::{Parser, ValueEnum};
 
 fn make_transport<S: Scheme>(scheme: S, model: &str, auth: ResolvedAuth) -> HttpTransport<S> {
     let cap = scheme.default_capability();

crates/agen/examples/record_test_fixtures/recorder.rs

@@ -7,8 +7,8 @@ use std::io::{BufWriter, Write};
 use std::path::Path;
 use std::time::{Instant, SystemTime, UNIX_EPOCH};
 
+use agen::llm_client::{LlmClient, Request};
 use futures::StreamExt;
-use llm_engine::llm_client::{LlmClient, Request};
 
 /// Recorded event
 #[derive(Debug, serde::Serialize, serde::Deserialize)]

crates/agen/examples/record_test_fixtures/scenarios.rs

@@ -2,7 +2,7 @@
 //!
 //! Defines requests and output file names for each scenario
 
-use llm_engine::llm_client::{Request, ToolDefinition};
+use agen::llm_client::{Request, ToolDefinition};
 
 /// Test scenario
 pub struct TestScenario {

crates/agen/src/handler.rs

@@ -32,7 +32,7 @@ pub trait Kind {
 /// # Examples
 ///
 /// ```ignore
-/// use llm_engine::timeline::{Handler, TextBlockEvent, TextBlockKind};
+/// use agen::timeline::{Handler, TextBlockEvent, TextBlockKind};
 ///
 /// struct TextCollector {
 ///     texts: Vec<String>,

crates/agen/src/history.rs

@@ -0,0 +1,199 @@
+//! Typed conversation history containers.
+//!
+//! Agen keeps provider-visible [`Item`](crate::Item) values separate from any
+//! host-domain provenance. The host chooses the annotation type `A`, while Agen
+//! preserves each item and annotation as one entry for clone/truncate/restore
+//! style history operations.
+
+use serde::{Deserialize, Serialize};
+
+use crate::Item;
+
+/// One conversation-history entry with host-owned annotation.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct HistoryEntry<A = ()> {
+    /// Provider/model-visible conversation item.
+    pub item: Item,
+    /// Host-domain metadata kept with the item and never projected to providers.
+    pub annotation: A,
+}
+
+impl<A> HistoryEntry<A> {
+    /// Build an entry from an item and its annotation.
+    pub fn new(item: Item, annotation: A) -> Self {
+        Self { item, annotation }
+    }
+
+    /// Split the entry into its item and annotation.
+    pub fn into_parts(self) -> (Item, A) {
+        (self.item, self.annotation)
+    }
+}
+
+impl HistoryEntry<()> {
+    /// Build a unit-annotated entry.
+    pub fn from_item(item: Item) -> Self {
+        Self {
+            item,
+            annotation: (),
+        }
+    }
+}
+
+/// Conversation history with one annotation per item.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
+pub struct History<A = ()> {
+    entries: Vec<HistoryEntry<A>>,
+}
+
+impl<A> History<A> {
+    /// Create an empty history.
+    pub fn new() -> Self {
+        Self {
+            entries: Vec::new(),
+        }
+    }
+
+    /// Build history from already annotated entries, preserving order.
+    pub fn from_entries(entries: Vec<HistoryEntry<A>>) -> Self {
+        Self { entries }
+    }
+
+    /// Replace all entries as one restore/rebuild operation and return the old entries.
+    pub fn replace_entries(&mut self, entries: Vec<HistoryEntry<A>>) -> Vec<HistoryEntry<A>> {
+        std::mem::replace(&mut self.entries, entries)
+    }
+
+    /// Borrow annotated entries.
+    pub fn entries(&self) -> &[HistoryEntry<A>] {
+        &self.entries
+    }
+
+    /// Mutably borrow annotated entries for host-owned rebuild operations.
+    pub fn entries_mut(&mut self) -> &mut [HistoryEntry<A>] {
+        &mut self.entries
+    }
+
+    /// Consume the history into annotated entries.
+    pub fn into_entries(self) -> Vec<HistoryEntry<A>> {
+        self.entries
+    }
+
+    /// Number of entries.
+    pub fn len(&self) -> usize {
+        self.entries.len()
+    }
+
+    /// Whether the history is empty.
+    pub fn is_empty(&self) -> bool {
+        self.entries.is_empty()
+    }
+
+    /// Iterate over annotated entries.
+    pub fn iter(&self) -> impl ExactSizeIterator<Item = &HistoryEntry<A>> {
+        self.entries.iter()
+    }
+
+    /// Iterate over provider-visible items only.
+    pub fn items(&self) -> impl ExactSizeIterator<Item = &Item> {
+        self.entries.iter().map(|entry| &entry.item)
+    }
+
+    /// Clone provider-visible items into a request-local projection.
+    pub fn items_cloned(&self) -> Vec<Item> {
+        self.items().cloned().collect()
+    }
+
+    /// Append an already annotated entry.
+    pub fn push_entry(&mut self, entry: HistoryEntry<A>) {
+        self.entries.push(entry);
+    }
+
+    /// Append many already annotated entries.
+    pub fn extend_entries(&mut self, entries: impl IntoIterator<Item = HistoryEntry<A>>) {
+        self.entries.extend(entries);
+    }
+
+    /// Commit one item through a trusted annotation callback before it becomes live.
+    ///
+    /// The callback may durably persist the item and returns the annotation that
+    /// must be stored with it. If the callback fails, the history is left unchanged.
+    pub fn append_with(
+        &mut self,
+        item: Item,
+        annotate: &mut impl FnMut(&Item) -> Result<A, String>,
+    ) -> Result<(), String> {
+        let annotation = annotate(&item)?;
+        self.entries.push(HistoryEntry { item, annotation });
+        Ok(())
+    }
+
+    /// Commit items through a trusted annotation callback before they become live.
+    ///
+    /// Items before a failure remain appended; the failing item and later items do
+    /// not enter history. This mirrors append-only durable logs where each accepted
+    /// item is already committed before the next item is attempted.
+    pub fn extend_with(
+        &mut self,
+        items: impl IntoIterator<Item = Item>,
+        annotate: &mut impl FnMut(&Item) -> Result<A, String>,
+    ) -> Result<(), String> {
+        for item in items {
+            self.append_with(item, annotate)?;
+        }
+        Ok(())
+    }
+
+    /// Truncate entries, preserving item+annotation pairing for retained entries.
+    pub fn truncate(&mut self, len: usize) {
+        self.entries.truncate(len);
+    }
+
+    /// Clear all entries.
+    pub fn clear(&mut self) {
+        self.entries.clear();
+    }
+}
+
+impl History<()> {
+    /// Build unit-annotated history from provider-visible items.
+    pub fn from_items(items: Vec<Item>) -> Self {
+        Self {
+            entries: items.into_iter().map(HistoryEntry::from_item).collect(),
+        }
+    }
+
+    /// Replace history from provider-visible items using unit annotations.
+    pub fn replace_items(&mut self, items: Vec<Item>) -> Vec<HistoryEntry<()>> {
+        self.replace_entries(items.into_iter().map(HistoryEntry::from_item).collect())
+    }
+
+    /// Append one item with unit annotation.
+    pub fn push(&mut self, item: Item) {
+        self.entries.push(HistoryEntry::from_item(item));
+    }
+
+    /// Append items with unit annotations.
+    pub fn extend_items(&mut self, items: impl IntoIterator<Item = Item>) {
+        self.entries
+            .extend(items.into_iter().map(HistoryEntry::from_item));
+    }
+}
+
+impl<A> IntoIterator for History<A> {
+    type Item = HistoryEntry<A>;
+    type IntoIter = std::vec::IntoIter<HistoryEntry<A>>;
+
+    fn into_iter(self) -> Self::IntoIter {
+        self.entries.into_iter()
+    }
+}
+
+impl<'a, A> IntoIterator for &'a History<A> {
+    type Item = &'a HistoryEntry<A>;
+    type IntoIter = std::slice::Iter<'a, HistoryEntry<A>>;
+
+    fn into_iter(self) -> Self::IntoIter {
+        self.entries.iter()
+    }
+}

crates/agen/src/interceptor.rs

@@ -0,0 +1,423 @@
+//! Interceptor - control flow delegation for the Engine execution loop
+//!
+//! Defines the [`Interceptor`] trait that callers implement to inject
+//! orchestration decisions (approval, skip, pause, abort) into the Engine's
+//! turn loop without the Engine knowing about host-application concepts.
+
+use std::sync::Arc;
+
+use async_trait::async_trait;
+
+use crate::Item;
+use crate::engine::EngineRunExit;
+use crate::history::HistoryEntry;
+use crate::tool::{Tool, ToolCall, ToolExecutionContext, ToolMeta, ToolResult};
+
+// =============================================================================
+// Typed lifecycle metadata and failures
+// =============================================================================
+
+/// Maximum UTF-8 byte length retained for interceptor diagnostics.
+pub const MAX_INTERCEPTOR_DIAGNOSTIC_BYTES: usize = 1024;
+
+/// Stable category for the source of an interceptor failure.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum InterceptorErrorCategory {
+    Policy,
+    Dependency,
+    ContractViolation,
+    Internal,
+}
+
+impl std::fmt::Display for InterceptorErrorCategory {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter.write_str(match self {
+            Self::Policy => "policy",
+            Self::Dependency => "dependency",
+            Self::ContractViolation => "contract_violation",
+            Self::Internal => "internal",
+        })
+    }
+}
+
+/// A typed, bounded failure returned by an [`Interceptor`] implementation.
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+#[error("{category}: {diagnostic}")]
+pub struct InterceptorError {
+    category: InterceptorErrorCategory,
+    diagnostic: String,
+}
+
+impl InterceptorError {
+    pub fn new(category: InterceptorErrorCategory, diagnostic: impl Into<String>) -> Self {
+        let mut diagnostic = diagnostic.into();
+        if diagnostic.len() > MAX_INTERCEPTOR_DIAGNOSTIC_BYTES {
+            let mut end = MAX_INTERCEPTOR_DIAGNOSTIC_BYTES;
+            while !diagnostic.is_char_boundary(end) {
+                end -= 1;
+            }
+            diagnostic.truncate(end);
+        }
+        Self {
+            category,
+            diagnostic,
+        }
+    }
+
+    pub fn category(&self) -> InterceptorErrorCategory {
+        self.category
+    }
+
+    pub fn diagnostic(&self) -> &str {
+        &self.diagnostic
+    }
+}
+
+/// The lifecycle phase at which an interceptor callback executes.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum InterceptorPhase {
+    #[default]
+    PromptSubmit,
+    PendingHistoryAppends,
+    PreLlmRequest,
+    PreToolCall,
+    PostToolCall,
+    AssistantTurnEnd,
+    RunExit,
+}
+
+impl std::fmt::Display for InterceptorPhase {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter.write_str(match self {
+            Self::PromptSubmit => "prompt_submit",
+            Self::PendingHistoryAppends => "pending_history_appends",
+            Self::PreLlmRequest => "pre_llm_request",
+            Self::PreToolCall => "pre_tool_call",
+            Self::PostToolCall => "post_tool_call",
+            Self::AssistantTurnEnd => "assistant_turn_end",
+            Self::RunExit => "run_exit",
+        })
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
+pub struct InterceptorRunId(pub u64);
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct InterceptorTurnId(pub u64);
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub enum InterceptorCallId {
+    Llm(u64),
+    Tool(String),
+}
+
+/// Saturating public counter used by interceptor contexts.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Default)]
+pub struct InterceptorCounter(u32);
+
+impl InterceptorCounter {
+    pub fn from_usize(value: usize) -> Self {
+        Self(u32::try_from(value).unwrap_or(u32::MAX))
+    }
+
+    pub fn get(self) -> u32 {
+        self.0
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub struct InterceptorCounters {
+    pub invocation: InterceptorCounter,
+    pub engine_turn: InterceptorCounter,
+    pub run_turn: InterceptorCounter,
+    pub llm_call: InterceptorCounter,
+    pub tool_batch: InterceptorCounter,
+    pub tool_call: InterceptorCounter,
+}
+
+/// Identity, phase, and bounded counters common to every lifecycle callback.
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct InterceptorInvocation {
+    pub run_id: InterceptorRunId,
+    pub turn_id: Option<InterceptorTurnId>,
+    pub call_id: Option<InterceptorCallId>,
+    pub phase: InterceptorPhase,
+    pub counters: InterceptorCounters,
+}
+
+/// An interceptor failure bound to the exact Engine lifecycle phase that ran it.
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+#[error("{phase} interceptor failed: {error}")]
+pub struct InterceptorFailure {
+    phase: InterceptorPhase,
+    #[source]
+    error: InterceptorError,
+}
+
+impl InterceptorFailure {
+    pub(crate) fn new(phase: InterceptorPhase, error: InterceptorError) -> Self {
+        Self { phase, error }
+    }
+
+    pub fn phase(&self) -> InterceptorPhase {
+        self.phase
+    }
+
+    pub fn error(&self) -> &InterceptorError {
+        &self.error
+    }
+}
+
+pub type InterceptorResult<T> = Result<T, InterceptorError>;
+
+// =============================================================================
+// Lifecycle Contexts
+// =============================================================================
+
+pub struct PromptSubmitContext<'a, A = ()> {
+    pub invocation: InterceptorInvocation,
+    pub item: &'a mut Item,
+    pub history: &'a [HistoryEntry<A>],
+}
+
+pub struct PendingHistoryAppendsContext<'a, A = ()> {
+    pub invocation: InterceptorInvocation,
+    pub history: &'a [HistoryEntry<A>],
+}
+
+pub struct PreLlmRequestContext<'a, A = ()> {
+    pub invocation: InterceptorInvocation,
+    pub items: &'a mut Vec<Item>,
+    pub history: &'a [HistoryEntry<A>],
+}
+
+pub struct AssistantTurnEndContext<'a, A = ()> {
+    pub invocation: InterceptorInvocation,
+    pub assistant_entries: &'a [HistoryEntry<A>],
+    pub history: &'a [HistoryEntry<A>],
+    pub tool_calls: &'a [ToolCall],
+}
+
+pub struct RunExitContext<'a, A = ()> {
+    pub invocation: InterceptorInvocation,
+    pub exit: &'a EngineRunExit,
+    pub history: &'a [HistoryEntry<A>],
+}
+
+// =============================================================================
+// Action Enums
+// =============================================================================
+
+/// Action after prompt submission.
+#[derive(Debug, Clone, PartialEq)]
+pub enum PromptAction {
+    /// Proceed normally.
+    Continue,
+    /// Cancel with a reason.
+    Cancel(String),
+    /// Proceed, and append these items to history right after the user
+    /// message. Mirrors [`TurnEndAction::ContinueWithMessages`] for the
+    /// submit edge: lets the upper layer attach resolver-produced
+    /// system messages (e.g. `@<path>` file content) so they sit
+    /// adjacent to the user message that referenced them.
+    ContinueWith(Vec<Item>),
+}
+
+/// Action before an LLM request.
+#[derive(Debug, Clone, PartialEq)]
+pub enum PreRequestAction {
+    /// Proceed normally.
+    Continue,
+    /// Proceed after appending these items to durable engine history.
+    ///
+    /// This is for upper-layer budget/status nudges that the model may react
+    /// to: the items are committed before the request so later turns can see
+    /// why the engine changed course.
+    ContinueWith(Vec<Item>),
+    /// Yield after appending these items to durable engine history.
+    ///
+    /// This is for host-mediated pre-request appends that must be visible to
+    /// usage accounting and compaction checks before the current LLM request is
+    /// allowed to proceed.
+    YieldWith(Vec<Item>),
+    /// Cancel with a reason (treated as an error).
+    Cancel(String),
+    /// Yield control to the caller for external processing.
+    ///
+    /// The Engine exits the turn loop cleanly with `EngineResult::Yielded`.
+    /// The caller is expected to resume execution later.
+    Yield,
+}
+
+/// Action before a tool call.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum PreToolAction {
+    /// Proceed with execution.
+    Continue,
+    /// Skip this tool call (do not execute).
+    Skip,
+    /// Do not execute the tool call; commit this synthetic result instead.
+    ///
+    /// This preserves provider-visible `tool_use` / `tool_result` pairing
+    /// without aborting the whole turn.
+    SyntheticResult(ToolResult),
+    /// Abort the entire run.
+    Abort(String),
+    /// Pause execution (can be resumed later).
+    Pause,
+}
+
+/// Action after a tool call.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum PostToolAction {
+    /// Proceed normally.
+    Continue,
+    /// Abort the entire run.
+    Abort(String),
+}
+
+/// Action at the end of a turn (when LLM produces no tool calls).
+#[derive(Debug, Clone)]
+pub enum TurnEndAction {
+    /// Accept the Engine's natural next phase: execute tools, or finish when none exist.
+    Finish,
+    /// Commit additional messages, then continue through the natural next phase.
+    ContinueWithMessages(Vec<Item>),
+    /// Pause execution (can be resumed later).
+    Pause,
+}
+
+// =============================================================================
+// Context Types
+// =============================================================================
+
+/// Context for pre-tool-call decisions.
+pub struct ToolCallInfo<'a, A = ()> {
+    pub invocation: InterceptorInvocation,
+    pub history: &'a [HistoryEntry<A>],
+    pub call: ToolCall,
+    /// Tool meta information.
+    pub meta: ToolMeta,
+    /// Tool instance (for state access).
+    pub tool: Arc<dyn Tool>,
+    /// Response-local execution context for this call.
+    pub context: ToolExecutionContext,
+}
+
+/// Context for post-tool-call decisions.
+pub struct ToolResultInfo<'a, A = ()> {
+    pub invocation: InterceptorInvocation,
+    pub history: &'a [HistoryEntry<A>],
+    pub call: ToolCall,
+    /// Committed terminal tool execution result.
+    pub result: ToolResult,
+    /// Tool meta information.
+    pub meta: ToolMeta,
+    /// Tool instance (for state access).
+    pub tool: Arc<dyn Tool>,
+    /// Response-local execution context for this call.
+    pub context: ToolExecutionContext,
+}
+
+// =============================================================================
+// Interceptor Trait
+// =============================================================================
+
+/// Intercepts the Engine execution loop at key decision points.
+///
+/// Every lifecycle method is asynchronous and returns [`InterceptorResult`],
+/// keeping implementation failure separate from the method's control-flow
+/// action. The Engine reports a failure as a typed run interruption annotated
+/// with the exact [`InterceptorPhase`] that failed.
+///
+/// All methods have default implementations that let the Engine proceed
+/// without intervention. Callers provide richer implementations for approval
+/// flows, permission checks, and other trusted host adaptation.
+#[async_trait]
+pub trait Interceptor<A: Send + Sync = ()>: Send + Sync {
+    /// Called after receiving user input, before adding it to Engine history.
+    async fn on_prompt_submit(
+        &self,
+        _context: PromptSubmitContext<'_, A>,
+    ) -> InterceptorResult<PromptAction> {
+        Ok(PromptAction::Continue)
+    }
+
+    /// Items that should be **committed to `engine.history`** just
+    /// before the next LLM request. Returned items are `extend`ed into
+    /// the persistent history (and therefore picked up by the per-turn
+    /// clone that backs the LLM request, plus the usual
+    /// history-persistence path).
+    ///
+    /// Use this for inputs that arrive from outside the LLM and need
+    /// to be reflected in the on-disk history — notifications,
+    /// external events, system reminders. Do **not** use
+    /// [`Self::pre_llm_request`] for that purpose: it mutates a
+    /// per-request clone, so any committed assistant response that
+    /// reacts to the injection would have no visible trigger on the
+    /// next turn (or after resume / compaction).
+    ///
+    /// `pre_llm_request` remains the right place for purely
+    /// reproducible per-request transformations (pruning, content
+    /// trimming, cache anchors) that depend only on the existing
+    /// history.
+    async fn pending_history_appends(
+        &self,
+        _context: PendingHistoryAppendsContext<'_, A>,
+    ) -> InterceptorResult<Vec<Item>> {
+        Ok(Vec::new())
+    }
+
+    /// Called before each LLM request. The context starts as a clone
+    /// of `engine.history` (after `pending_history_appends` and the
+    /// Engine's own prune projection have been applied).
+    ///
+    /// Direct mutations to `context` remain request-local and are not persisted.
+    /// If an interceptor derives a human/model-visible nudge from the current
+    /// request context, return [`PreRequestAction::ContinueWith`] so the Engine
+    /// commits it to history before the request is sent.
+    async fn pre_llm_request(
+        &self,
+        _context: PreLlmRequestContext<'_, A>,
+    ) -> InterceptorResult<PreRequestAction> {
+        Ok(PreRequestAction::Continue)
+    }
+
+    /// Called before each tool is executed.
+    async fn pre_tool_call(
+        &self,
+        _info: &mut ToolCallInfo<'_, A>,
+    ) -> InterceptorResult<PreToolAction> {
+        Ok(PreToolAction::Continue)
+    }
+
+    /// Called after each tool reaches one terminal result and that result is committed.
+    async fn post_tool_call(
+        &self,
+        _info: &ToolResultInfo<'_, A>,
+    ) -> InterceptorResult<PostToolAction> {
+        Ok(PostToolAction::Continue)
+    }
+
+    /// Called after every terminal assistant response is committed and before
+    /// the Engine decides whether to execute tools, continue, or finish.
+    async fn on_assistant_turn_end(
+        &self,
+        _context: AssistantTurnEndContext<'_, A>,
+    ) -> InterceptorResult<TurnEndAction> {
+        Ok(TurnEndAction::Finish)
+    }
+
+    /// Called once for the terminal outcome of each public run or resume call.
+    async fn on_run_exit(&self, _context: RunExitContext<'_, A>) -> InterceptorResult<()> {
+        Ok(())
+    }
+}
+
+/// Default interceptor: no intervention. Engine proceeds through the loop
+/// without any external control flow decisions.
+pub(crate) struct DefaultInterceptor;
+
+#[async_trait]
+impl<A: Send + Sync> Interceptor<A> for DefaultInterceptor {}

crates/agen/src/lib.rs

@@ -0,0 +1,54 @@
+#![doc = include_str!("../README.md")]
+
+mod engine;
+mod handler;
+mod history;
+mod message;
+
+pub(crate) mod callback;
+pub mod event;
+pub mod interceptor;
+pub mod llm_client;
+pub mod providers;
+pub mod prune;
+pub mod state;
+pub mod timeline;
+pub mod token_counter;
+pub mod tool;
+pub mod tool_server;
+pub mod usage_record;
+
+pub use agen_macros::{description, tool, tool_registry};
+pub use callback::{TextBlockScope, ThinkingBlockScope, ToolUseBlockScope};
+pub use engine::{
+    Engine, EngineConfig, EngineError, EngineResult, EngineRunExit, EngineRunOutput,
+    LlmRetryNotice, RunInterruptionReason, ToolRegistryError,
+};
+pub use handler::ToolUseBlockStart;
+pub use history::{History, HistoryEntry};
+pub use interceptor::{
+    AssistantTurnEndContext, Interceptor, InterceptorCallId, InterceptorCounter,
+    InterceptorCounters, InterceptorError, InterceptorErrorCategory, InterceptorFailure,
+    InterceptorInvocation, InterceptorPhase, InterceptorResult, InterceptorRunId,
+    InterceptorTurnId, MAX_INTERCEPTOR_DIAGNOSTIC_BYTES, PendingHistoryAppendsContext,
+    PreLlmRequestContext, PromptSubmitContext, RunExitContext,
+};
+pub use message::{ContentPart, Item, Message, Role};
+pub use tool::{
+    ToolCall, ToolExecutionContext, ToolExecutionHandle, ToolExecutionPolicy,
+    ToolExecutionTerminal, ToolExecutionTerminalFuture, ToolOutputLimits, ToolResult,
+    ToolResultDisposition,
+};
+pub use usage_record::UsageRecord;
+
+/// Implementation dependencies used by code generated from `agen` macros.
+///
+/// This module is not a stable user-facing API. It is public only because macro expansion
+/// happens in the downstream crate.
+#[doc(hidden)]
+pub mod __private {
+    pub use async_trait;
+    pub use schemars;
+    pub use serde;
+    pub use serde_json;
+}

crates/agen/src/llm_client/auth.rs

@@ -30,7 +30,7 @@ pub enum AuthRequirement {
 /// リクエスト毎に認証ヘッダを動的に組み立てるプロバイダ。
 ///
 /// access token が refresh で更新されたり、複数ヘッダを同時に注入する
-/// 必要があるケースで使う。実体は呼び出し側に置き、llm-engine は
+/// 必要があるケースで使う。実体は呼び出し側に置き、agen は
 /// trait を知るだけ。
 ///
 /// 返したヘッダはそのまま `HeaderMap` に挿入される。`Authorization`

crates/agen/src/llm_client/error.rs

@@ -18,6 +18,9 @@ pub enum ClientError {
         message: String,
         retry_after: Option<Duration>,
     },
+    /// The provider rejected the request because it exceeded the model context window.
+    /// Classified only from a structured provider error code, never message text.
+    ContextWindowExceeded,
     /// A request lifecycle phase exceeded its hard timeout.
     Timeout {
         phase: &'static str,
@@ -48,6 +51,7 @@ impl fmt::Display for ClientError {
                 }
                 write!(f, ": {}", message)
             }
+            ClientError::ContextWindowExceeded => write!(f, "Model context window reached"),
             ClientError::Timeout { phase, timeout } => {
                 write!(f, "{phase} timed out after {}s", timeout.as_secs())
             }
@@ -112,7 +116,10 @@ pub fn is_retryable(error: &ClientError) -> bool {
         ClientError::Api { status: None, .. } => false,
         ClientError::Timeout { .. } => true,
         ClientError::Http(e) => e.is_connect() || e.is_timeout(),
-        ClientError::Json(_) | ClientError::Sse(_) | ClientError::Config(_) => false,
+        ClientError::ContextWindowExceeded
+        | ClientError::Json(_)
+        | ClientError::Sse(_)
+        | ClientError::Config(_) => false,
     }
 }
 

crates/agen/src/llm_client/retry.rs

@@ -8,7 +8,7 @@ use std::time::Duration;
 
 /// 指数バックオフ + ジッター + 累積タイムアウトを表すポリシー。
 ///
-/// `Default` は llm-engine 全体の固定値を返す。呼び出し側からの上書きが
+/// `Default` は agen 全体の固定値を返す。呼び出し側からの上書きが
 /// 必要になったら拡張する。
 #[derive(Debug, Clone)]
 pub struct RetryPolicy {

crates/agen/src/llm_client/scheme/openai_chat/request.rs

@@ -5,10 +5,13 @@
 use serde::Serialize;
 use serde_json::Value;
 
-use crate::llm_client::{
-    Request,
-    capability::{ModelCapability, ReasoningControl, ReasoningSupport},
-    types::{Item, Role, ToolDefinition, parse_tool_arguments},
+use crate::{
+    llm_client::{
+        Request,
+        capability::{ModelCapability, ReasoningControl, ReasoningSupport},
+        types::{ContentPart, Item, Role, ToolDefinition, image_data_url, parse_tool_arguments},
+    },
+    tool::Attachment,
 };
 
 use super::OpenAIScheme;
@@ -134,7 +137,7 @@ impl OpenAIScheme {
         }
 
         // Convert items to messages
-        messages.extend(self.convert_items_to_messages(&request.items));
+        messages.extend(self.convert_items_to_messages(&request.items, capability.vision));
 
         let tools = request.tools.iter().map(|t| self.convert_tool(t)).collect();
 
@@ -185,12 +188,38 @@ impl OpenAIScheme {
     /// - Assistant messages have role "assistant"
     /// - Tool calls are within assistant messages as tool_calls array
     /// - Tool results have role "tool" with tool_call_id
-    fn convert_items_to_messages(&self, items: &[Item]) -> Vec<OpenAIMessage> {
+    fn flush_pending_tool_result_images(
+        messages: &mut Vec<OpenAIMessage>,
+        pending_images: &mut Vec<OpenAIContentPart>,
+    ) {
+        if !pending_images.is_empty() {
+            messages.push(OpenAIMessage {
+                role: "user".to_string(),
+                content: Some(OpenAIContent::Parts(std::mem::take(pending_images))),
+                tool_calls: vec![],
+                tool_call_id: None,
+                name: None,
+            });
+        }
+    }
+
+    fn convert_items_to_messages(
+        &self,
+        items: &[Item],
+        supports_images: bool,
+    ) -> Vec<OpenAIMessage> {
         let mut messages = Vec::new();
         let mut pending_tool_calls: Vec<OpenAIToolCall> = Vec::new();
         let mut pending_assistant_text: Option<String> = None;
+        let mut pending_tool_result_images: Vec<OpenAIContentPart> = Vec::new();
 
         for item in items {
+            if !matches!(item, Item::ToolResult { .. }) {
+                Self::flush_pending_tool_result_images(
+                    &mut messages,
+                    &mut pending_tool_result_images,
+                );
+            }
             match item {
                 Item::Message { role, content, .. } => {
                     // Flush pending tool calls
@@ -205,16 +234,17 @@ impl OpenAIScheme {
                         Role::Assistant => "assistant",
                         Role::System => "system",
                     };
-
-                    let text_content: String = content
-                        .iter()
-                        .map(|p| p.as_text())
-                        .collect::<Vec<_>>()
-                        .join("");
+                    let message_content = OpenAIContent::Text(
+                        content
+                            .iter()
+                            .map(ContentPart::as_text)
+                            .collect::<Vec<_>>()
+                            .join(""),
+                    );
 
                     messages.push(OpenAIMessage {
                         role: openai_role.to_string(),
-                        content: Some(OpenAIContent::Text(text_content)),
+                        content: Some(message_content),
                         tool_calls: vec![],
                         tool_call_id: None,
                         name: None,
@@ -244,19 +274,35 @@ impl OpenAIScheme {
                     call_id,
                     summary,
                     content,
+                    attachments,
                     ..
                 } => {
-                    // Flush pending tool calls before tool result
+                    // OpenAI requires every parallel tool result before a new user message.
                     self.flush_pending_assistant(
                         &mut messages,
                         &mut pending_tool_calls,
                         &mut pending_assistant_text,
                     );
 
-                    let text = match content {
+                    let mut text = match content {
                         Some(c) => format!("{summary}\n{c}"),
                         None => summary.clone(),
                     };
+                    if supports_images {
+                        pending_tool_result_images.extend(attachments.iter().map(|attachment| {
+                            let Attachment::Image(image) = attachment;
+                            OpenAIContentPart::ImageUrl {
+                                image_url: ImageUrl {
+                                    url: image_data_url(image.mime_type(), image.data()),
+                                },
+                            }
+                        }));
+                    } else if !attachments.is_empty() {
+                        text.push_str(&format!(
+                            "\n[{} image attachment(s) omitted: model does not support images]",
+                            attachments.len()
+                        ));
+                    }
                     messages.push(OpenAIMessage {
                         role: "tool".to_string(),
                         content: Some(OpenAIContent::Text(text)),
@@ -284,6 +330,7 @@ impl OpenAIScheme {
             &mut pending_tool_calls,
             &mut pending_assistant_text,
         );
+        Self::flush_pending_tool_result_images(&mut messages, &mut pending_tool_result_images);
 
         messages
     }
@@ -334,6 +381,13 @@ mod tests {
         }
     }
 
+    fn vision_cap() -> ModelCapability {
+        ModelCapability {
+            vision: true,
+            ..cap()
+        }
+    }
+
     #[test]
     fn test_build_simple_request() {
         let scheme = OpenAIScheme::new();
@@ -439,4 +493,94 @@ mod tests {
         assert_eq!(body.messages[1].tool_calls.len(), 1);
         assert_eq!(body.messages[2].role, "tool");
     }
+
+    #[test]
+    fn parallel_tool_results_precede_durable_image_projection() {
+        let scheme = OpenAIScheme::new();
+        let image = std::sync::Arc::<[u8]>::from(&b"\x89PNG\r\n\x1a\nbody"[..]);
+        let request = Request::new()
+            .item(Item::tool_call("call_image", "ViewImage", "{}"))
+            .item(Item::tool_call("call_text", "Read", "{}"))
+            .item(Item::tool_result_item_with_attachments(
+                "call_image",
+                "Attached image",
+                None,
+                false,
+                vec![crate::tool::Attachment::Image(
+                    crate::tool::ImageAttachment::new("image/png", image),
+                )],
+            ))
+            .item(Item::tool_result_item(
+                "call_text",
+                "Read text",
+                None,
+                false,
+            ));
+        let json = serde_json::to_value(
+            &scheme
+                .build_request("gpt-4o", &request, &vision_cap())
+                .messages,
+        )
+        .unwrap();
+
+        assert_eq!(json[0]["role"], "assistant");
+        assert_eq!(json[1]["role"], "tool");
+        assert_eq!(json[2]["role"], "tool");
+        assert_eq!(json[3]["role"], "user");
+        assert_eq!(json[3]["content"][0]["type"], "image_url");
+    }
+
+    #[test]
+    fn durable_tool_image_is_deterministically_lowered_to_following_user_content() {
+        let scheme = OpenAIScheme::new();
+        let image = std::sync::Arc::<[u8]>::from(&b"\x89PNG\r\n\x1a\nbody"[..]);
+        let attachment = crate::tool::Attachment::Image(crate::tool::ImageAttachment::new(
+            "image/png",
+            image.clone(),
+        ));
+        let item = Item::tool_result_item_with_attachments(
+            "call_image",
+            "Attached image",
+            None,
+            false,
+            vec![attachment],
+        );
+        let persisted = serde_json::to_string(&item).unwrap();
+        assert!(persisted.contains("attachments"));
+        let restored: Item = serde_json::from_str(&persisted).unwrap();
+
+        let request = Request::new()
+            .item(Item::tool_call(
+                "call_image",
+                "ViewImage",
+                r#"{"path":"a.png"}"#,
+            ))
+            .item(restored);
+        let body = scheme.build_request("gpt-4o", &request, &vision_cap());
+        let json = serde_json::to_value(&body.messages).unwrap();
+        let rebuilt = serde_json::to_value(
+            &scheme
+                .build_request("gpt-4o", &request, &vision_cap())
+                .messages,
+        )
+        .unwrap();
+        assert_eq!(rebuilt, json);
+
+        assert_eq!(json[0]["role"], "assistant");
+        assert_eq!(json[1]["role"], "tool");
+        assert_eq!(json[2]["role"], "user");
+        assert_eq!(json[2]["content"][0]["type"], "image_url");
+        assert!(
+            json[2]["content"][0]["image_url"]["url"]
+                .as_str()
+                .unwrap()
+                .starts_with("data:image/png;base64,")
+        );
+
+        let mut no_vision = cap();
+        no_vision.vision = false;
+        let disabled =
+            serde_json::to_string(&scheme.build_request("gpt-4o", &request, &no_vision)).unwrap();
+        assert!(!disabled.contains("data:image"));
+    }
 }

crates/agen/src/llm_client/scheme/openai_responses/mod.rs

@@ -4,8 +4,8 @@
 //! function_call item が first-class で、SSE イベントも `response.*` 名前空間で
 //! 流れる。
 //!
-//! - リクエスト JSON 生成: [`request`]
-//! - SSE イベントパース → [`Event`](crate::llm_client::event::Event) 変換: [`events`]
+//! - リクエスト JSON 生成: `request`
+//! - SSE イベントパース → [`Event`](crate::llm_client::event::Event) 変換: `events`
 
 mod capability;
 mod events;

crates/agen/src/llm_client/scheme/openai_responses/request.rs

@@ -7,14 +7,31 @@
 use serde::{Serialize, Serializer};
 use serde_json::Value;
 
-use crate::llm_client::{
-    Request,
-    capability::{ModelCapability, ReasoningControl, ReasoningSupport},
-    types::{ContentPart, Item, Role, ToolDefinition, parse_tool_arguments},
+use crate::{
+    llm_client::{
+        Request,
+        capability::{ModelCapability, ReasoningControl, ReasoningSupport},
+        types::{ContentPart, Item, Role, ToolDefinition, image_data_url, parse_tool_arguments},
+    },
+    tool::Attachment,
 };
 
 use super::OpenAIResponsesScheme;
 
+#[derive(Debug, Serialize)]
+#[serde(untagged)]
+pub(crate) enum FunctionCallOutputBody {
+    Text(String),
+    ContentItems(Vec<FunctionCallOutputContentItem>),
+}
+
+#[derive(Debug, Serialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub(crate) enum FunctionCallOutputContentItem {
+    InputText { text: String },
+    InputImage { image_url: String },
+}
+
 /// `/v1/responses` のリクエスト body。
 #[derive(Debug, Serialize)]
 pub(crate) struct ResponsesRequest {
@@ -91,9 +108,7 @@ pub(crate) enum InputItem {
     /// function tool の結果（user 側）。
     FunctionCallOutput {
         call_id: String,
-        /// Responses は文字列 or 構造化 output を許すが、ここでは
-        /// `summary` + `content` を改行連結した文字列で送る。
-        output: String,
+        output: FunctionCallOutputBody,
     },
     /// reasoning item。`encrypted_content` があれば必ず添える。
     Reasoning {
@@ -118,6 +133,7 @@ pub(crate) enum InputItem {
 pub(crate) enum InputContent {
     /// user / developer 側のテキスト
     InputText { text: String },
+    /// user 側の画像
     /// assistant 側のテキスト
     OutputText { text: String },
 }
@@ -173,7 +189,7 @@ impl OpenAIResponsesScheme {
         request: &Request,
         capability: &ModelCapability,
     ) -> ResponsesRequest {
-        let input = convert_items_to_input(&request.items);
+        let input = convert_items_to_input(&request.items, capability.vision);
         let tools = request.tools.iter().map(convert_tool).collect();
 
         // Reasoning 投影: capability が Effort / Both をサポートし、かつ
@@ -234,7 +250,7 @@ impl OpenAIResponsesScheme {
 }
 
 /// `Item` 列を `input[]` に変換する。
-fn convert_items_to_input(items: &[Item]) -> Vec<InputItem> {
+fn convert_items_to_input(items: &[Item], supports_images: bool) -> Vec<InputItem> {
     let mut out = Vec::with_capacity(items.len());
     for item in items {
         match item {
@@ -247,7 +263,7 @@ fn convert_items_to_input(items: &[Item]) -> Vec<InputItem> {
                     };
                 let parts: Vec<InputContent> = content
                     .iter()
-                    .map(|p| match p {
+                    .map(|part| match part {
                         ContentPart::Text { text } => text_variant(text.clone()),
                         ContentPart::Refusal { refusal } => text_variant(refusal.clone()),
                     })
@@ -275,15 +291,33 @@ fn convert_items_to_input(items: &[Item]) -> Vec<InputItem> {
                 call_id,
                 summary,
                 content,
+                attachments,
                 ..
             } => {
                 let text = match content {
                     Some(c) => format!("{summary}\n{c}"),
                     None => summary.clone(),
                 };
+                let output = if attachments.is_empty() {
+                    FunctionCallOutputBody::Text(text)
+                } else if supports_images {
+                    let mut parts = vec![FunctionCallOutputContentItem::InputText { text }];
+                    parts.extend(attachments.iter().map(|attachment| {
+                        let Attachment::Image(image) = attachment;
+                        FunctionCallOutputContentItem::InputImage {
+                            image_url: image_data_url(image.mime_type(), image.data()),
+                        }
+                    }));
+                    FunctionCallOutputBody::ContentItems(parts)
+                } else {
+                    FunctionCallOutputBody::Text(format!(
+                        "{text}\n[{} image attachment(s) omitted: model does not support images]",
+                        attachments.len()
+                    ))
+                };
                 out.push(InputItem::FunctionCallOutput {
                     call_id: call_id.clone(),
-                    output: text,
+                    output,
                 });
             }
             Item::Reasoning {
@@ -690,4 +724,51 @@ mod tests {
         assert_eq!(json["tools"][0]["type"], "function");
         assert_eq!(json["tools"][0]["name"], "t");
     }
+
+    #[test]
+    fn durable_tool_image_uses_function_call_output_content_items() {
+        let scheme = OpenAIResponsesScheme::new();
+        let image = std::sync::Arc::<[u8]>::from(&b"\x89PNG\r\n\x1a\nbody"[..]);
+        let item = Item::tool_result_item_with_attachments(
+            "call_image",
+            "Attached image",
+            None,
+            false,
+            vec![crate::tool::Attachment::Image(
+                crate::tool::ImageAttachment::new("image/png", image),
+            )],
+        );
+        let persisted = serde_json::to_string(&item).unwrap();
+        let restored: Item = serde_json::from_str(&persisted).unwrap();
+        let req = Request::new()
+            .item(Item::tool_call(
+                "call_image",
+                "ViewImage",
+                r#"{"path":"a.png"}"#,
+            ))
+            .item(restored);
+        let body = scheme.build_request("gpt-5", &req, &cap_with_reasoning());
+        let json = serde_json::to_value(&body).unwrap();
+
+        assert_eq!(json["input"][1]["type"], "function_call_output");
+        assert_eq!(json["input"].as_array().unwrap().len(), 2);
+        assert_eq!(json["input"][1]["output"][0]["type"], "input_text");
+        assert_eq!(json["input"][1]["output"][1]["type"], "input_image");
+        assert!(
+            json["input"][1]["output"][1]["image_url"]
+                .as_str()
+                .unwrap()
+                .starts_with("data:image/png;base64,")
+        );
+        let rebuilt =
+            serde_json::to_value(scheme.build_request("gpt-5", &req, &cap_with_reasoning()))
+                .unwrap();
+        assert_eq!(rebuilt["input"], json["input"]);
+
+        let mut no_vision = cap_with_reasoning();
+        no_vision.vision = false;
+        let disabled =
+            serde_json::to_string(&scheme.build_request("gpt-5", &req, &no_vision)).unwrap();
+        assert!(!disabled.contains("data:image"));
+    }
 }

crates/agen/src/llm_client/transport.rs

@@ -431,13 +431,7 @@ fn api_error_code(error: &ClientError) -> Option<&str> {
 }
 
 fn is_context_length_exceeded(error: &ClientError) -> bool {
-    match error {
-        ClientError::Api { code, message, .. } => {
-            code.as_deref() == Some("context_length_exceeded")
-                || message.contains("context_length_exceeded")
-        }
-        _ => false,
-    }
+    matches!(error, ClientError::ContextWindowExceeded)
 }
 
 async fn response_with_timeout(
@@ -487,6 +481,9 @@ async fn classify_error_response(resp: reqwest::Response) -> ClientError {
             .and_then(|v| v.as_str())
             .unwrap_or(&text)
             .to_string();
+        if code.as_deref() == Some("context_length_exceeded") {
+            return ClientError::ContextWindowExceeded;
+        }
         ClientError::Api {
             status: Some(status),
             code,

crates/agen/src/llm_client/types.rs

@@ -9,12 +9,19 @@
 
 use std::{fmt, sync::Arc};
 
+use crate::tool::{Attachment, ToolResultDisposition};
+use base64::Engine as _;
 use serde::{Deserialize, Serialize};
 
 fn is_false(value: &bool) -> bool {
     !*value
 }
 
+pub(crate) fn image_data_url(media_type: &str, data: &[u8]) -> String {
+    let encoded = base64::engine::general_purpose::STANDARD.encode(data);
+    format!("data:{media_type};base64,{encoded}")
+}
+
 // ============================================================================
 // Item - The core unit of conversation
 // ============================================================================
@@ -62,7 +69,7 @@ impl fmt::Debug for RequestTrace {
 /// # Examples
 ///
 /// ```ignore
-/// use llm_engine::Item;
+/// use agen::Item;
 ///
 /// let user = Item::user_message("Hello!");
 /// let assistant = Item::assistant_message("Hi there!");
@@ -114,9 +121,15 @@ pub enum Item {
         /// Detailed output (removed by pruning when old enough)
         #[serde(default, skip_serializing_if = "Option::is_none")]
         content: Option<String>,
+        /// Typed terminal state used for replay and recovery.
+        #[serde(default, skip_serializing_if = "ToolResultDisposition::is_success")]
+        disposition: ToolResultDisposition,
         /// Whether the tool result represents an execution error.
         #[serde(default, skip_serializing_if = "is_false")]
         is_error: bool,
+        /// Durable binary details (removed with `content` by normal pruning).
+        #[serde(default, skip_serializing_if = "Vec::is_empty")]
+        attachments: Vec<Attachment>,
     },
 
     /// Reasoning/thinking item
@@ -251,12 +264,56 @@ impl Item {
         content: Option<String>,
         is_error: bool,
     ) -> Self {
+        Self::tool_result_item_with_disposition_and_attachments(
+            call_id,
+            summary,
+            content,
+            if is_error {
+                ToolResultDisposition::Error
+            } else {
+                ToolResultDisposition::Success
+            },
+            Vec::new(),
+        )
+    }
+
+    /// Create a tool result item with durable, prunable structured attachments.
+    pub fn tool_result_item_with_attachments(
+        call_id: impl Into<String>,
+        summary: impl Into<String>,
+        content: Option<String>,
+        is_error: bool,
+        attachments: Vec<Attachment>,
+    ) -> Self {
+        Self::tool_result_item_with_disposition_and_attachments(
+            call_id,
+            summary,
+            content,
+            if is_error {
+                ToolResultDisposition::Error
+            } else {
+                ToolResultDisposition::Success
+            },
+            attachments,
+        )
+    }
+
+    pub fn tool_result_item_with_disposition_and_attachments(
+        call_id: impl Into<String>,
+        summary: impl Into<String>,
+        content: Option<String>,
+        disposition: ToolResultDisposition,
+        attachments: Vec<Attachment>,
+    ) -> Self {
+        let is_error = !disposition.is_success();
         Self::ToolResult {
             id: None,
             call_id: call_id.into(),
             summary: summary.into(),
             content,
+            disposition,
             is_error,
+            attachments,
         }
     }
 
@@ -461,7 +518,7 @@ impl ContentPart {
         }
     }
 
-    /// Get the text content regardless of type
+    /// Get a textual projection of the content part.
     pub fn as_text(&self) -> &str {
         match self {
             Self::Text { text } => text,

crates/agen/src/prune.rs

@@ -110,25 +110,30 @@ impl Default for PruneConfig {
     }
 }
 
-/// Set `content = None` on each `Item::ToolResult` at the given indices.
+/// Remove detailed text and attachments from each `Item::ToolResult` at the given indices.
 ///
-/// Returns the number of items that were actually modified — items that
-/// are already content-less are counted as 0. Intended for use on a
-/// request-context clone (never on a persistent history).
+/// The mandatory summary remains. Returns the number of items that were actually
+/// modified — results that already contain no detail are counted as 0. Intended
+/// for use on a request-context clone (never on a persistent history).
 pub fn project(items: &mut [Item], indices: &[usize]) -> usize {
     let mut count = 0;
     for &i in indices {
-        if let Item::ToolResult { content, .. } = &mut items[i]
-            && content.is_some()
+        if let Item::ToolResult {
+            content,
+            attachments,
+            ..
+        } = &mut items[i]
+            && (content.is_some() || !attachments.is_empty())
         {
             *content = None;
+            attachments.clear();
             count += 1;
         }
     }
     count
 }
 
-/// Indices of `Item::ToolResult { content: Some(_), .. }` that lie before
+/// Indices of detailed `Item::ToolResult` values that lie before
 /// the suffix protected by `protected_tokens`. Pure: does not mutate `items`.
 ///
 /// Returns an empty vector when token estimates are unavailable (`NoData`) or
@@ -159,8 +164,10 @@ pub fn evaluate_candidates(
         .enumerate()
         .filter_map(|(i, item)| match item {
             Item::ToolResult {
-                content: Some(_), ..
-            } => Some(i),
+                content,
+                attachments,
+                ..
+            } if content.is_some() || !attachments.is_empty() => Some(i),
             _ => None,
         })
         .collect();
@@ -373,6 +380,38 @@ mod tests {
         }
     }
 
+    #[test]
+    fn project_drops_image_detail_but_keeps_summary_and_persistent_source() {
+        let original = vec![Item::tool_result_item_with_attachments(
+            "call_image",
+            "Attached image/png image (12 bytes)",
+            None,
+            false,
+            vec![crate::tool::Attachment::Image(
+                crate::tool::ImageAttachment::new("image/png", b"image-body".to_vec()),
+            )],
+        )];
+        let mut request_context = original.clone();
+
+        let estimates = uniform_estimates(&original, 100);
+        assert_eq!(prunable_indices(&original, 0, &estimates), vec![0]);
+
+        assert_eq!(project(&mut request_context, &[0]), 1);
+        assert!(matches!(
+            &request_context[0],
+            Item::ToolResult {
+                summary,
+                content: None,
+                attachments,
+                ..
+            } if summary == "Attached image/png image (12 bytes)" && attachments.is_empty()
+        ));
+        assert!(matches!(
+            &original[0],
+            Item::ToolResult { attachments, .. } if attachments.len() == 1
+        ));
+    }
+
     #[test]
     fn project_skips_already_pruned_items() {
         // indices points at an item whose content is already None.

crates/agen/src/state.rs

@@ -19,12 +19,12 @@ mod private {
 /// - Editing message history (add, delete, clear)
 /// - Registering tools and hooks
 ///
-/// Can transition to [`Locked`] state via `Engine::lock()`.
+/// Can transition to [`Locked`] state via `Engine::lock(&history)`.
 ///
 /// # Examples
 ///
 /// ```ignore
-/// use llm_engine::Engine;
+/// use agen::Engine;
 ///
 /// let mut engine = Engine::new(client)
 ///     .system_prompt("You are helpful.");

crates/agen/src/timeline/timeline.rs

@@ -348,7 +348,7 @@ where
 /// # Examples
 ///
 /// ```ignore
-/// use llm_engine::{Timeline, Handler, TextBlockKind, TextBlockEvent};
+/// use agen::{Timeline, Handler, TextBlockKind, TextBlockEvent};
 ///
 /// struct MyHandler;
 /// impl Handler<TextBlockKind> for MyHandler {

crates/agen/src/tool.rs

@@ -3,11 +3,18 @@
 //! Traits for defining tools callable by LLM.
 //! Usually auto-implemented using the `#[tool]` macro.
 
-use std::collections::HashMap;
-use std::sync::Arc;
+use std::{
+    collections::HashMap,
+    fmt,
+    future::Future,
+    pin::Pin,
+    sync::Arc,
+    task::{Context, Poll},
+};
 
 use async_trait::async_trait;
-use serde::{Deserialize, Serialize};
+use base64::{Engine as _, engine::general_purpose::STANDARD};
+use serde::{Deserialize, Deserializer, Serialize, Serializer, de::Error as _};
 use serde_json::Value;
 use thiserror::Error;
 
@@ -23,6 +30,12 @@ pub enum ToolError {
     /// Internal error
     #[error("Internal error: {0}")]
     Internal(String),
+    /// Cooperative cancellation completed with bounded terminal output.
+    #[error("Tool execution cancelled")]
+    Cancelled(ToolOutput),
+    /// Execution was interrupted with a confirmed bounded terminal output.
+    #[error("Tool execution interrupted")]
+    Interrupted(ToolOutput),
 }
 
 // =============================================================================
@@ -89,19 +102,112 @@ pub(crate) fn truncate_content(content: &mut String, limit: usize) {
     content.push_str(&suffix_template.replace("%BYTES%", &dropped.to_string()));
 }
 
+#[derive(Clone, PartialEq, Eq)]
+pub struct ImageAttachment {
+    mime_type: String,
+    data: Arc<[u8]>,
+}
+
+impl ImageAttachment {
+    pub fn new(mime_type: impl Into<String>, data: impl Into<Arc<[u8]>>) -> Self {
+        Self {
+            mime_type: mime_type.into(),
+            data: data.into(),
+        }
+    }
+
+    pub fn mime_type(&self) -> &str {
+        &self.mime_type
+    }
+
+    pub fn data(&self) -> &[u8] {
+        &self.data
+    }
+}
+
+impl fmt::Debug for ImageAttachment {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("ImageAttachment")
+            .field("mime_type", &self.mime_type)
+            .field("bytes", &self.data.len())
+            .finish()
+    }
+}
+
+#[derive(Serialize, Deserialize)]
+struct ImageAttachmentWire {
+    mime_type: String,
+    data: String,
+}
+
+impl Serialize for ImageAttachment {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+    {
+        ImageAttachmentWire {
+            mime_type: self.mime_type.clone(),
+            data: STANDARD.encode(self.data.as_ref()),
+        }
+        .serialize(serializer)
+    }
+}
+
+impl<'de> Deserialize<'de> for ImageAttachment {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        let wire = ImageAttachmentWire::deserialize(deserializer)?;
+        let data = STANDARD.decode(wire.data).map_err(D::Error::custom)?;
+        Ok(Self::new(wire.mime_type, data))
+    }
+}
+
+/// Durable binary detail emitted by a tool and handled by normal ToolResult pruning.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "type", content = "payload", rename_all = "snake_case")]
+pub enum Attachment {
+    Image(ImageAttachment),
+}
+
+/// Terminal disposition of one started tool call.
+///
+/// `Cancelled` means the tool confirmed cancellation. `OutcomeUnknown` means
+/// execution stopped without confirmation, so neither completion nor side
+/// effects may be inferred.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[serde(rename_all = "snake_case")]
+pub enum ToolResultDisposition {
+    #[default]
+    Success,
+    Error,
+    Interrupted,
+    Cancelled,
+    OutcomeUnknown,
+}
+
+impl ToolResultDisposition {
+    pub const fn is_success(&self) -> bool {
+        matches!(self, Self::Success)
+    }
+}
+
 /// Tool execution result.
 ///
 /// Every output has a mandatory `summary` (1-2 lines) that persists in
-/// conversation history even after pruning. The optional `content` carries
-/// full details and is removed by the Prune mechanism when the context
-/// grows too large.
+/// conversation history even after pruning. Optional text and binary details are
+/// committed to history and may later be omitted only by normal ToolResult pruning.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ToolOutput {
     /// Short summary (1-2 lines). Always remains in history.
     pub summary: String,
-    /// Detailed output. Removed by Prune when old enough.
+    /// Detailed text output. Removed by Prune when old enough.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub content: Option<String>,
+    /// Durable binary details handled by the same pruning lifecycle as `content`.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub attachments: Vec<Attachment>,
 }
 
 impl From<String> for ToolOutput {
@@ -110,6 +216,7 @@ impl From<String> for ToolOutput {
             ToolOutput {
                 summary: s,
                 content: None,
+                attachments: Vec::new(),
             }
         } else {
             let lines = s.lines().count();
@@ -118,6 +225,7 @@ impl From<String> for ToolOutput {
             ToolOutput {
                 summary,
                 content: Some(s),
+                attachments: Vec::new(),
             }
         }
     }
@@ -249,6 +357,12 @@ impl ToolExecutionContext {
         }
     }
 
+    /// Identifies one live execution attempt without making the batch id a durable
+    /// replay or idempotency authority.
+    pub fn execution_id(&self) -> String {
+        format!("{}:{}", self.batch_id, self.call_id)
+    }
+
     /// Context for direct, non-engine calls in unit tests and low-level callers.
     pub fn direct() -> Self {
         Self::new("direct", "direct", 0)
@@ -261,6 +375,142 @@ impl Default for ToolExecutionContext {
     }
 }
 
+/// The provider-confirmed terminal result of one started tool execution.
+///
+/// `OutcomeUnknown` is reserved for an execution task that had to be force-closed
+/// or failed before the provider could confirm its terminal result.
+#[derive(Debug)]
+pub enum ToolExecutionTerminal {
+    Confirmed(Result<ToolOutput, ToolError>),
+    OutcomeUnknown,
+}
+
+/// The completion future paired with a [`ToolExecutionHandle`]. Dropping this
+/// future does not drop the provider execution: the spawned execution remains
+/// owned by its handle until it completes or is explicitly force-closed.
+pub struct ToolExecutionTerminalFuture {
+    task: tokio::task::JoinHandle<Result<ToolOutput, ToolError>>,
+}
+
+impl Future for ToolExecutionTerminalFuture {
+    type Output = ToolExecutionTerminal;
+
+    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
+        match Pin::new(&mut self.task).poll(cx) {
+            Poll::Ready(Ok(result)) => Poll::Ready(ToolExecutionTerminal::Confirmed(result)),
+            Poll::Ready(Err(_)) => Poll::Ready(ToolExecutionTerminal::OutcomeUnknown),
+            Poll::Pending => Poll::Pending,
+        }
+    }
+}
+
+/// Live ownership and control for one started tool execution.
+///
+/// Execution, cancellation, and terminal confirmation remain provider-owned:
+/// this handle starts `Tool::execute`, delegates cooperative cancellation to
+/// `Tool::cancel_execution`, and treats execution-future completion as the
+/// provider's terminal confirmation. Agen may force-close only after its caller's
+/// deadline expires, at which point the outcome is necessarily unknown.
+#[derive(Clone)]
+pub struct ToolExecutionHandle {
+    inner: Arc<ToolExecutionHandleInner>,
+}
+
+struct ToolExecutionHandleInner {
+    tool: Arc<dyn Tool>,
+    context: ToolExecutionContext,
+    abort: tokio::task::AbortHandle,
+}
+
+impl Drop for ToolExecutionHandleInner {
+    fn drop(&mut self) {
+        // Losing the final live owner is an explicit forced close, never a
+        // best-effort detached provider future.
+        self.abort.abort();
+    }
+}
+
+impl fmt::Debug for ToolExecutionHandle {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("ToolExecutionHandle")
+            .field("call_id", &self.inner.context.call_id)
+            .field("batch_id", &self.inner.context.batch_id)
+            .finish_non_exhaustive()
+    }
+}
+
+impl ToolExecutionHandle {
+    pub fn start(
+        tool: Arc<dyn Tool>,
+        input_json: String,
+        context: ToolExecutionContext,
+    ) -> (Self, ToolExecutionTerminalFuture) {
+        let execution_tool = Arc::clone(&tool);
+        let execution_context = context.clone();
+        let task =
+            tokio::spawn(
+                async move { execution_tool.execute(&input_json, execution_context).await },
+            );
+        let abort = task.abort_handle();
+        (
+            Self {
+                inner: Arc::new(ToolExecutionHandleInner {
+                    tool,
+                    context,
+                    abort,
+                }),
+            },
+            ToolExecutionTerminalFuture { task },
+        )
+    }
+
+    pub fn context(&self) -> &ToolExecutionContext {
+        &self.inner.context
+    }
+
+    pub async fn cancel_before(&self, deadline: tokio::time::Instant) -> Result<(), ToolError> {
+        match tokio::time::timeout_at(
+            deadline,
+            self.inner.tool.cancel_execution(&self.inner.context),
+        )
+        .await
+        {
+            Ok(result) => result,
+            Err(_) => Err(ToolError::Internal(format!(
+                "tool cancellation request exceeded its deadline for call {}",
+                self.inner.context.call_id
+            ))),
+        }
+    }
+
+    pub fn force_close(&self) {
+        self.inner.abort.abort();
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ToolExecutionPolicy {
+    /// Time a pause waits for already-started providers to reach a natural safe
+    /// boundary before escalating to explicit cooperative cancellation.
+    pub pause_safe_boundary_timeout: std::time::Duration,
+    /// Maximum time allowed for a provider to accept one cooperative
+    /// cancellation request.
+    pub cancellation_request_timeout: std::time::Duration,
+    /// Maximum time allowed for all providers to confirm terminal results after
+    /// cancellation has been requested.
+    pub terminal_confirmation_timeout: std::time::Duration,
+}
+
+impl Default for ToolExecutionPolicy {
+    fn default() -> Self {
+        Self {
+            pause_safe_boundary_timeout: std::time::Duration::from_millis(100),
+            cancellation_request_timeout: std::time::Duration::from_millis(100),
+            terminal_confirmation_timeout: std::time::Duration::from_millis(500),
+        }
+    }
+}
+
 // =============================================================================
 // Tool trait
 // =============================================================================
@@ -291,7 +541,7 @@ impl Default for ToolExecutionContext {
 /// # Manual Implementation
 ///
 /// ```ignore
-/// use llm_engine::tool::{Tool, ToolError, ToolExecutionContext, ToolMeta, ToolDefinition, ToolOutput};
+/// use agen::tool::{Tool, ToolError, ToolExecutionContext, ToolMeta, ToolDefinition, ToolOutput};
 /// use std::sync::Arc;
 ///
 /// struct MyTool { counter: std::sync::atomic::AtomicUsize }
@@ -329,6 +579,26 @@ pub trait Tool: Send + Sync {
         input_json: &str,
         ctx: ToolExecutionContext,
     ) -> Result<ToolOutput, ToolError>;
+
+    /// Request cooperative cancellation for one started call.
+    ///
+    /// Implementations that own cancellable provider operations should signal
+    /// every live execution identified by `call_id`, then let `execute` return
+    /// the confirmed bounded terminal output. Direct callers may use this
+    /// compatibility surface; Agen uses [`Tool::cancel_execution`] so providers
+    /// can bind cancellation to one exact live attempt.
+    async fn cancel(&self, _call_id: &str) -> Result<(), ToolError> {
+        Ok(())
+    }
+
+    /// Request cooperative cancellation for one exact started execution.
+    ///
+    /// The default preserves existing tools by delegating to `cancel(call_id)`.
+    /// Providers with their own execution registry should override this method
+    /// and key cancellation by [`ToolExecutionContext::execution_id`].
+    async fn cancel_execution(&self, ctx: &ToolExecutionContext) -> Result<(), ToolError> {
+        self.cancel(&ctx.call_id).await
+    }
 }
 
 // =============================================================================
@@ -356,6 +626,9 @@ pub struct ToolCall {
 pub struct ToolResult {
     /// Corresponding tool call ID
     pub tool_use_id: String,
+    /// Typed terminal state.
+    #[serde(default, skip_serializing_if = "ToolResultDisposition::is_success")]
+    pub disposition: ToolResultDisposition,
     /// Short summary (always kept in history)
     pub summary: String,
     /// Detailed output (prunable)
@@ -364,16 +637,29 @@ pub struct ToolResult {
     /// Whether this is an error
     #[serde(default)]
     pub is_error: bool,
+    /// Durable binary details (prunable with `content`).
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub attachments: Vec<Attachment>,
 }
 
 impl ToolResult {
     /// Create a success result from a [`ToolOutput`].
     pub fn from_output(tool_use_id: impl Into<String>, output: ToolOutput) -> Self {
+        Self::from_output_with_disposition(tool_use_id, output, ToolResultDisposition::Success)
+    }
+
+    pub fn from_output_with_disposition(
+        tool_use_id: impl Into<String>,
+        output: ToolOutput,
+        disposition: ToolResultDisposition,
+    ) -> Self {
         Self {
             tool_use_id: tool_use_id.into(),
+            disposition,
             summary: output.summary,
             content: output.content,
-            is_error: false,
+            is_error: !disposition.is_success(),
+            attachments: output.attachments,
         }
     }
 
@@ -381,9 +667,26 @@ impl ToolResult {
     pub fn error(tool_use_id: impl Into<String>, message: impl Into<String>) -> Self {
         Self {
             tool_use_id: tool_use_id.into(),
+            disposition: ToolResultDisposition::Error,
             summary: message.into(),
             content: None,
             is_error: true,
+            attachments: Vec::new(),
+        }
+    }
+
+    /// Close an execution whose completion and side effects cannot be confirmed.
+    pub fn outcome_unknown(tool_use_id: impl Into<String>) -> Self {
+        Self {
+            tool_use_id: tool_use_id.into(),
+            disposition: ToolResultDisposition::OutcomeUnknown,
+            summary: "Tool execution outcome unknown".to_string(),
+            content: Some(
+                "Execution was interrupted before completion could be confirmed. Completion and side effects are unknown."
+                    .to_string(),
+            ),
+            is_error: true,
+            attachments: Vec::new(),
         }
     }
 }

crates/agen/tests/annotated_history_test.rs

@@ -0,0 +1,210 @@
+mod common;
+
+use agen::interceptor::{
+    AssistantTurnEndContext, Interceptor, InterceptorCallId, InterceptorInvocation,
+    InterceptorPhase, InterceptorResult, PendingHistoryAppendsContext, PreLlmRequestContext,
+    PreRequestAction, PromptAction, PromptSubmitContext, RunExitContext, TurnEndAction,
+};
+use agen::llm_client::event::{Event, ResponseStatus, StatusEvent};
+use agen::{Engine, EngineError, History, HistoryEntry, Item, Role};
+use async_trait::async_trait;
+use common::MockLlmClient;
+use std::sync::{Arc, Mutex};
+
+fn completed_text_events(text: &str) -> Vec<Event> {
+    vec![
+        Event::text_block_start(0),
+        Event::text_delta(0, text),
+        Event::text_block_stop(0, None),
+        Event::Status(StatusEvent {
+            status: ResponseStatus::Completed,
+        }),
+    ]
+}
+
+#[tokio::test]
+async fn run_preserves_item_annotations_without_projecting_them() {
+    let client = MockLlmClient::new(completed_text_events("assistant reply"));
+    let engine = Engine::<_, agen::state::Mutable, String>::new_annotated(client);
+    let mut history = History::<String>::new();
+    let mut next = 0usize;
+    let mut annotate = |item: &Item| {
+        next += 1;
+        let kind = match item {
+            Item::Message { role, .. } => match role {
+                Role::User => "user",
+                Role::Assistant => "assistant",
+                Role::System => "system",
+            },
+            Item::ToolCall { .. } => "tool_call",
+            Item::ToolResult { .. } => "tool_result",
+            Item::Reasoning { .. } => "reasoning",
+        };
+        Ok(format!("{next}:{kind}"))
+    };
+
+    let output = engine
+        .run_with_annotation(&mut history, "hello", &mut annotate)
+        .await;
+
+    assert!(matches!(output.result, agen::EngineRunExit::Finished));
+    assert_eq!(history.len(), 2);
+    assert_eq!(history.entries()[0].annotation, "1:user");
+    assert_eq!(history.entries()[1].annotation, "2:assistant");
+    assert_eq!(history.items_cloned().len(), 2);
+}
+
+#[derive(Clone)]
+struct AnnotationObservingInterceptor {
+    observed: Arc<Mutex<Vec<(InterceptorInvocation, Vec<String>)>>>,
+}
+
+impl AnnotationObservingInterceptor {
+    fn record(&self, invocation: &InterceptorInvocation, history: &[HistoryEntry<String>]) {
+        self.observed.lock().unwrap().push((
+            invocation.clone(),
+            history
+                .iter()
+                .map(|entry| entry.annotation.clone())
+                .collect(),
+        ));
+    }
+}
+
+#[async_trait]
+impl Interceptor<String> for AnnotationObservingInterceptor {
+    async fn on_prompt_submit(
+        &self,
+        context: PromptSubmitContext<'_, String>,
+    ) -> InterceptorResult<PromptAction> {
+        self.record(&context.invocation, context.history);
+        Ok(PromptAction::Continue)
+    }
+
+    async fn pending_history_appends(
+        &self,
+        context: PendingHistoryAppendsContext<'_, String>,
+    ) -> InterceptorResult<Vec<Item>> {
+        self.record(&context.invocation, context.history);
+        Ok(Vec::new())
+    }
+
+    async fn pre_llm_request(
+        &self,
+        context: PreLlmRequestContext<'_, String>,
+    ) -> InterceptorResult<PreRequestAction> {
+        self.record(&context.invocation, context.history);
+        Ok(PreRequestAction::Continue)
+    }
+
+    async fn on_assistant_turn_end(
+        &self,
+        context: AssistantTurnEndContext<'_, String>,
+    ) -> InterceptorResult<TurnEndAction> {
+        assert_eq!(context.assistant_entries.len(), 1);
+        assert_eq!(context.assistant_entries[0].annotation, "2:assistant");
+        self.record(&context.invocation, context.history);
+        Ok(TurnEndAction::Finish)
+    }
+
+    async fn on_run_exit(&self, context: RunExitContext<'_, String>) -> InterceptorResult<()> {
+        self.record(&context.invocation, context.history);
+        Ok(())
+    }
+}
+
+#[tokio::test]
+async fn interceptor_contexts_preserve_annotations_and_typed_lifecycle_identity() {
+    let client = MockLlmClient::new(completed_text_events("assistant reply"));
+    let mut engine = Engine::<_, agen::state::Mutable, String>::new_annotated(client);
+    let observed = Arc::new(Mutex::new(Vec::new()));
+    engine.set_interceptor(AnnotationObservingInterceptor {
+        observed: observed.clone(),
+    });
+    let mut history = History::<String>::new();
+    let mut next = 0usize;
+    let mut annotate = |item: &Item| {
+        next += 1;
+        let kind = if item.is_assistant_message() {
+            "assistant"
+        } else {
+            "user"
+        };
+        Ok(format!("{next}:{kind}"))
+    };
+
+    let output = engine
+        .run_with_annotation(&mut history, "hello", &mut annotate)
+        .await;
+    assert!(matches!(output.result, agen::EngineRunExit::Finished));
+
+    let observed = observed.lock().unwrap();
+    let phases: Vec<_> = observed
+        .iter()
+        .map(|(invocation, _)| invocation.phase)
+        .collect();
+    assert_eq!(
+        phases,
+        [
+            InterceptorPhase::PromptSubmit,
+            InterceptorPhase::PendingHistoryAppends,
+            InterceptorPhase::PreLlmRequest,
+            InterceptorPhase::AssistantTurnEnd,
+            InterceptorPhase::RunExit,
+        ]
+    );
+    assert!(
+        observed
+            .iter()
+            .all(|(invocation, _)| invocation.run_id == observed[0].0.run_id)
+    );
+    assert_eq!(
+        observed
+            .iter()
+            .map(|(invocation, _)| invocation.counters.invocation.get())
+            .collect::<Vec<_>>(),
+        [0, 1, 2, 3, 4]
+    );
+    assert_eq!(observed[2].0.call_id, Some(InterceptorCallId::Llm(0)));
+    assert_eq!(observed[3].0.call_id, Some(InterceptorCallId::Llm(0)));
+    assert_eq!(observed[1].1, ["1:user"]);
+    assert_eq!(observed[2].1, ["1:user"]);
+    assert_eq!(observed[3].1, ["1:user", "2:assistant"]);
+    assert_eq!(observed[4].1, ["1:user", "2:assistant"]);
+}
+
+#[test]
+fn append_failure_does_not_make_item_live() {
+    let client = MockLlmClient::new(vec![]);
+    let mut engine = Engine::<_, agen::state::Mutable, usize>::new_annotated(client);
+    let mut history = History::<usize>::new();
+    let mut fail = |_item: &Item| Err("commit failed".to_string());
+
+    let err = engine
+        .append_history_with(&mut history, [Item::user_message("uncommitted")], &mut fail)
+        .unwrap_err();
+
+    assert!(matches!(err, EngineError::HistoryAppend(message) if message == "commit failed"));
+    assert!(history.is_empty());
+}
+
+#[test]
+fn replacement_keeps_items_and_annotations_together() {
+    let mut history = History::from_entries(vec![
+        HistoryEntry::new(Item::user_message("old"), "old-ann".to_string()),
+        HistoryEntry::new(Item::user_message("second"), "second-ann".to_string()),
+    ]);
+
+    history.truncate(1);
+    assert_eq!(history.entries()[0].item.as_text(), Some("old"));
+    assert_eq!(history.entries()[0].annotation, "old-ann");
+
+    let previous = history.replace_entries(vec![HistoryEntry::new(
+        Item::user_message("restored"),
+        "restored-ann".to_string(),
+    )]);
+
+    assert_eq!(previous.len(), 1);
+    assert_eq!(history.entries()[0].item.as_text(), Some("restored"));
+    assert_eq!(history.entries()[0].annotation, "restored-ann");
+}

crates/agen/tests/callback_test.rs

@@ -8,13 +8,13 @@ use std::sync::atomic::{AtomicUsize, Ordering};
 use std::sync::{Arc, Mutex};
 use std::time::Duration;
 
+use agen::Engine;
+use agen::llm_client::event::{Event, ResponseStatus, StatusEvent as ClientStatusEvent};
+use agen::llm_client::retry::RetryPolicy;
+use agen::llm_client::{ClientError, LlmClient, Request, ResponseStream};
+use agen::tool::{Tool, ToolDefinition, ToolError, ToolMeta, ToolOutput};
 use async_trait::async_trait;
 use common::MockLlmClient;
-use llm_engine::Engine;
-use llm_engine::llm_client::event::{Event, ResponseStatus, StatusEvent as ClientStatusEvent};
-use llm_engine::llm_client::retry::RetryPolicy;
-use llm_engine::llm_client::{ClientError, LlmClient, Request, ResponseStream};
-use llm_engine::tool::{Tool, ToolDefinition, ToolError, ToolMeta, ToolOutput};
 
 #[derive(Clone)]
 struct FailOnceClient {
@@ -58,6 +58,7 @@ async fn test_callback_llm_retry_event() {
         max_attempts: 2,
         total_timeout: Duration::from_secs(1),
     });
+    let mut history = agen::History::new();
 
     let notices = Arc::new(Mutex::new(Vec::new()));
     let sink = notices.clone();
@@ -65,8 +66,11 @@ async fn test_callback_llm_retry_event() {
         sink.lock().unwrap().push((llm_call, notice.clone()));
     });
 
-    let result = engine.run("retry once").await;
-    assert!(result.is_ok(), "engine should succeed after one retry");
+    let result = engine.run(&mut history, "retry once").await;
+    assert!(
+        matches!(result.result, agen::EngineRunExit::Finished),
+        "engine should succeed after one retry"
+    );
 
     let notices = notices.lock().unwrap();
     assert_eq!(notices.len(), 1);
@@ -91,6 +95,7 @@ async fn test_callback_text_block_events() {
 
     let client = MockLlmClient::new(events);
     let mut engine = Engine::new(client);
+    let mut history = agen::History::new();
 
     let text_deltas = Arc::new(Mutex::new(Vec::new()));
     let text_completes = Arc::new(Mutex::new(Vec::new()));
@@ -108,9 +113,12 @@ async fn test_callback_text_block_events() {
         });
     });
 
-    // Mutable::run consumes self, returns (Locked, EngineResult)
-    let result = engine.run("Greet me").await;
-    assert!(result.is_ok(), "Engine should complete");
+    // Mutable::run consumes self, returns (Locked, EngineRunExit)
+    let result = engine.run(&mut history, "Greet me").await;
+    assert!(
+        matches!(result.result, agen::EngineRunExit::Finished),
+        "Engine should complete"
+    );
 
     let deltas = text_deltas.lock().unwrap();
     assert_eq!(deltas.len(), 2);
@@ -137,6 +145,7 @@ async fn test_callback_tool_call_complete() {
 
     let client = MockLlmClient::new(events);
     let mut engine = Engine::new(client);
+    let mut history = agen::History::new();
 
     let tool_starts = Arc::new(Mutex::new(Vec::<(String, String)>::new()));
     let tool_completes = Arc::new(Mutex::new(Vec::new()));
@@ -154,8 +163,8 @@ async fn test_callback_tool_call_complete() {
         });
     });
 
-    // Mutable::run consumes self, returns (Locked, EngineResult)
-    let _ = engine.run("Weather please").await;
+    // Mutable::run consumes self, returns (Locked, EngineRunExit)
+    let _ = engine.run(&mut history, "Weather please").await;
 
     let starts = tool_starts.lock().unwrap();
     assert_eq!(starts.len(), 1);
@@ -183,6 +192,7 @@ async fn test_callback_turn_events() {
 
     let client = MockLlmClient::new(events);
     let mut engine = Engine::new(client);
+    let mut history = agen::History::new();
 
     let turn_starts = Arc::new(Mutex::new(Vec::new()));
     let turn_ends = Arc::new(Mutex::new(Vec::new()));
@@ -197,9 +207,9 @@ async fn test_callback_turn_events() {
         ends.lock().unwrap().push(turn);
     });
 
-    // Mutable::run consumes self, returns (Locked, EngineResult)
-    let result = engine.run("Do something").await;
-    assert!(result.is_ok());
+    // Mutable::run consumes self, returns (Locked, EngineRunExit)
+    let result = engine.run(&mut history, "Do something").await;
+    assert!(matches!(result.result, agen::EngineRunExit::Finished));
 
     let starts = turn_starts.lock().unwrap();
     let ends = turn_ends.lock().unwrap();
@@ -221,7 +231,7 @@ impl Tool for FixedOutputTool {
     async fn execute(
         &self,
         _input_json: &str,
-        _ctx: llm_engine::tool::ToolExecutionContext,
+        _ctx: agen::tool::ToolExecutionContext,
     ) -> Result<ToolOutput, ToolError> {
         Ok(self.output.clone())
     }
@@ -254,12 +264,14 @@ async fn test_callback_tool_result_events() {
 
     let client = MockLlmClient::new(events);
     let mut engine = Engine::new(client);
+    let mut history = agen::History::new();
 
     engine.register_tool(fixed_tool(
         "fixed",
         ToolOutput {
             summary: "did the thing".into(),
             content: Some("full detail body".into()),
+            attachments: Vec::new(),
         },
     ));
 
@@ -275,7 +287,7 @@ async fn test_callback_tool_result_events() {
         ));
     });
 
-    let _ = engine.run("call it").await;
+    let _ = engine.run(&mut history, "call it").await;
 
     let observed = captured.lock().unwrap();
     assert_eq!(observed.len(), 1);
@@ -296,7 +308,7 @@ impl Tool for ErroringTool {
     async fn execute(
         &self,
         _input_json: &str,
-        _ctx: llm_engine::tool::ToolExecutionContext,
+        _ctx: agen::tool::ToolExecutionContext,
     ) -> Result<ToolOutput, ToolError> {
         Err(ToolError::ExecutionFailed(self.message.clone()))
     }
@@ -329,6 +341,7 @@ async fn test_callback_tool_result_error_path() {
 
     let client = MockLlmClient::new(events);
     let mut engine = Engine::new(client);
+    let mut history = agen::History::new();
 
     engine.register_tool(erroring_tool("erroring", "boom"));
 
@@ -344,7 +357,7 @@ async fn test_callback_tool_result_error_path() {
         ));
     });
 
-    let _ = engine.run("fail it").await;
+    let _ = engine.run(&mut history, "fail it").await;
 
     let observed = captured.lock().unwrap();
     assert_eq!(observed.len(), 1);
@@ -373,6 +386,7 @@ async fn test_callback_usage_events() {
 
     let client = MockLlmClient::new(events);
     let mut engine = Engine::new(client);
+    let mut history = agen::History::new();
 
     let usage_events = Arc::new(Mutex::new(Vec::new()));
 
@@ -381,8 +395,8 @@ async fn test_callback_usage_events() {
         usages.lock().unwrap().push(event.clone());
     });
 
-    // Mutable::run consumes self, returns (Locked, EngineResult)
-    let _ = engine.run("Hello").await;
+    // Mutable::run consumes self, returns (Locked, EngineRunExit)
+    let _ = engine.run(&mut history, "Hello").await;
 
     let usages = usage_events.lock().unwrap();
     assert_eq!(usages.len(), 1);

crates/agen/tests/common/mod.rs

@@ -6,11 +6,11 @@ use std::path::{Path, PathBuf};
 use std::pin::Pin;
 use std::sync::{Arc, Mutex};
 
+use agen::llm_client::event::{BlockType, DeltaContent, Event};
+use agen::llm_client::{ClientError, LlmClient, Request};
+use agen::timeline::{Handler, TextBlockEvent, TextBlockKind, Timeline};
 use async_trait::async_trait;
 use futures::Stream;
-use llm_engine::llm_client::event::{BlockType, DeltaContent, Event};
-use llm_engine::llm_client::{ClientError, LlmClient, Request};
-use llm_engine::timeline::{Handler, TextBlockEvent, TextBlockKind, Timeline};
 
 use std::sync::atomic::{AtomicUsize, Ordering};
 
@@ -19,6 +19,7 @@ use std::sync::atomic::{AtomicUsize, Ordering};
 pub struct MockLlmClient {
     responses: Arc<Vec<Vec<Event>>>,
     call_count: Arc<AtomicUsize>,
+    requests: Arc<Mutex<Vec<Request>>>,
 }
 
 impl MockLlmClient {
@@ -30,6 +31,7 @@ impl MockLlmClient {
         Self {
             responses: Arc::new(responses),
             call_count: Arc::new(AtomicUsize::new(0)),
+            requests: Arc::new(Mutex::new(Vec::new())),
         }
     }
 
@@ -41,6 +43,10 @@ impl MockLlmClient {
     pub fn event_count(&self) -> usize {
         self.responses.iter().map(|v| v.len()).sum()
     }
+
+    pub fn requests(&self) -> Vec<Request> {
+        self.requests.lock().unwrap().clone()
+    }
 }
 
 #[async_trait]
@@ -51,8 +57,9 @@ impl LlmClient for MockLlmClient {
 
     async fn stream(
         &self,
-        _request: Request,
+        request: Request,
     ) -> Result<Pin<Box<dyn Stream<Item = Result<Event, ClientError>> + Send>>, ClientError> {
+        self.requests.lock().unwrap().push(request);
         let count = self.call_count.fetch_add(1, Ordering::SeqCst);
         if count >= self.responses.len() {
             return Err(ClientError::Api {
@@ -272,7 +279,7 @@ pub fn assert_timeline_integration(subdir: &str) {
     });
 
     for event in &events {
-        let timeline_event: llm_engine::timeline::event::Event = event.clone().into();
+        let timeline_event: agen::timeline::event::Event = event.clone().into();
         timeline.dispatch(&timeline_event);
     }
 

crates/agen/tests/engine_fixtures.rs

@@ -9,10 +9,10 @@ use std::path::Path;
 use std::sync::Arc;
 use std::sync::atomic::{AtomicUsize, Ordering};
 
+use agen::Engine;
+use agen::tool::{Tool, ToolDefinition, ToolError, ToolMeta, ToolOutput};
 use async_trait::async_trait;
 use common::MockLlmClient;
-use llm_engine::Engine;
-use llm_engine::tool::{Tool, ToolDefinition, ToolError, ToolMeta, ToolOutput};
 
 /// Fixture directory path
 fn fixtures_dir() -> std::path::PathBuf {
@@ -61,7 +61,7 @@ impl Tool for MockWeatherTool {
     async fn execute(
         &self,
         input_json: &str,
-        _ctx: llm_engine::tool::ToolExecutionContext,
+        _ctx: agen::tool::ToolExecutionContext,
     ) -> Result<ToolOutput, ToolError> {
         self.call_count.fetch_add(1, Ordering::SeqCst);
 
@@ -102,7 +102,7 @@ fn test_mock_client_from_fixture() {
 /// Creates a client with programmatically constructed events instead of using fixture files.
 #[test]
 fn test_mock_client_from_events() {
-    use llm_engine::llm_client::event::Event;
+    use agen::llm_client::event::Event;
 
     // Specify events directly
     let events = vec![
@@ -134,11 +134,15 @@ async fn test_engine_simple_text_response() {
 
     let client = MockLlmClient::from_fixture(&fixture_path).unwrap();
     let engine = Engine::new(client);
+    let mut history = agen::History::new();
 
     // Send a simple message (Mutable::run consumes self, returns tuple)
-    let result = engine.run("Hello").await;
+    let result = engine.run(&mut history, "Hello").await;
 
-    assert!(result.is_ok(), "Engine should complete successfully");
+    assert!(
+        matches!(result.result, agen::EngineRunExit::Finished),
+        "Engine should complete successfully"
+    );
 }
 
 /// Verify that Engine can correctly process responses containing tool calls
@@ -156,6 +160,7 @@ async fn test_engine_tool_call() {
 
     let client = MockLlmClient::from_fixture(&fixture_path).unwrap();
     let mut engine = Engine::new(client);
+    let mut history = agen::History::new();
 
     // Register tool
     let weather_tool = MockWeatherTool::new();
@@ -163,7 +168,9 @@ async fn test_engine_tool_call() {
     engine.register_tool(weather_tool.definition());
 
     // Send message (Mutable::run consumes self, returns tuple)
-    let _result = engine.run("What's the weather in Tokyo?").await;
+    let _result = engine
+        .run(&mut history, "What's the weather in Tokyo?")
+        .await;
 
     // Verify tool was called
     // Note: max_turns=1 so no request is sent after tool result
@@ -180,7 +187,7 @@ async fn test_engine_tool_call() {
 /// Useful when test independence is needed and external file dependency should be eliminated.
 #[tokio::test]
 async fn test_engine_with_programmatic_events() {
-    use llm_engine::llm_client::event::{Event, ResponseStatus, StatusEvent};
+    use agen::llm_client::event::{Event, ResponseStatus, StatusEvent};
 
     // Construct event sequence programmatically
     let events = vec![
@@ -195,11 +202,15 @@ async fn test_engine_with_programmatic_events() {
 
     let client = MockLlmClient::new(events);
     let engine = Engine::new(client);
+    let mut history = agen::History::new();
 
     // Mutable::run consumes self, returns tuple
-    let result = engine.run("Greet me").await;
+    let result = engine.run(&mut history, "Greet me").await;
 
-    assert!(result.is_ok(), "Engine should complete successfully");
+    assert!(
+        matches!(result.result, agen::EngineRunExit::Finished),
+        "Engine should complete successfully"
+    );
 }
 
 /// Verify that ToolCallCollector correctly collects ToolCall from ToolUse block events
@@ -208,8 +219,8 @@ async fn test_engine_with_programmatic_events() {
 /// correctly extracts id, name, and input (JSON).
 #[tokio::test]
 async fn test_tool_call_collector_integration() {
-    use llm_engine::llm_client::event::Event;
-    use llm_engine::timeline::{Timeline, ToolCallCollector};
+    use agen::llm_client::event::Event;
+    use agen::timeline::{Timeline, ToolCallCollector};
 
     // Event sequence containing ToolUse block
     let events = vec![
@@ -225,7 +236,7 @@ async fn test_tool_call_collector_integration() {
 
     // Dispatch events
     for event in &events {
-        let timeline_event: llm_engine::timeline::event::Event = event.clone().into();
+        let timeline_event: agen::timeline::event::Event = event.clone().into();
         timeline.dispatch(&timeline_event);
     }