phronomy 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 821e5e60bc5eacd862e98cbf03b74ba1de640d923c783d29ec560b4e0523dafa
-  data.tar.gz: 515be391fa893cc679bcc348a5db5abddbb5d6714507f0adf3eae25a0d0caffd
+  metadata.gz: b0ea2e317999f3202e06d5afac0b46509fa22a813531919447040d1e048a087f
+  data.tar.gz: ae5740df9899b7463b35b54b885948ca1e0e42e01b8b85b1a93fd6437022c90b
 SHA512:
-  metadata.gz: 744f401fb376638feea54c7639653ea92fcf1cde3043f0de656f1e16e2f14fbac15ae2c396d939e4f5810446acc4d65e29d4c95fe1049e02d759625b0b7c7f19
-  data.tar.gz: 6835730faae5f27c80c0a2157f7e69e38f23c6b41e1cdbfa169532b786b981934d70a224bf793922e55fc0d7be4894d9ca9c984191bbf8e014d1aee158664ed9
+  metadata.gz: 123b0998a7a299f97ce981a3561c68990c41e05decb534b4c4664e441abd6cf368e04ecf6cea61df6a1ea2c4016850b093e0c208aa034fc02b1fa498e0078263
+  data.tar.gz: f1ba3ee6163b1a746bd99f00241daf286ac5eb3d8d1e30f7caa739de1de5dd900f3b19b90a063c4a9f19f494a1e9ac1dca59b4d32ade41deabe71f849803ac62

data/CHANGELOG.md

@@ -9,6 +9,71 @@ 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

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,21 +48,22 @@ 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 |
 | **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::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 |
@@ -75,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
@@ -125,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
 
@@ -166,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
@@ -203,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.
@@ -403,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:`
@@ -412,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."
 
@@ -427,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."
 
@@ -573,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.
 
 
@@ -587,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.
@@ -611,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
 
@@ -706,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
 ```
 
@@ -733,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**
@@ -775,30 +965,19 @@ blocks always execute.
 > which calls `cancel!` on expiry and fires all `on_cancel` callbacks — including
 > the MCP bridge.
 
-> **`config[:tool_timeout]` / `config[:llm_timeout]` — caller protection, not
-> worker termination**
+> **Transport timeout and retry ownership**
 >
-> These keys set a submit-time deadline in `BlockingAdapterPool`. The timer is
-> armed at submit time (including queue wait) and calls `fire_timeout!` when the
-> deadline expires. The worker thread is never forcibly interrupted.
+> 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.
 >
-> **Timeout behaviour depends on when the deadline fires:**
+> `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.
 >
-> | Situation | `TimeoutError`? | `abandoned?` | `abandoned_count` |
-> |---|---|---|---|
-> | Deadline fires while worker is executing | ✅ via `on_complete` | `true` | +1 |
-> | Deadline fires while op is still queued | ✅ via `on_complete` | `false` | unchanged |
-> | `blocking_wait(timeout:)` expires | ✅ to that waiter only | unchanged | unchanged |
-> | `CancellationToken` cancelled | `CancellationError` | — | — |
-> | Streaming path | not guaranteed (separate fix needed) | — | — |
->
-> `blocking_wait(timeout:)` is a **waiter-local** deadline — the operation remains
-> unsettled and other waiters or `on_complete` callbacks will still receive the
-> eventual result (unless a submit-time deadline also fires).
->
-> Size `blocking_io_pool_size` to account for the worst-case number of
-> concurrently abandoned workers that may accumulate before the pool is saturated.
-
 ```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

data/docs/decisions/004-invoke-timeout-is-not-cancellation.md

@@ -2,74 +2,21 @@
 
 ## Status
 
-Accepted
+Superseded by [ADR-011](011-delegate-transport-policy-to-adapters.md).
 
-## Context
+## Historical decision
 
-`Agent::Base` exposes `invoke_timeout N` as a class-level DSL. When an invocation
-exceeds the timeout, `Phronomy::TimeoutError` is raised to the caller.
+Phronomy previously exposed `Agent::Base.invoke_timeout` as a class-level wait
+boundary. The initial implementation did not stop background work; a later
+implementation attached a cancellation scope to the complete Agent invocation.
 
-The question is: should the timeout also stop the agent's background work?
-
-Ruby's `Timeout.timeout` / `Thread#kill` can interrupt a running thread, but
-doing so is unsafe: it can leave mutexes locked, database connections in a broken
-state, and external API calls mid-flight without cleanup. `Thread#raise` has the
-same hazards because it can interrupt anywhere inside a `rescue`/`ensure` block.
-
-Cooperative cancellation (checking a shared flag periodically) is safe but
-requires every tool, every LLM call, and every framework-internal loop to
-participate — a significant API surface change.
-
-## Decision
-
-`invoke_timeout` is a **wait timeout only**. When the deadline is reached:
-
-- `TimeoutError` is raised in the calling thread.
-- The agent's background thread continues running until it either completes
-  normally or is garbage-collected when the process ends.
-- No cancellation signal is sent to the agent.
-
-This is explicitly documented in the README and in the DSL source.
-
-A proper cooperative cancellation mechanism is tracked in Issue #216
-(`CancellationToken`), which is a separate feature requiring agent, tool, and
-transport layer participation.
-
-## Consequences
-
-**Positive:**
-- No risk of leaving shared resources (DB connections, mutexes, sockets) in a
-  broken state due to forced thread interruption.
-- Implementation is simple: `Timeout.timeout` on the calling side only.
-- The contract is explicit and predictable.
-
-**Negative / Tradeoffs:**
-- Background threads may continue consuming resources (LLM API quota, etc.)
-  after the caller has given up.
-- Users who expect "cancel" semantics from a timeout will be surprised.
-- Proper cancellation requires the `CancellationToken` feature (#216), which
-  has not yet been implemented.
-
-## Extension: PendingOperation#await cooperative cancellation semantics
-
-`BlockingAdapterPool::PendingOperation#await` also supports both `timeout:` and
-`cancellation_token:` parameters. The same non-preemptive rule applies here,
-consistent with ADR-010 (cooperative-first, non-preemptive concurrency model):
-
-1. **No forcible thread termination.** When a `cancellation_token` is cancelled,
-   `CancellationError` is raised to the `await` caller; when the timeout fires,
-   `TimeoutError` is raised instead. In both cases, the underlying worker thread
-   is **not** killed. The worker runs its block to natural completion.
-2. **Cooperative, not preemptive.** Cancellation takes effect only at `await`
-   call sites or at explicit `token.check!` checkpoints inside the submitted
-   block. Code that ignores the token will not be interrupted.
-3. **Timeout scope.** `timeout:` at `await` time is measured from the moment
-   `await` is called. If both submit-time and await-time timeouts are provided,
-   the earlier deadline wins.
-4. **Error propagation.** `CancellationError` (or `TimeoutError`) is raised to
-   the `await` caller; the submitter is responsible for handling it.
-
-These semantics are identical in spirit to the `invoke_timeout` decision above:
-the framework exposes a *wait* boundary, not a hard-kill boundary. Safe resource
-cleanup is the caller's responsibility.
+The API has been removed. An Agent class no longer owns a default invocation
+timeout. Applications that need a deadline for a particular root operation pass
+an `InvocationContext` with `deadline:` or `cancellation_token:`. Those values are
+coordination context supplied by the caller, not an implicit Agent execution
+policy.
 
+LLM transport timeout belongs to RubyLLM or another configured LLM adapter.
+Tool transport timeout belongs to the Tool implementation or its underlying
+client. Phronomy retains generic deadline and cancellation primitives for the
+execution tree it coordinates.