phronomy 0.13.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd9fb679db0e4d4c582a82dad543ca0d93806878e0936404cd4255d2a48a741b
-  data.tar.gz: 511a6bfb90ec0524aafb201996bc251c9b1923a2d3ff4d1b389aa7d62f2d3395
+  metadata.gz: b0ea2e317999f3202e06d5afac0b46509fa22a813531919447040d1e048a087f
+  data.tar.gz: ae5740df9899b7463b35b54b885948ca1e0e42e01b8b85b1a93fd6437022c90b
 SHA512:
-  metadata.gz: 9efc33585c40e3d5b4559121cd5654c9687608ff05ab684818e27ac5d4672264352fb68fbf4efa6436ed8666a0b194acfdcea7511fce67a5eda50e690cd80803
-  data.tar.gz: 0142742c7875411622ad37ae2918164130bd84fe237da2e100b69578f67380a08c61ae6ca77cfdcac5892ea7bd56140c39b374b8d0543d11cd359bda587f12df
+  metadata.gz: 123b0998a7a299f97ce981a3561c68990c41e05decb534b4c4664e441abd6cf368e04ecf6cea61df6a1ea2c4016850b093e0c208aa034fc02b1fa498e0078263
+  data.tar.gz: f1ba3ee6163b1a746bd99f00241daf286ac5eb3d8d1e30f7caa739de1de5dd900f3b19b90a063c4a9f19f494a1e9ac1dca59b4d32ade41deabe71f849803ac62

data/CHANGELOG.md

@@ -7,6 +7,161 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [Unreleased]
+
+### Added
+
+- `Workflow#signal(thread_id:, event:, payload:)` for FIFO delivery to a live
+  Workflow FSMSession.
+- Workflow transition `action:` callbacks, executed after source exit callbacks
+  and before target entry callbacks. Actions may accept `(context)` or
+  `(context, event)` and may return a replacement Workflow context.
+- `InvalidAsyncWorkflowActionError` and
+  `InvalidAsyncTransitionActionError`. Transition actions may start async work,
+  but returning a `Phronomy::Task` is rejected rather than implicitly awaited.
+- Symmetric Agent `on_event:` support for `invoke_async` and `stream_async`;
+  streaming differs only by adding `:token` events.
+- `Agent#approve_async` and `Agent::Base.approve_async` resume a suspended
+  AgentInvocation without blocking the caller and return a `Phronomy::Task`.
+- Streaming invocations resumed through `approve_async` continue to deliver
+  terminal stream events on the Runtime-owned EventLoop thread.
+- `Phronomy::Metrics.snapshot` now reports `event_loop_queue_depth` and
+  `event_loop_queue_max_depth`.
+- EventLoop emits a rate-limited warning when its shared event queue reaches
+  1,000 pending entries. Events are observed only; they are not dropped.
+
+### Removed
+
+- Implicit awaiting of Task-returning Workflow/Agent/Tool entry actions and the
+  Workflow `action_timeout:` DSL. Entry actions are synchronous RTC callbacks.
+- The duplicate caller-thread `WorkflowRunner#run_workflow` execution path.
+- Agent-wide automatic replay: `Agent::Base.retry_policy` and the `Retryable`
+  concern. A failed AgentInvocation is no longer started again by Phronomy.
+- Agent-class `invoke_timeout`. Callers that need a root deadline should pass an
+  `InvocationContext` with `deadline:` or `cancellation_token:`.
+- Phronomy LLM operation timeout `config[:llm_timeout]`; configure RubyLLM's
+  `request_timeout` instead.
+- Generic Tool retry DSL (`retry_on`, `retry_policies`) and
+  `config[:tool_timeout]`; Tool/client implementations own their transport policy.
+- `max_parallel_tools` from Agent, AgentInvocation, ParallelToolChat, and
+  InvocationContext.
+- Unused `InvocationContext#provider_limits`.
+- `Configuration#stream_queue_max_size`, which no longer affected the
+  Runtime-owned EventLoop streaming path.
+
+### Changed
+
+- `Workflow#invoke`, `#invoke_async`, and `#stream` now share context
+  preparation, StateStore load/save, EventLoop registration, and FSMSession
+  execution.
+- Workflow entry and transition action return values use the same
+  `set_graph_metadata` context protocol as FSMSession, including duck-typed
+  context replacements.
+- Agent terminal outcomes are delivered to `on_event` before the returned Task
+  is settled. `Task#on_complete`, `wait_result`, and cancellation remain active.
+- Mapping Agent events to Workflow events, correlation, stale-event handling,
+  result persistence, and external Task cancellation are application concerns.
+- LLM transport timeout, transient-error retry, backoff, and jitter are delegated
+  to RubyLLM or another configured LLM adapter. Phronomy only translates the
+  adapter's final provider error.
+- Agent execution now creates exactly one AgentInvocation session per call.
+- Parallel Tool mode dispatches the complete authorized ToolCall batch; Runtime's
+  bounded workers and queues remain the coarse process-protection boundary.
+- Caller-provided deadline and cancellation-token propagation is unchanged.
+
+### Fixed
+
+- `Agent#approve` now rejects EventLoop re-entry instead of synchronously waiting
+  for work that can only be dispatched by that same EventLoop.
+
+---
+
+## [0.14.0] - 2026-07-27
+
+### Changed
+
+- **Runtime-owned EventLoop lifecycle** (`refactor: Runtime-owned EventLoop lifecycle`):
+  - `Runtime#event_loop` lazy accessor replaces the standalone `EventLoop.instance` singleton.
+  - `EventLoop.instance` is retained as a deprecated compatibility bridge to `Runtime.instance.event_loop`.
+  - EventLoop dispatcher now runs in a dedicated real-thread service scheduler owned by `Runtime`,
+    removing the hidden `Runtime.new(scheduler: ThreadScheduler.new)` inside `EventLoop`.
+  - EventLoop lifecycle is terminal: `:running` → `:draining` → `:stopping` → `:terminated` / `:failed`.
+  - `STOP` Object sentinel replaces the `:__stop__` symbol; stale sentinel handling is removed.
+  - `@running` instance variable removed; dispatch loop driven solely by the STOP sentinel.
+  - EventLoop-specific `@shutdown_token` removed.
+  - `outstanding_sessions` counter covers queue-pending `:start` events from `register` time,
+    ensuring drain correctness when shutdown races with queued sessions.
+  - Shutdown timeout: `AbortAndStop` control command path plus `cancel!` → `join(cancel_grace)` fallback.
+  - `Runtime.reset_default!` replaces `EventLoop.reset!`; `Phronomy.reset_runtime!` performs real Runtime shutdown then config reset.
+  - `ShutdownResult` value object separates `runtime_outcome` from `cleanup_status`.
+  - `FSMSession` now receives `event_loop:` and `timer_queue_provider:` explicitly at build time.
+  - Agent / Workflow phase-machine builders capture the owning EventLoop at invocation time;
+    `EventLoop.instance` is no longer re-fetched inside async callbacks or timers.
+
+### Fixed
+
+- **Double-dispatch regression (P0 hotfix — commit `2cc8c6c1`)**: `EventLoop#stop` no longer clears `@task`
+  while the dispatcher task is still alive. A subsequent `start` call detects the live task and does
+  not spawn a second dispatch loop on the same queue. Includes `:cancel_timeout` status for the case
+  where `cancel!` does not terminate the task within `cancel_grace` seconds.
+- **`EventLoop.reset!` safety**: raises `Phronomy::Error` when the dispatcher task is still alive
+  after stop instead of unconditionally clearing the singleton.
+- **`EventLoop#task_alive?`**: new public helper; thread-safe boolean for use in reset logic.
+
+
+  `BlockingAdapterPool#submit` previously stored the timeout value but never
+  registered a wall-clock timer, so `config: { llm_timeout: N }` and
+  `config: { tool_timeout: N }` had no effect for callers using `on_complete`
+  (the normal non-streaming Agent path). The timer is now armed before queue
+  admission and calls `fire_timeout!` when the deadline expires.
+
+### Changed
+
+- **`blocking_wait(timeout:)` is now a waiter-local deadline only**:
+  Previously, the timeout passed to `blocking_wait` (or `wait_result`) would settle the
+  operation, set `abandoned? = true`, and increment `abandoned_count` — affecting
+  all future waiters and callbacks. It is now scoped to the single calling thread:
+  the caller receives `TimeoutError`, but the operation remains unsettled. Other
+  waiters or `on_complete` callbacks will still receive the eventual result unless
+  a separate submit-time deadline or cancellation settles the operation first.
+  **Callers that relied on `blocking_wait(timeout:)` to abandon and count an
+  operation must switch to a submit-time `timeout:` passed to `pool.submit`.**
+
+- **Queue-timeout operations are not counted as abandoned**:
+  When a submit-time timeout fires before the worker picks up the operation,
+  the operation is settled with `TimeoutError` but `abandoned? == false` and
+  `abandoned_count` is not incremented. Only timeouts that fire while the block
+  is executing set `abandoned? = true`.
+
+- **MCP client support now requires `mcp` 1.x**:
+  The `mcp` SDK 0.x dependency is no longer supported. The constraint is now
+  `mcp ~> 1.0`. `faraday` and `event_stream_parser` are added as direct runtime
+  dependencies so HTTP/SSE transport works without relying on transitive
+  resolution through RubyLLM.
+
+- **MCP Tool error handling follows MCP 1.x semantics**:
+  JSON-RPC errors (`MCP::Client::ServerError`) are converted to
+  `Phronomy::ToolError`. Cancellations (`MCP::CancelledError`) are converted to
+  `Phronomy::CancellationError`. Tool-level `isError: true` results are
+  returned to the model as error text rather than raising, allowing the LLM to
+  self-correct.
+
+- **MCP input schemas now use a strict supported subset of JSON Schema 2020-12**:
+  Unsupported structural keywords (`oneOf`, `anyOf`, `allOf`, `$ref`, etc.),
+  nested object/array types, and nullable type arrays fail fast with
+  `Phronomy::ToolError` at `from_server` time. Constraint-only annotations
+  (`minimum`, `maxLength`, `format`, etc.) produce a logger warning and are
+  otherwise ignored. See [`docs/mcp-client.md`](docs/mcp-client.md) for the
+  full supported schema subset.
+
+- **MCP client cancellation now invalidates the transport**:
+  After a `MCP::CancelledError` the internal client reference is set to `nil`
+  and the old transport is closed asynchronously. The next tool call creates a
+  fresh connection, preventing stdio response mis-routing from a lingering SDK
+  worker thread.
+
+---
+
 ## [0.13.0] - 2026-07-23
 
 ### Added

data/README.md

@@ -27,7 +27,6 @@ It provides composable building blocks — Workflows, Agents, Tools, Filters, an
 | Feature | Stability |
 |---|---|
 | **Workflow** — Stateful, branching workflows with wait_state/send_event | Stable |
-| **Workflow action_timeout** — Per-state `action_timeout:` keyword on `state` DSL; cancels Task-returning entry actions that exceed the limit and raises `Phronomy::ActionTimeoutError` | Beta |
 | **Agent** — ReAct-style tool-calling agents with guardrails and conversation history | Stable |
 | **Before-Completion Hook** — Three-tier LLM parameter injection | Stable |
 | **Context Management** — Token budget calculation, estimation, and pruning; `Agent::Base` protected hooks: `build_context` (overridable), `trim_messages`, `trim_to_budget`, `compact_messages`, `budget_exceeded?`, `drop_messages_over` | Stable |
@@ -37,7 +36,7 @@ It provides composable building blocks — Workflows, Agents, Tools, Filters, an
 | **Output Parser** — JSON and Struct-mapped parsers for structured LLM responses | Stable |
 | **Eval Framework** — Dataset-driven evaluation with multiple scorer types | Beta |
 | **Tracing** — Pluggable span-based observability | Stable |
-| **Error Taxonomy** — `RateLimitError`, `AuthenticationError`, `ContextLengthError`, `TransportError` (subclasses of `Phronomy::Error`) raised at the agent retry boundary | Beta |
+| **Error Taxonomy** — final RubyLLM/provider errors are translated to `RateLimitError`, `AuthenticationError`, `ContextLengthError`, and `TransportError` without replaying the Agent invocation | Beta |
 
 **Knowledge and integration**
 
@@ -49,22 +48,25 @@ It provides composable building blocks — Workflows, Agents, Tools, Filters, an
 | **MCP Tool** — `Phronomy::Tools::Mcp`: Model Context Protocol server integration via the official `mcp` gem; `Phronomy::Tools::Agent`: wraps an agent class as a callable tool via `from_agent` | Beta |
 | **Vector Search Tool** — `Phronomy::Tools::VectorSearch`: wraps a `VectorStore` and `Embeddings` adapter as a callable agent tool via `from_store` | Beta |
 
-**Execution and reliability**
-
-| Feature | Stability |
+| **Execution and reliability** | |
 |---|---|
-| **Workflow EventLoop Mode** — Opt-in event-driven execution: `Phronomy.configure { \|c\| c.event_loop = true }` | Experimental |
-| **Agent EventLoop Mode** — `Agent#invoke` (non-blocking via EventLoop), `Agent#invoke_async` + `Task#map` (child-agent pattern for Workflow integration), parallel tool dispatch via `ParallelToolChat` | Experimental |
-| **`invoke_async` / `call_async`** — `Agent::Base#invoke_async` and `Workflow#invoke_async` return a `Task`; `Agent::Context::Capability::Base#call_async` similarly; compatible with EventLoop and standalone contexts | Experimental |
-| **`Task#map`** — transforms a `Task`'s completed value via a block; returns a new `Task` whose value is the block's return value; if the source task fails or is cancelled the mapped task propagates the error without calling the block; primary use-case: `invoke_async.map { \|r\| ctx.merge(answer: r[:output]) }` to wire agent results into a `WorkflowContext` | Experimental |
+| **EventLoop** — Runtime-owned event-driven execution core shared by all Agent invocations, Tool invocations, and Workflow sessions. Not configurable; EventLoop is always active when the Runtime is running. `Phronomy::EventLoop` itself is an internal API | Beta |
+| **`invoke` / `invoke_async`** — `Agent::Base#invoke` blocks the calling thread and returns the final result Hash; `Agent::Base#invoke_async` returns a `Phronomy::Task` immediately without blocking; `Workflow#invoke` and `Workflow#invoke_async` follow the same contract | Stable |
+| **Agent async events** — `invoke_async(..., on_event:)` and `stream_async(..., on_event:)` share `:tool_call`, `:tool_result`, `:approval_required`, `:done`, `:error`, `:timeout`, and `:cancelled`; streaming adds `:token` | Beta |
+| **`stream` / `stream_async`** — callbacks execute on the EventLoop thread and must return quickly; the block form remains a compatibility alias for `on_event:` | Beta |
+| **`stream_callback_error_policy`** — Backward-compatible setting shared by `invoke_async` and `stream_async` terminal `on_event:` callbacks: `:report` (default) preserves the Agent result, while `:fail_task` fails the returned Task with `Phronomy::StreamCallbackError`; Agent execution errors are never replaced by callback errors | Beta |
+| **`invoke_async` / `call_async`** — `Agent::Base#invoke_async` and `Workflow#invoke_async` return a `Task`; `Agent::Context::Capability::Base#call_async` similarly; compatible with EventLoop and standalone contexts | Stable |
+| **`Task#map`** — transforms a Task's completed value and propagates failure/cancellation; Workflow entry and transition actions do not await mapped Tasks | Stable |
 | **CancellationToken** — Cooperative cancellation via `cancel!`/`cancelled?`/`raise_if_cancelled!`; `timeout_after(seconds)` for monotonic-clock deadlines; optional `deadline:` (wall-clock) for backward compatibility; passed as `config: { cancellation_token: token }` to agents and `dispatch_parallel`; injected into `tool.execute` when the method declares a `cancellation_token:` keyword; bridged to `MCP::Cancellation` in `Phronomy::Tools::Mcp#execute` | Experimental |
 | **`dispatch_parallel` / `fan_out` `force_kill:` option** — `force_kill: false` (default) leaves timed-out workers running and raises `TimeoutError` immediately; `force_kill: true` restores the old `Thread#kill` behaviour with a `logger.warn` | Beta |
-| **`execution_mode` DSL on `Agent::Context::Capability::Base`** — Declares how a tool's `execute` should be dispatched: `:cooperative` (same scheduler thread), `:blocking_io` (default; offloaded to `BlockingAdapterPool`), `:cpu_bound`, `:external_process`; `config[:tool_timeout]` sets the per-submit timeout forwarded to `BlockingAdapterPool` for abandoned-operation tracking | Experimental |
+| **`execution_mode` DSL on `Agent::Context::Capability::Base`** — Declares how a tool's `execute` should be dispatched: `:cooperative` (same scheduler thread), `:blocking_io` (default; offloaded to `BlockingAdapterPool`), `:cpu_bound`, `:external_process`; Tool-specific timeout/retry belongs to the Tool implementation or its client | Experimental |
+| **`blocking_io_pool_size` / `blocking_io_queue_size`** — Configure the default `BlockingAdapterPool` via `Phronomy.configure { \|c\| c.blocking_io_pool_size = 20; c.blocking_io_queue_size = 200 }`; all LLM calls, MCP tool calls, and other blocking I/O share this pool; defaults: `pool_size: 10`, `queue_size: 100` | Beta |
 | **`invocation_context:` keyword on `Agent#invoke` / `Workflow#invoke`** — Pass a `Phronomy::InvocationContext` directly; `thread_id`, `cancellation_token`, and `deadline`-based timeout are derived from it; `task_id` / `parent_task_id` appear in trace spans automatically; `config:` keys remain supported as backward-compat aliases | Beta |
-| **`ConcurrencyGate` — unified backpressure** — Counting semaphore that enforces per-resource concurrency caps (`max_concurrent_agent_tasks`, `max_concurrent_tool_tasks`, `max_concurrent_workflow_tasks`, `max_concurrent_llm_calls`, `max_concurrent_vector_searches`); configured via `Phronomy.configure`; backpressure behaviour follows the global `backpressure` setting (`:wait`, `:raise`/`:reject`, `:timeout`); `nil` cap = unlimited (default) | Beta |
 | **Cooperative scheduler yield points** — `Runtime#yield` (cooperative yield; yields the current task's time slice); `Runtime#yield_if_needed(every: N)` (thread-local counter, yields every N calls); CPU-bound detection when `blocking_detect_threshold_ms` is set (warns and increments `non_yield_threshold_violation_count` when a task runs longer than the threshold without yielding); `starvation_threshold_ms` configuration field (default: 50ms) | Beta |
-| **`Phronomy::Metrics`** — `Phronomy::Metrics.snapshot` returns task-tree and pool counters; task-centric keys: `active_agent_tasks`, `active_tool_tasks`, `active_workflow_tasks`, `active_llm_tasks`, `task_wait_time_p50_ms`, `task_wait_time_p95_ms`, `task_run_time_p50_ms`, `task_run_time_p95_ms`, `cancelled_tasks`, `failed_tasks`, `non_yield_threshold_violation_count`; pool/event-loop keys remain for backward compatibility; `Runtime#task_snapshot` exposes task-centric metrics directly | Beta |
-| **`Phronomy.with_configuration` / `Phronomy.reset_runtime!`** — Scoped configuration override and full runtime reset for test isolation | Beta |
+| **`Phronomy::Metrics`** — `Phronomy::Metrics.snapshot` returns task-tree, pool, EventLoop, and queue counters; task-centric keys: `active_agent_tasks`, `active_tool_tasks`, `active_workflow_tasks`, `active_llm_tasks`, `task_wait_time_p50_ms`, `task_wait_time_p95_ms`, `task_run_time_p50_ms`, `task_run_time_p95_ms`, `cancelled_tasks`, `failed_tasks`, `non_yield_threshold_violation_count`; EventLoop queue keys: `event_loop_queue_depth` (current pending entries), `event_loop_queue_max_depth` (peak since start); a rate-limited warning is emitted when depth reaches 1,000 — events are not dropped | Beta |
+| **`Phronomy.with_configuration` / `Phronomy.reset_runtime!`** — Scoped configuration override; `reset_runtime!` performs a full `Runtime#shutdown` (including EventLoop termination) then resets configuration; intended for test isolation | Beta |
+| **`Runtime#event_loop`** — Returns the Runtime-owned `EventLoop` instance; lazy-initialised on first access; EventLoop lifetime is tied to the owning Runtime | Beta |
+| **`Runtime#shutdown(timeout:, cancel_grace:)`** — Irreversible Runtime shutdown: drains active sessions, terminates the EventLoop dispatcher, then stops pools and timers; returns a `ShutdownResult` with `runtime_outcome` and `cleanup_status` fields | Beta |
 
 **Agent patterns**
 
@@ -73,14 +75,14 @@ It provides composable building blocks — Workflows, Agents, Tools, Filters, an
 | **Workflow parallel pattern** — Concurrent branches via application-level threads (no built-in parallel primitive; see the Workflow section for the recommended pattern) | Beta |
 | **Multi-agent** — Agent-as-Tool pattern and hub-and-spoke handoff routing | Beta |
 | **GeneratorVerifier** — Generator-Verifier loop with injectable prompt builders/parsers | Beta |
-| **Agent::Orchestrator** — Parallel subagent dispatch, fan-out, and `subagent` DSL | Beta |
-| **Agent::TeamCoordinator** — Agent teams pattern: LLM coordinator + stateful workers with sequential task assignment (worker-local message history persisted across tasks) | Beta |
+| **`Phronomy::MultiAgent::Orchestrator`** — Parallel subagent dispatch, fan-out, and `subagent` DSL | Beta |
+| **`Phronomy::MultiAgent::TeamCoordinator`** — Agent teams pattern: LLM coordinator + stateful workers with sequential task assignment (worker-local message history persisted across tasks) | Beta |
 | **Agent::SharedState** — Shared state pattern: peer agents collaborate via a shared KnowledgeStore; `member` DSL with per-agent instructions and `coordination` team protocol | Experimental |
-| **`ScopePolicy`** — Configurable policy callable that maps (tool, scope, agent) to `:allow`/`:approve`/`:reject`; default policy auto-routes high-risk scopes through the approval gate | Experimental |
-| **HITL Checkpoint/Resume** — `Agent::Base#invoke` returns `{ suspended: true, checkpoint: Checkpoint }` when an approval-required tool is encountered without a synchronous handler; `Agent::Base#resume(checkpoint, approved:)` resumes execution; `Agent::Base.resume(checkpoint, approved:)` (class-level) resolves the agent class automatically; `Checkpoint#to_h` / `Checkpoint.from_h` for serialization; `Agent::Base#checkpoint_store=` for custom idempotency backends; `CheckpointAlreadyResumedError` raised on duplicate resume | Experimental |
+| **Human-in-the-loop approval** — `Agent::Base#invoke` returns `{ suspended: true, agent_invocation_id: String, approval_request: Phronomy::Agent::ToolApprovalRequest }` when a tool requiring approval is encountered; `Agent::Base#approve(id, approval_request_id:, approved:)` (synchronous) or `Agent::Base#approve_async(id, approval_request_id:, approved:)` (returns `Task`) resumes execution; approval state is in-process only — not persisted across process restarts or shared across pods | Beta |
+| **`tool_approval_policy`** — Instance-level callable that maps each `ToolApprovalRequest` to `:allow`, `:require_approval`, or `:reject`; set on the agent instance before invoking | Beta |
 | **`Filter::Base` — unified value filter interface** — `Phronomy::Filter::Base` with a single abstract method `call(value, **context)`; apply to user input (`add_input_filter` / `input_filter` DSL), final LLM output (`add_output_filter` / `output_filter` DSL), or individual tool return values (`add_tool_result_filter(tool_class?, filter)` / `tool_result_filter` DSL); filters transform values and return the result, or raise `Phronomy::FilterBlockError` to reject; filter chains are composable; the same filter instance can be reused across all three sites | Beta |
 
-> **Public API boundary**: The tables above are the complete list of classes, modules, and features
+> **Public API boundary**: The table above lists the primary public features
 > intended for gem consumers. Every entry has an associated stability label.
 > All other classes, modules, and methods — including everything in the
 > [Advanced / Internal APIs](#advanced--internal-apis) section below — are
@@ -123,10 +125,30 @@ Configure your provider credentials before using agents or chains:
 RubyLLM.configure do |c|
   c.openai_api_key = ENV["OPENAI_API_KEY"]
   # c.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+
+  # RubyLLM owns LLM transport timeout and retry policy.
+  c.request_timeout = 120
+  c.max_retries = 3
+  c.retry_interval = 0.1
+  c.retry_backoff_factor = 2
+  c.retry_interval_randomness = 0.5
 end
 ```
 
-See the [RubyLLM documentation](https://rubyllm.com) for all supported providers.
+See the [RubyLLM documentation](https://rubyllm.com) for all supported providers. Phronomy does not add another LLM timeout or retry layer.
+
+### Execution-policy migration for 0.15
+
+| Removed Phronomy setting | Replacement |
+|---|---|
+| `retry_policy` | RubyLLM transport retry, or explicit application orchestration |
+| `invoke_timeout` | `InvocationContext#deadline` or `cancellation_token` when the caller needs a root deadline |
+| `config[:llm_timeout]` | `RubyLLM.configure { |c| c.request_timeout = ... }` |
+| Tool `retry_on` | Tool/client-specific retry with explicit idempotency guarantees |
+| `config[:tool_timeout]` | Tool/client-native timeout |
+| `max_parallel_tools` | No replacement; `parallel_tool_execution` remains an on/off mode |
+| `InvocationContext#provider_limits` | Configure the provider client directly |
+| `stream_queue_max_size` | No replacement; the shared EventLoop queue is unbounded by design. Monitor `Metrics.snapshot[:event_loop_queue_depth]` instead |
 
 ### Optional dependencies
 
@@ -164,6 +186,75 @@ result = ResearchAgent.new.invoke("What happened in AI research this week?")
 puts result[:output]
 ```
 
+#### Streaming
+
+`stream` blocks the calling thread while delivering events; `stream_async` returns a `Task`
+immediately. Callbacks always execute on the **EventLoop thread** — keep them lightweight and
+do not call blocking I/O or synchronous Agent APIs inside a callback.
+
+```ruby
+# Synchronous streaming — blocks until done
+result = ResearchAgent.new.stream("What happened in AI research this week?") do |event|
+  case event.type
+  when :token           then print event.payload[:content]
+  when :tool_call       then puts "\n[Calling: #{event.payload[:tool_call].name}]"
+  when :tool_result     then puts "[Tool done]"
+  when :done            then puts "\n---"
+  when :approval_required
+    # Approval needed — handle via approve_async (see Human-in-the-loop section)
+  when :error           then warn "Error: #{event.payload[:error].message}"
+  end
+end
+puts result[:output]
+
+# Non-blocking streaming — returns Task immediately
+task = ResearchAgent.new.stream_async("Summarise AI news") do |event|
+  broadcast_to_websocket(event) if event.type == :token   # must return quickly
+end
+result = task.wait_result
+```
+
+#### Human-in-the-loop approval
+
+When a tool is configured with `requires_approval true` and no `:allow` policy is set,
+`invoke` suspends and returns `{ suspended: true, agent_invocation_id:, approval_request: }`.
+Resume via `approve` (synchronous) or `approve_async` (non-blocking, safe inside callbacks):
+
+```ruby
+agent = ResearchAgent.new
+agent.tool_approval_policy { :require_approval }
+
+result = agent.invoke("Run the search")
+if result[:suspended]
+  request = result[:approval_request]
+  puts "Tool: #{request.items.first.tool_name}"
+
+  # From top-level code — synchronous
+  final = agent.approve(
+    result[:agent_invocation_id],
+    approval_request_id: request.id,
+    approved: true
+  )
+  puts final[:output]
+end
+
+# Inside a stream callback — use approve_async to avoid EventLoop re-entry
+agent.stream_async("Run it") do |event|
+  if event.type == :approval_required
+    req = event.payload[:request]
+    approve_task = agent.approve_async(
+      req.agent_invocation_id,
+      approval_request_id: req.id,
+      approved: true
+    )
+    # approve_task resolves when the resumed invocation completes
+  end
+end
+```
+
+> **Important**: Approval state is stored in-process (`AgentInvocationRegistry`). It is **not**
+> persisted across process restarts and is **not** shared between pods or processes.
+
 ### Workflow — Stateful workflow with wait_state/send_event
 
 ```ruby runnable
@@ -201,20 +292,116 @@ final = app.send_event(state: state, event: :approve)
 puts "Approved: #{final.approved}"  # => true
 ```
 
-In EventLoop mode (`c.event_loop = true`), use `invoke_async + Task#map` to run an agent
-asynchronously inside a Workflow entry action.  The mapped Task returns a `WorkflowContext`,
-which `FSMSession` picks up via the standard `:action_completed` path:
+Start the Agent as an asynchronous activity of the active state, then
+map its lifecycle event to an application-defined Workflow event:
 
 ```ruby
-# EventLoop mode: workflow that runs an agent and captures the result.
-entry :translate, ->(ctx) {
-  TranslationAgent.new.invoke_async(ctx.query).map do |result|
-    ctx.merge(answer: result[:output])   # returns WorkflowContext
+class TranslationContext
+  include Phronomy::WorkflowContext
+
+  field :query
+  field :answer
+  field :error
+
+  def handle_fsm_event(event)
+    case event.type
+    when :translation_completed
+      self.answer = event.payload[:answer]
+    when :translation_failed
+      self.error = event.payload[:error]
+    end
+    false
   end
-}
-transition from: :translate, to: :done   # no on: needed
+end
+
+workflow = nil
+
+workflow = Phronomy::Workflow.define(TranslationContext) do
+  initial :translate
+
+  state :translate, action: ->(ctx) {
+    TranslationAgent.new.invoke_async(
+      ctx.query,
+      on_event: ->(event) {
+        case event.type
+        when :done
+          workflow.signal(
+            thread_id: ctx.thread_id,
+            event: :translation_completed,
+            payload: {answer: event.payload[:output]}
+          )
+        when :error, :timeout, :cancelled
+          workflow.signal(
+            thread_id: ctx.thread_id,
+            event: :translation_failed,
+            payload: {error: event.payload[:error]}
+          )
+        end
+      }
+    )
+    ctx
+  }
+
+  state :done
+  state :failed
+
+  transition from: :translate, on: :translation_completed, to: :done
+  transition from: :translate, on: :translation_failed, to: :failed
+end
+```
+
+The application owns payload interpretation, correlation, and field updates.
+Phronomy does not automatically copy Agent results into WorkflowContext.
+
+Transitions may define an `action:` callback in addition to a `guard:`:
+
+```ruby
+transition(
+  from: :review,
+  on: :approved,
+  to: :publish,
+  guard: ->(context, event) {
+    event.payload[:request_id] == context.request_id
+  },
+  action: ->(context, event) {
+    context.merge(approved_by: event.payload[:reviewer])
+  }
+)
 ```
 
+The callback order for a successful transition is:
+
+```text
+source exit callbacks
+-> selected transition action
+-> target entry callbacks
+```
+
+Transition actions may accept either `(context)` or `(context, event)`. A
+returned Workflow context replaces the current context before target entry
+callbacks run. Returning `nil` or another non-context value preserves the
+current context.
+
+Like entry actions, transition actions are synchronous Run-to-Completion
+callbacks. They may start asynchronous work and register a listener that later
+calls `Workflow#signal`, but they must return the context or `nil` immediately.
+Returning `Phronomy::Task` raises
+`Phronomy::InvalidAsyncTransitionActionError`; Phronomy does not implicitly
+await it.
+
+For a transition with `on:`, the two-argument action receives the external
+`Phronomy::Event`. For an automatic transition without `on:`, it receives the
+internal event:
+
+```text
+event.type    == :state_completed
+event.payload == nil
+```
+
+When several transitions have the same source and event, guards are evaluated
+in declaration order. The first matching transition is selected, and only that
+transition's action runs.
+
 ### Multi-Agent — Agent-as-Tool pattern
 
 Wrap sub-agents as `Agent::Context::Capability::Base` subclasses so the orchestrator LLM can call them on demand.
@@ -401,7 +588,7 @@ rescue Phronomy::LowConfidenceError => e
 end
 ```
 
-### Agent::Orchestrator — Parallel subagent dispatch
+### MultiAgent::Orchestrator — Parallel subagent dispatch
 
 > **Note:** `dispatch_parallel` and `fan_out` use plain Ruby threads. Use
 > `max_concurrency:` to cap the number of concurrent workers and `on_error:`
@@ -410,7 +597,7 @@ end
 > fan-outs consider additional rate-limiting at the application level.
 
 ```ruby
-class ResearchOrchestrator < Phronomy::Agent::Orchestrator
+class ResearchOrchestrator < Phronomy::MultiAgent::Orchestrator
   model "gpt-4o"
   instructions "Coordinate research tasks by dispatching to specialised agents."
 
@@ -425,7 +612,7 @@ result = ResearchOrchestrator.new.invoke("Research the latest AI news.")
 Programmatic parallel dispatch (no LLM loop):
 
 ```ruby
-class MyOrchestrator < Phronomy::Agent::Orchestrator
+class MyOrchestrator < Phronomy::MultiAgent::Orchestrator
   model "gpt-4o"
   instructions "Orchestrate."
 
@@ -530,6 +717,10 @@ end
 
 ### MCP Tool — External tool servers
 
+> **MCP 1.x required.** Phronomy targets `mcp ~> 1.0`. For supported JSON Schema
+> constructs, error semantics, and client lifecycle contracts, see
+> [`docs/mcp-client.md`](docs/mcp-client.md).
+
 ```ruby
 search_tool = Phronomy::Tools::Mcp.from_server(
   "stdio://./mcp-server",
@@ -567,7 +758,7 @@ puts result2[:output]   # => "Your name is Alice."
 Persist it however suits your application (in-memory hash, Redis, ActiveRecord, etc.).
 
 > **Note on `thread_id`**: `thread_id` is a correlation identifier used internally for
-> checkpoint/compaction context and EventLoop routing. It does **not** automatically persist or
+> EventLoop session routing and compaction context. It does **not** automatically persist or
 > restore conversation history — you must pass `messages:` explicitly on each turn as shown above.
 
 
@@ -581,14 +772,16 @@ Phronomy.configure do |c|
   c.before_completion               = nil   # optional; global hook lambda
   c.trace_pii                       = false # default; set to true only when trace data contains no PII
   c.logger                          = nil   # optional; any object responding to #warn (e.g. Rails.logger)
-  c.event_loop_stop_grace_seconds   = 5     # seconds to wait for sessions to drain on EventLoop#stop(drain: true)
+  c.event_loop_stop_grace_seconds   = 5     # seconds to wait for sessions to drain on shutdown
   c.runtime_backend                 = :thread   # :thread (default); :immediate (tests, synchronous); :fiber (experimental validation only); :cooperative (deprecated alias for :immediate)
-  c.strict_runtime_guards           = false          # when true, raises on invoke-inside-task
+  c.strict_runtime_guards           = false     # when true, raises SchedulerReentrancyError on invoke-inside-task
+  c.stream_callback_error_policy    = :report   # :report (default) preserves Agent result; :fail_task fails Task with StreamCallbackError
 end
 ```
 
 `c.logger` receives framework diagnostic messages (e.g. unreachable-state warnings from
-`Workflow.define`). When `nil` (default), messages are written to `$stderr` via `Kernel#warn`.
+`Workflow.define`, stream callback errors, EventLoop queue backlog warnings). When `nil`
+(default), messages are written to `$stderr` via `Kernel#warn`.
 
 > **Note**: When `trace_pii = false`, both the _input_ and the _output_ (LLM
 > responses and tool results) are replaced with `[REDACTED]` in trace spans.
@@ -605,6 +798,10 @@ Understanding when to use each prevents scheduler stalls and hidden deadlocks.
 | Top-level application code, Rails controller, background job | `agent.invoke(input)` — blocks the calling thread until done |
 | Workflow action / EventLoop callback | `agent.invoke_async(input).map { |r| ctx.merge(output: r[:output]) }` — returns a Task and resumes by state transition |
 | Top-level code that wants explicit async | `agent.invoke_async(input).wait_result` — blocks the calling thread until the Task completes |
+| Streaming from top-level code | `agent.stream(input) { |event| ... }` — blocks until done; callbacks run on the EventLoop thread |
+| Streaming non-blocking | `task = agent.stream_async(input) { |event| ... }` — returns Task immediately; callbacks run on the EventLoop thread |
+| Resume approval from top-level code | `agent.approve(id, approval_request_id: r_id, approved: true)` — synchronous; blocks until resumed |
+| Resume approval from an EventLoop callback | `agent.approve_async(id, approval_request_id: r_id, approved: true)` — returns Task; safe to call from a stream callback |
 
 ### Why this matters
 
@@ -700,8 +897,7 @@ class MyAgent < Phronomy::Agent::Base
   model "gpt-4o"
   max_output_tokens 4096   # override max_output_tokens from registry
   context_overhead  600    # extra reservation for system prompt + tools
-  invoke_timeout    30     # raise Phronomy::TimeoutError after 30 s (wait timeout, not cancellation)
-  max_parallel_tools 4     # cap concurrent tool executions (default: 10)
+  # LLM timeout/retry is configured on RubyLLM, not on the Agent class.
 end
 ```
 
@@ -727,7 +923,7 @@ Pass a `CancellationToken` to any agent via `config: { cancellation_token: token
 Cancellation is checked at multiple granular checkpoints: before the LLM call,
 after each streaming chunk, before each parallel
 tool-call batch, and after each `before_completion` hook. `CancellationError` is
-raised immediately and is never retried. No threads are force-killed — `ensure`
+raised immediately. Phronomy does not replay the complete Agent invocation. No threads are force-killed — `ensure`
 blocks always execute.
 
 > **Cooperative cancellation — not preemptive**
@@ -750,6 +946,38 @@ blocks always execute.
 > safety concerns. Ruby's GVL prevents fully preemptive cancellation without such
 > risky interruption.
 
+> **`timeout_after` vs `CancellationScope.deadline_in`**
+>
+> `CancellationToken.timeout_after(seconds)` uses lazy clock comparison: `cancelled?`
+> returns `true` once the deadline elapses, but `on_cancel` callbacks are **not**
+> fired. Bridges that rely on `on_cancel` — such as the `MCP::Cancellation` bridge
+> in `Phronomy::Tools::Mcp#execute` — will therefore **not** be triggered on expiry.
+>
+> When you need the cancellation to propagate into in-flight I/O (e.g. an MCP
+> `call_tool` request), use `CancellationScope` instead:
+>
+> ```ruby
+> scope = Phronomy::Concurrency::CancellationScope.new.deadline_in(30)
+> result = MyAgent.new.invoke("...", config: { cancellation_token: scope.token })
+> ```
+>
+> `CancellationScope#deadline_in` registers a timer in the Runtime timer queue,
+> which calls `cancel!` on expiry and fires all `on_cancel` callbacks — including
+> the MCP bridge.
+
+> **Transport timeout and retry ownership**
+>
+> Phronomy does not interpret `config[:llm_timeout]`, `config[:tool_timeout]`,
+> Agent `retry_policy`, or Tool `retry_on`. Configure LLM transport behavior on
+> RubyLLM (or another adapter) and configure Tool transport behavior on the Tool's
+> HTTP/DB/MCP client. This ensures the layer capable of safely aborting the I/O owns
+> the timeout and retry semantics.
+>
+> `InvocationContext#deadline` and `cancellation_token` remain available for a
+> caller-defined root-operation boundary. They provide cooperative cancellation
+> across the Phronomy execution tree; they do not replace provider-native socket,
+> request, statement, or session timeouts.
+>
 ```ruby
 token = Phronomy::Concurrency::CancellationToken.new
 

data/benchmark/bench_agent_invoke.rb

@@ -8,7 +8,7 @@
 #
 # Scenarios:
 #   1. Minimal agent (no tools, no knowledge) — baseline framework overhead.
-#   2. Tool-aware agent with max_parallel_tools=4 (4 stub tools per turn).
+#   2. Tool-aware agent with a registered stub Tool.
 #   3. Agent#stream setup latency (first-chunk time with stubbed stream).
 
 require "benchmark"
@@ -79,7 +79,6 @@ end
 bench_tool_class = Class.new(Phronomy::Agent::Base) do
   model "stub-model"
   tools BenchNullTool
-  max_parallel_tools 4
 
   define_method(:build_chat) { |*| BenchStubChat.new(BENCH_RESP) }
 end
@@ -97,7 +96,7 @@ Benchmark.bm(50) do |x|
     end
   end
 
-  x.report("Agent#invoke — 4 parallel stub tools, #{AGENT_INVOKE_ITERATIONS} iters") do
+  x.report("Agent#invoke — tool-aware, #{AGENT_INVOKE_ITERATIONS} iters") do
     AGENT_INVOKE_ITERATIONS.times do
       BENCH_AGENT_TOOLS.invoke("ping", thread_id: "bench-#{rand(1_000_000)}")
     end