phronomy 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd9fb679db0e4d4c582a82dad543ca0d93806878e0936404cd4255d2a48a741b
-  data.tar.gz: 511a6bfb90ec0524aafb201996bc251c9b1923a2d3ff4d1b389aa7d62f2d3395
+  metadata.gz: 821e5e60bc5eacd862e98cbf03b74ba1de640d923c783d29ec560b4e0523dafa
+  data.tar.gz: 515be391fa893cc679bcc348a5db5abddbb5d6714507f0adf3eae25a0d0caffd
 SHA512:
-  metadata.gz: 9efc33585c40e3d5b4559121cd5654c9687608ff05ab684818e27ac5d4672264352fb68fbf4efa6436ed8666a0b194acfdcea7511fce67a5eda50e690cd80803
-  data.tar.gz: 0142742c7875411622ad37ae2918164130bd84fe237da2e100b69578f67380a08c61ae6ca77cfdcac5892ea7bd56140c39b374b8d0543d11cd359bda587f12df
+  metadata.gz: 744f401fb376638feea54c7639653ea92fcf1cde3043f0de656f1e16e2f14fbac15ae2c396d939e4f5810446acc4d65e29d4c95fe1049e02d759625b0b7c7f19
+  data.tar.gz: 6835730faae5f27c80c0a2157f7e69e38f23c6b41e1cdbfa169532b786b981934d70a224bf793922e55fc0d7be4894d9ca9c984191bbf8e014d1aee158664ed9

data/CHANGELOG.md

@@ -7,6 +7,96 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [Unreleased]
+
+---
+
+## [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

@@ -60,11 +60,13 @@ It provides composable building blocks — Workflows, Agents, Tools, Filters, an
 | **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 |
+| **`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.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**
 
@@ -530,6 +532,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",
@@ -750,6 +756,49 @@ 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.
+
+> **`config[:tool_timeout]` / `config[:llm_timeout]` — caller protection, not
+> worker termination**
+>
+> 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.
+>
+> **Timeout behaviour depends on when the deadline fires:**
+>
+> | 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/docs/mcp-client.md

@@ -0,0 +1,75 @@
+# MCP client support
+
+Phronomy supports the official `mcp` Ruby SDK **1.x**. MCP SDK 0.x is not supported.
+
+## Transports
+
+`Phronomy::Tools::Mcp.from_server` supports:
+
+- `stdio://...`
+- `http://...`
+- `https://...`
+
+HTTP and SSE support are standard dependencies of Phronomy through `faraday` and
+`event_stream_parser`.
+
+## Input-schema subset
+
+Phronomy intentionally supports a strict subset of JSON Schema 2020-12 for MCP
+Tool inputs.
+
+Supported root keywords:
+
+- `$schema`
+- `type` (`object` only)
+- `properties`
+- `required`
+- `title`
+- `description`
+- `additionalProperties` when omitted or `false`
+
+Supported property types:
+
+- `string`
+- `integer`
+- `number`
+- `boolean`
+
+Supported property keywords:
+
+- `type`
+- `description`
+- `enum`
+- `title`
+
+The following validation keywords are accepted but ignored with a warning:
+
+- `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`, `multipleOf`
+- `minLength`, `maxLength`, `pattern`, `format`, `default`, `examples`
+
+Unknown keywords, structural composition (`oneOf`, `anyOf`, `allOf`, `$ref`,
+conditionals), arrays, nested objects, and nullable type arrays fail fast with
+`Phronomy::ToolError` rather than silently changing the Tool contract.
+
+When `additionalProperties` is omitted, the remote schema is accepted, but
+Phronomy still exposes and accepts only names declared in `properties`.
+
+`outputSchema` is detected and reported with a warning, but is not validated in
+this phase.
+
+## Errors and cancellation
+
+- JSON-RPC errors raised by the SDK are converted to `Phronomy::ToolError`.
+- MCP Tool results with `isError: true` are returned to the model as Tool error
+  text so the model can correct its arguments.
+- An expired HTTP session is reconnected for future calls. The failed Tool call
+  is not replayed because Tool side effects are not assumed to be idempotent.
+- Cancellation invalidates the current client and transport. The next call creates
+  a new connection, preventing an abandoned SDK worker from sharing the old stdio
+  stream with a new request.
+
+Calls, reconnects, and explicit `close` operations on a Tool instance are
+serialized. `close` synchronously closes the current client and permits a later
+call to reconnect. A transport detached by cancellation is owned by the bounded
+MCP cleanup pool and is drained during Runtime shutdown; `close` does not wait
+for an older detached transport.

data/gemfiles/mcp_1_0.gemfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec path: ".."
+
+gem "mcp", "= 1.0.0"
+gem "rspec", "~> 3.0"
+gem "webrick", "~> 1.8"

data/lib/phronomy/agent/base.rb

@@ -546,15 +546,9 @@ module Phronomy
         if invocation_context
           thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
         end
-        bp = Phronomy.configuration.backpressure
-        on_full = (bp == :raise) ? :reject : (bp || :wait)
-        bp_timeout = Phronomy.configuration.backpressure_timeout
         result_task = Phronomy::Task.deferred(name: "agent-#{(self.class.name || "anonymous").downcase}-async")
-        gate = Phronomy::Runtime.instance.gate(:agent)
-        gate.acquire(on_full: on_full, timeout: bp_timeout) do
-          _start_invoke_attempt(result_task, input, messages: messages, thread_id: thread_id, config: config, attempt: 0)
-          return result_task
-        end
+        _start_invoke_attempt(result_task, input, messages: messages, thread_id: thread_id, config: config, attempt: 0)
+        result_task
       end
 
       # Streaming version of #invoke. Yields {Phronomy::Agent::StreamEvent} objects
@@ -843,16 +837,17 @@ module Phronomy
         effective_config = thread_id ? config.merge(thread_id: thread_id) : config
         # Fail fast when the token is already cancelled before any LLM call.
         check_cancellation!(effective_config, "invocation cancelled")
-        # Ensure EventLoop is running. start is idempotent when already alive.
-        Phronomy::EventLoop.instance.start
+        runtime = Phronomy::Runtime.instance
+        event_loop = runtime.event_loop
         trace("agent.invoke", input: input, **_build_caller_meta(effective_config)) do |_span|
           session = Agent::InvocationSession.build(
             agent: self,
             input: input,
             messages: messages,
-            config: effective_config
+            config: effective_config,
+            runtime: runtime
           )
-          completion_queue = Phronomy::EventLoop.instance.register(session)
+          completion_queue = event_loop.register(session)
           ctx = completion_queue.pop
           raise ctx if ctx.is_a?(Exception)
           result = _extract_invoke_result(ctx, session.id)
@@ -868,15 +863,17 @@ module Phronomy
       def _start_invoke_attempt(result_task, input, messages:, thread_id:, config:, attempt:)
         effective_config = thread_id ? config.merge(thread_id: thread_id) : config
         check_cancellation!(effective_config, "invocation cancelled")
-        Phronomy::EventLoop.instance.start
+        runtime = Phronomy::Runtime.instance
+        event_loop = runtime.event_loop
         session = Agent::InvocationSession.build(
           agent: self,
           input: input,
           messages: messages,
-          config: effective_config
+          config: effective_config,
+          runtime: runtime
         )
         source_task = Phronomy::Task.deferred(name: "#{result_task.name}-attempt-#{attempt}")
-        Phronomy::EventLoop.instance.register(session, completion: source_task)
+        event_loop.register(session, completion: source_task)
         session_id = session.id
         policy = self.class._retry_policy
 
@@ -956,13 +953,16 @@ module Phronomy
       # Builds and runs a resume FSMSession for the given context and event.
       # @api private
       def _resume_fsm(ctx, event)
+        runtime = Phronomy::Runtime.instance
+        event_loop = runtime.event_loop
         session = Agent::InvocationSession.build_for_resume(
           agent: self,
           context: ctx,
           resume_event: event,
-          resume_phase: :awaiting_approval
+          resume_phase: :awaiting_approval,
+          runtime: runtime
         )
-        completion_queue = Phronomy::EventLoop.instance.register(session)
+        completion_queue = event_loop.register(session)
         resumed_ctx = completion_queue.pop
         raise resumed_ctx if resumed_ctx.is_a?(Exception)
         _extract_invoke_result(resumed_ctx, session.id)

data/lib/phronomy/agent/context/capability/base.rb

@@ -290,6 +290,12 @@ module Phronomy
                   case param_type
                   when "integer" then v.is_a?(Integer) ? v : Integer(v.to_s)
                   when "number" then v.is_a?(Numeric) ? v : Float(v.to_s)
+                  when "boolean"
+                    unless v == true || v == false
+                      raise ArgumentError,
+                        "boolean enum values must be true or false (got: #{v.inspect})"
+                    end
+                    v
                   else v.to_s
                   end
                 end

data/lib/phronomy/agent/invocation_session.rb

@@ -19,7 +19,7 @@ module Phronomy
     #     messages: [],
     #     config:   { thread_id: "t-1" }
     #   )
-    #   completion_queue = Phronomy::EventLoop.instance.register(session)
+    #   completion_queue = Phronomy::Runtime.instance.event_loop.register(session)
     #   ctx = completion_queue.pop
     #
     # == Streaming mode
@@ -56,7 +56,8 @@ module Phronomy
       # @param on_event [Proc, nil] stream event callback (stream mode only)
       # @return [Phronomy::FSMSession]
       # @api private
-      def self.build(agent:, input:, messages:, config:, mode: :invoke, on_event: nil)
+      def self.build(agent:, input:, messages:, config:, mode: :invoke, on_event: nil,
+        runtime: Phronomy::Runtime.instance)
         ctx = Agent::InvocationContext.new(
           agent: agent,
           input: input,
@@ -95,7 +96,9 @@ module Phronomy
             approve: [{from: :awaiting_approval, to: :executing_tool, guard: nil}],
             reject: [{from: :awaiting_approval, to: :blocked, guard: nil}]
           },
-          recursion_limit: fsm_recursion_limit
+          recursion_limit: fsm_recursion_limit,
+          event_loop: runtime.event_loop,
+          timer_queue_provider: -> { runtime.timer_queue }
         )
       end
 
@@ -108,7 +111,8 @@ module Phronomy
       # @param resume_phase [Symbol] the wait state to resume from
       # @return [Phronomy::FSMSession]
       # @api private
-      def self.build_for_resume(agent:, context:, resume_event:, resume_phase:)
+      def self.build_for_resume(agent:, context:, resume_event:, resume_phase:,
+        runtime: Phronomy::Runtime.instance)
         actions = build_entry_actions(agent)
         phase_machine = Agent::PhaseMachineBuilder.new(entry_actions: actions).build
 
@@ -129,6 +133,8 @@ module Phronomy
             reject: [{from: :awaiting_approval, to: :blocked, guard: nil}]
           },
           recursion_limit: fsm_recursion_limit,
+          event_loop: runtime.event_loop,
+          timer_queue_provider: -> { runtime.timer_queue },
           resume_event: resume_event,
           resume_phase: resume_phase
         )

data/lib/phronomy/agent/phase_machine_builder.rb

@@ -115,6 +115,7 @@ module Phronomy
           # FSM session id — set by FSMSession so async task spawns know the
           # target_id for EventLoop events.
           attr_accessor :session_id
+          attr_accessor :event_loop, :timer_queue_provider
 
           def initialize
             super
@@ -155,10 +156,10 @@ module Phronomy
         machine.async_pending = true
         session_id = machine.session_id
         if timeout_secs
-          Phronomy::Runtime.instance.timer_queue.schedule(seconds: timeout_secs) do
+          machine.timer_queue_provider.call.schedule(seconds: timeout_secs) do
             next if result.done?
 
-            Phronomy::EventLoop.instance.post(
+            machine.event_loop.post(
               Phronomy::Event.new(
                 type: :error,
                 target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID,
@@ -171,7 +172,7 @@ module Phronomy
         end
         result.on_complete do |task_result, error|
           if error
-            Phronomy::EventLoop.instance.post(
+            machine.event_loop.post(
               Phronomy::Event.new(type: :error, target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID, payload: {session_id: session_id, result: error})
             )
             next
@@ -181,7 +182,7 @@ module Phronomy
           else
             Phronomy::Event.new(type: :state_completed, target_id: session_id, payload: nil)
           end
-          Phronomy::EventLoop.instance.post(ev)
+          machine.event_loop.post(ev)
         end
       end
     end

data/lib/phronomy/configuration.rb

@@ -86,20 +86,6 @@ module Phronomy
     #   Phronomy.configure { |c| c.llm_adapter = MyAsyncLLMAdapter.new }
     attr_accessor :llm_adapter
 
-    # Default backpressure strategy for {BlockingAdapterPool#submit} when the
-    # queue is full.  One of +:wait+ (block until a slot is available),
-    # +:raise+ (raise {Phronomy::BackpressureError}), or +:timeout+ (raise
-    # {Phronomy::TimeoutError} after +backpressure_timeout+ seconds).
-    # @return [:wait, :raise, :timeout]
-    attr_accessor :backpressure
-
-    # Seconds to wait before raising {Phronomy::TimeoutError} when
-    # +backpressure+ is +:timeout+.
-    # @return [Numeric, nil]
-    attr_accessor :backpressure_timeout
-
-    # Warn when an event spends longer than this many seconds waiting in the
-    # EventLoop queue before being dispatched (starvation detection).
     # Set to +nil+ to disable the warning.
     # @return [Numeric, nil]
     attr_accessor :event_loop_starvation_threshold_seconds
@@ -120,37 +106,25 @@ module Phronomy
     # @return [Float, nil]
     attr_accessor :blocking_detect_threshold_ms
 
-    # Maximum number of concurrent agent tasks (invoke_async calls in-flight).
-    # nil = unlimited (default).  When at capacity, behaviour is controlled by
-    # +backpressure+ (:wait, :raise/:reject, :timeout).
-    # @return [Integer, nil]
-    attr_accessor :max_concurrent_agent_tasks
-
-    # Maximum number of concurrent tool tasks (parallel tool calls in-flight).
-    # nil = unlimited (default).
-    # @return [Integer, nil]
-    attr_accessor :max_concurrent_tool_tasks
-
-    # Maximum number of concurrent workflow tasks.
-    # nil = unlimited (default).
-    # @return [Integer, nil]
-    attr_accessor :max_concurrent_workflow_tasks
-
-    # Maximum number of concurrent LLM calls in-flight.
-    # nil = unlimited (default).
-    # @return [Integer, nil]
-    attr_accessor :max_concurrent_llm_calls
-
     # Upper bound on the number of streaming token chunks that may be buffered
     # in the {AsyncQueue} used by {Agent#stream} before the LLM producer is
     # throttled.  When nil (default), the queue is unbounded.
     # @return [Integer, nil]
     attr_accessor :stream_queue_max_size
 
-    # Maximum number of concurrent vector-store searches in-flight.
-    # nil = unlimited (default).
-    # @return [Integer, nil]
-    attr_accessor :max_concurrent_vector_searches
+    # Number of OS worker threads in the default {BlockingAdapterPool}.
+    # All LLM calls, MCP tool calls, and other blocking I/O share this pool.
+    # Increase for higher LLM/tool throughput; decrease to limit
+    # concurrency (e.g. to stay within a provider's rate limit).
+    # Default: 10.
+    # @return [Integer]
+    attr_accessor :blocking_io_pool_size
+
+    # Maximum number of operations that may wait in the {BlockingAdapterPool}
+    # queue before {Phronomy::BackpressureError} is raised (on_full: :raise) or
+    # the caller blocks (on_full: :wait, the default). Default: 100.
+    # @return [Integer]
+    attr_accessor :blocking_io_queue_size
 
     # Scheduler starvation threshold (milliseconds).
     # When a task waits more than this many milliseconds after calling
@@ -195,18 +169,13 @@ module Phronomy
       @parallel_tool_execution = false
       @event_loop_stop_grace_seconds = 5
       @llm_adapter = Phronomy::LLMAdapter::RubyLLM.new
-      @backpressure = :wait
-      @backpressure_timeout = nil
       @event_loop_starvation_threshold_seconds = nil
       @event_loop_dispatch_threshold_seconds = nil
       @scheduler_debug = false
       @blocking_detect_threshold_ms = nil
-      @max_concurrent_agent_tasks = nil
-      @max_concurrent_tool_tasks = nil
-      @max_concurrent_workflow_tasks = nil
-      @max_concurrent_llm_calls = nil
       @stream_queue_max_size = nil
-      @max_concurrent_vector_searches = nil
+      @blocking_io_pool_size = 10
+      @blocking_io_queue_size = 100
       @starvation_threshold_ms = 50
       @runtime_backend = :thread
       @strict_runtime_guards = false

data/lib/phronomy/diagnostics.rb

@@ -52,7 +52,7 @@ module Phronomy
     # @return [void]
     # @api private
     def self.assert_not_in_event_loop!
-      return unless Phronomy::EventLoop.current?
+      return unless Phronomy::Runtime.in_event_loop_context?
 
       raise Phronomy::SchedulerReentrancyError,
         "Blocking invoke called from inside an EventLoop action. " \