phronomy 0.5.3 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49b20f3defaed56477f9f1ee375a450d26a770d004c052754cc5c045746587cc
-  data.tar.gz: 1d2fe811e467c7d04208b82cc9d9ca5fca9b17d0bf6061aa952a2fb862c23a53
+  metadata.gz: 81df7b877b08caffbfdafb9ab1f1c186739a04ef643a14e7b457be805c8b2b9d
+  data.tar.gz: c0fd0ffad64df476c21e0205926df15589c0e654fed9675a6e8aef3589636f1c
 SHA512:
-  metadata.gz: 763cf25297e0c8799ad76bcd362ecb5f1899a9ccd0d90791e119d2d0946c59f7c076f7a00d92e01e64735e90b45d7e1aa5462e41efceee9147daf45ac214551f
-  data.tar.gz: 3a30e9198008dd9e4e512c374324b4c1cfda40c2a41762ff160f90ffa8ac98c0669f700d810e899fa661bd68af3a14db0145a00afc4d0e97d560d7de27989db0
+  metadata.gz: cb22a0d7f3edba46a46e9614f4cdad1641941164a641e17c1b3aa24ed07a3d7fb88b408304f1e9c5eaceac02ef8a1fa8503cfb0cffac3ae86b1dd9786756f5ac
+  data.tar.gz: 4be7f67215d0b3b8381508f9ccf062fbfc8f41bb7a8a76299e2642634e78421c8ad5fcc551170db4e739c3db7e1cb8fd69ffad6982f50cdba8375f2237aa5ce9

data/CHANGELOG.md

@@ -7,6 +7,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [Unreleased]
+
+### Removed
+
+- **`Phronomy::Guardrail::Builtin` module removed**: `PromptInjectionDetector`
+  and `PIIPatternDetector` are opt-in pattern-matching helpers that encode
+  application-level policy decisions (which phrases to block, which PII
+  categories to detect, which languages to support). Shipping them as gem
+  defaults was misleading — their correct home is inside each application that
+  needs them. Reference implementations are now provided in example 06 of
+  `phronomy-examples`. Extend `Phronomy::Guardrail::InputGuardrail` directly to
+  create equivalent guardrails in your application.
+
+---
+
+## [0.5.4] - 2026-05-20
+
+### New Features
+
+- **VectorStore embedding dimension validation** (#98): All three vector store
+  implementations (`InMemory`, `RedisSearch`, `Pgvector`) now validate that every
+  embedding passed to `add` and `search` matches the expected dimension.
+  Dimension is inferred automatically from the first `add` call; alternatively
+  it can be set explicitly via `initialize(dimension: N)`. A mismatch raises
+  `ArgumentError` with a descriptive message. The `search` method never
+  establishes the dimension — it only validates when a dimension is already
+  known. `clear` retains the established dimension (schema property).
+
+- **`dispatch_parallel` / `fan_out` concurrency controls** (#99): Two new
+  keyword arguments are now accepted by both methods.
+  - `max_concurrency: nil` (default) or a positive `Integer` — caps the number
+    of worker threads. `nil` means one thread per task (previous behaviour).
+  - `on_error: :raise` (default) or `:skip` — controls failure handling.
+    `:raise` runs all tasks to completion then re-raises the first error in
+    input order (fail-last, not fail-fast). `:skip` fills failed slots with
+    `nil` and never raises.
+  The underlying implementation uses a `Queue`-based bounded worker pool
+  (`bounded_map`) for predictable resource usage.
+
+---
+
 ## [0.5.3] - 2026-05-20
 
 ### Bug Fixes

data/README.md

@@ -12,6 +12,8 @@ It provides composable building blocks — Workflows, Agents, Tools, Guardrails,
 | Feature | Stability |
 |---|---|
 | **Workflow** — Stateful, branching workflows with wait_state/send_event | Stable |
+| **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#run_as_child` (child-FSM pattern for Workflow integration), parallel tool dispatch via `ParallelToolChat` | Experimental |
 | **Workflow Parallel Node** — Concurrent branches via application-level threads | Beta |
 | **Agent** — ReAct-style tool-calling agents with guardrails and conversation history | Stable |
 | **Before-Completion Hook** — Three-tier LLM parameter injection | Stable |
@@ -22,7 +24,7 @@ It provides composable building blocks — Workflows, Agents, Tools, Guardrails,
 | **Agent::Orchestrator** — Parallel subagent dispatch, fan-out, and `subagent` DSL | Beta |
 | **Agent::TeamCoordinator** — Agent teams pattern: LLM coordinator + stateful worker pool with task queue (worker-local message history per run) | Beta |
 | **Agent::SharedState** — Shared state pattern: peer agents collaborate via a shared KnowledgeStore; `member` DSL with per-agent instructions and `coordination` team protocol | Experimental |
-| **Guardrails** — Input/output validation; built-in PII and prompt-injection detectors | Beta |
+| **Guardrails** — Input/output validation with custom `InputGuardrail`/`OutputGuardrail` | Beta |
 | **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 |
@@ -83,11 +85,11 @@ app = Phronomy::Workflow.define(ReviewContext) do
   state     :review,   action: ->(s) { s.merge(feedback: Reviewer.call(s.draft)) }
   wait_state :awaiting_approval           # halts here for human decision
   state     :finalize, action: ->(s) { s.merge(approved: true) }
-  after :write,    to: :review
-  after :review,   to: :awaiting_approval
-  after :finalize, to: :__finish__
-  event :approve, from: :awaiting_approval, to: :finalize
-  event :reject,  from: :awaiting_approval, to: :write
+  transition from: :write,              to: :review
+  transition from: :review,             to: :awaiting_approval
+  transition from: :finalize,           to: :__finish__
+  transition from: :awaiting_approval,  on: :approve, to: :finalize
+  transition from: :awaiting_approval,  on: :reject,  to: :write
 end
 
 # First run — halts at :awaiting_approval
@@ -146,16 +148,6 @@ agent = ResearchAgent.new
 agent.add_input_guardrail(NoSensitiveDataGuardrail.new)
 ```
 
-### Built-in Guardrails — PII and prompt injection detection
-
-```ruby
-# Detect SSNs, credit cards, emails, and phone numbers
-agent.add_input_guardrail(Phronomy::Guardrail::Builtin::PIIPatternDetector.new)
-
-# Block common prompt-injection attempts
-agent.add_input_guardrail(Phronomy::Guardrail::Builtin::PromptInjectionDetector.new)
-```
-
 ### Knowledge/RAG — Context injection and vector retrieval
 
 ```ruby
@@ -271,10 +263,11 @@ end
 
 ### Agent::Orchestrator — Parallel subagent dispatch
 
-> **Note:** `dispatch_parallel` and `fan_out` use plain Ruby threads and are
-> intended for small-scale fan-out (a handful of subagents). For large-scale
-> parallel dispatch, manage concurrency (thread pools, rate limiting) at the
-> application level.
+> **Note:** `dispatch_parallel` and `fan_out` use plain Ruby threads. Use
+> `max_concurrency:` to cap the number of concurrent workers and `on_error:`
+> to control failure handling (`:raise` re-raises the first error after all
+> tasks complete; `:skip` fills failed slots with `nil`). For very large
+> fan-outs consider additional rate-limiting at the application level.
 
 ```ruby
 class ResearchOrchestrator < Phronomy::Agent::Orchestrator
@@ -297,16 +290,22 @@ class MyOrchestrator < Phronomy::Agent::Orchestrator
   instructions "Orchestrate."
 
   def run(query)
-    # Heterogeneous agents in parallel
+    # Heterogeneous agents in parallel (cap at 4 threads; skip failures)
     results = dispatch_parallel(
       {agent: SearchAgent,   input: "topic A"},
-      {agent: AnalysisAgent, input: query}
+      {agent: AnalysisAgent, input: query},
+      max_concurrency: 4,
+      on_error: :skip
     )
 
     # Fan-out — same agent, multiple inputs
-    translations = fan_out(agent: TranslationAgent, inputs: %w[Hello World])
+    translations = fan_out(
+      agent: TranslationAgent,
+      inputs: %w[Hello World],
+      max_concurrency: 2
+    )
 
-    results.map { |r| r[:output] }.join("\n")
+    results.compact.map { |r| r[:output] }.join("\n")
   end
 end
 ```
@@ -333,7 +332,7 @@ app = Phronomy::Workflow.define(EnrichContext) do
     threads.each { |t| t.join(10) }  # 10-second timeout
     s.merge(summary: results[:summary], tags: Array(results[:tags]))
   end
-  after :enrich, to: :__finish__
+  transition from: :enrich, to: :__finish__
 end
 
 state = app.invoke({}, config: { thread_id: "t1" })

data/lib/phronomy/agent/base.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "digest"
+require "securerandom"
 require_relative "concerns/retryable"
 require_relative "concerns/guardrailable"
 require_relative "concerns/before_completion"
@@ -382,7 +383,82 @@ module Phronomy
       #   end
       #   puts result[:output]
       def invoke(input, messages: [], thread_id: nil, config: {})
-        _invoke_impl(input, messages: messages, thread_id: thread_id, config: config)
+        if Phronomy.configuration.event_loop
+          # Protect against blocking the EventLoop thread itself.
+          if Thread.current[:phronomy_event_loop_thread]
+            raise Phronomy::Error,
+              "Cannot call Agent#invoke (EventLoop mode) from within an EventLoop " \
+              "entry action. Use agent.run_as_child(input, ctx: ctx) instead."
+          end
+
+          fsm = Agent::FSM.new(
+            agent: self,
+            input: input,
+            messages: messages,
+            thread_id: thread_id || SecureRandom.uuid,
+            config: config
+          )
+          completion_queue = Phronomy::EventLoop.instance.register(fsm)
+          result = completion_queue.pop
+          raise result if result.is_a?(Exception)
+          result
+        else
+          _invoke_impl(input, messages: messages, thread_id: thread_id, config: config)
+        end
+      end
+
+      # Registers this agent as a child {AgentFSM} inside the given Workflow context.
+      #
+      # Use this method from a Workflow entry action (running on the EventLoop thread)
+      # instead of {#invoke}, which would raise a deadlock error because +invoke+ blocks
+      # on a +Thread::Queue+ when EventLoop mode is active.
+      #
+      # The agent runs asynchronously in a background IO thread.  When it finishes, the
+      # parent {FSMSession} receives a +:child_completed+ event whose payload is the
+      # result hash +{ output:, messages:, usage: }+.  Declare an +on: :child_completed+
+      # transition in your Workflow to advance to the next state.
+      #
+      # An optional block may be provided to write the result back into the parent
+      # WorkflowContext <b>before</b> the +:child_completed+ event is dispatched.
+      # +Thread::Queue+ provides the happens-before guarantee \u2014 no Mutex is needed.
+      #
+      # @example Without block (result available only as event payload)
+      #   entry :run_agent, ->(ctx) { MyAgent.new.run_as_child(ctx.query, ctx: ctx) }
+      #   transition from: :run_agent, on: :child_completed, to: :process_result
+      #
+      # @example With block (writes result into context)
+      #   entry :run_agent, ->(ctx) {
+      #     MyAgent.new.run_as_child(ctx.query, ctx: ctx) { |r| ctx.answer = r[:output] }
+      #   }
+      #   transition from: :run_agent, on: :child_completed, to: :process_result
+      #
+      # @param input     [String, Hash]  user input passed to the agent
+      # @param ctx       [Object]        a WorkflowContext that responds to +#thread_id+
+      # @param messages  [Array]         prior conversation history
+      # @param config    [Hash]          invocation config (forwarded to +_invoke_impl+)
+      # @yield [Hash]  result hash +{ output:, messages:, usage: }+ — called from the
+      #                agent IO thread before +:child_completed+ is posted
+      # @return [nil]  the caller must not wait on any return value;
+      #                the result arrives as a +:child_completed+ event
+      # @raise [Phronomy::Error] when EventLoop mode is not enabled
+      def run_as_child(input, ctx:, messages: [], config: {}, &result_writer)
+        unless Phronomy.configuration.event_loop
+          raise Phronomy::Error,
+            "run_as_child requires EventLoop mode. " \
+            "Enable with: Phronomy.configure { |c| c.event_loop = true }"
+        end
+
+        fsm = Agent::FSM.new(
+          agent: self,
+          input: input,
+          messages: messages,
+          thread_id: "#{ctx.thread_id}_agent_#{SecureRandom.uuid}",
+          config: config,
+          parent_id: ctx.thread_id,
+          result_writer: result_writer
+        )
+        Phronomy::EventLoop.instance.enqueue_child(fsm)
+        nil
       end
 
       # Streaming version of #invoke. Yields {Phronomy::Agent::StreamEvent} objects
@@ -665,6 +741,15 @@ module Phronomy
 
       # Load messages from a ConversationManager.
       #
+      # Returns the chat class to instantiate for this invocation.
+      # When the +:phronomy_agent_parallel_tools+ thread-local flag is set
+      # (i.e. inside an {AgentFSM} IO thread), returns {ParallelToolChat} so
+      # that concurrent tool dispatch is enabled.  Falls back to +nil+ otherwise,
+      # signalling {#build_chat} to use the standard +RubyLLM.chat+ factory.
+      def build_chat_class
+        Thread.current[:phronomy_agent_parallel_tools] ? Agent::ParallelToolChat : nil
+      end
+
       def build_chat
         opts = {}
         m = self.class.model
@@ -675,7 +760,8 @@ module Phronomy
           opts[:assume_model_exists] = true
         end
         t = self.class.temperature
-        chat = RubyLLM.chat(**opts)
+        parallel_class = build_chat_class
+        chat = parallel_class ? parallel_class.new(**opts) : RubyLLM.chat(**opts)
         chat.with_temperature(t) if t
         self.class.tools.each do |tool_class|
           chat.with_tool(prepare_tool_class(tool_class))

data/lib/phronomy/agent/fsm.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Phronomy
+  module Agent
+    # EventLoop-registered execution unit for a single agent invocation.
+    #
+    # +AgentFSM+ implements the minimal interface expected by {Phronomy::EventLoop}
+    # (+#id+, +#start+, +#handle+) so it can be managed alongside
+    # {Phronomy::FSMSession} instances.  It is *not* a traditional finite-state
+    # machine; the name reflects its role in the EventLoop rather than internal
+    # state transitions.
+    #
+    # == Execution model
+    #
+    # {#start} is called by the EventLoop on the +:start+ event.  It immediately
+    # returns after spawning a background IO thread that runs the agent's full
+    # invocation pipeline (via +_invoke_impl+).  The EventLoop thread is never
+    # blocked by agent execution.
+    #
+    # Inside the IO thread, the +:phronomy_agent_parallel_tools+ thread-local
+    # flag is set to +true+ so that {Agent::Base#build_chat} returns a
+    # {ParallelToolChat} instance, enabling concurrent tool dispatch when the LLM
+    # returns multiple tool calls in one response.
+    #
+    # == Completion events
+    #
+    # On *success*:
+    #   - Posts +:finished+ to this FSM's own +#id+ so the EventLoop cleans up
+    #     its registry entry and unblocks any +completion_queue.pop+ caller.
+    #   - When +parent_id+ is set (child-FSM pattern), additionally posts
+    #     +:child_completed+ to +parent_id+, carrying the result hash as the
+    #     event payload.  The parent {FSMSession} must declare an +on:+ transition
+    #     for +:child_completed+ to advance correctly.
+    #
+    # On *error*:
+    #   - Posts +:error+ to this FSM's own +#id+.  The EventLoop propagates the
+    #     exception through the +completion_queue+ so that the original caller of
+    #     +Agent::Base#invoke+ (in EventLoop mode) receives and re-raises it.
+    #
+    # == Standalone usage (blocking caller)
+    #
+    #   Phronomy.configure { |c| c.event_loop = true }
+    #   result = MyAgent.new.invoke("Hello!")   # => { output:, messages:, usage: }
+    #
+    # {Agent::Base#invoke} detects EventLoop mode, creates an +AgentFSM+, registers
+    # it via {EventLoop#register}, and blocks the *calling* thread on the returned
+    # +completion_queue+ until the agent finishes.
+    #
+    # == Child-FSM usage (non-blocking, inside a Workflow)
+    #
+    #   state :run_agent
+    #   entry :run_agent, ->(ctx) { MyAgent.new.run_as_child(ctx.query, ctx: ctx) }
+    #   transition from: :run_agent, on: :child_completed, to: :process_result
+    #
+    # {Agent::Base#run_as_child} creates an +AgentFSM+ with +parent_id+ set to
+    # +ctx.thread_id+, registers it with the EventLoop, and returns immediately.
+    # The parent {FSMSession} waits for the +:child_completed+ event.
+    class FSM
+      # @return [String] unique identifier used as the EventLoop target_id
+      attr_reader :id
+
+      # @return [Symbol] current internal phase (:idle, :running)
+      attr_reader :current_phase
+
+      # @param agent     [Phronomy::Agent::Base]  agent instance to run
+      # @param input     [String, Hash]           user input passed to +invoke_once+
+      # @param messages  [Array]                  prior conversation history
+      # @param thread_id [String, nil]            conversation thread id;
+      #                                           auto-generated when nil
+      # @param config    [Hash]                   invocation config forwarded to
+      #                                           +_invoke_impl+
+      # @param parent_id    [String, nil]  EventLoop id of the parent
+      #                                     FSMSession; when set, a
+      #                                     +:child_completed+ event is posted
+      #                                     on completion
+      # @param result_writer [Proc, nil]   optional callable invoked with the
+      #                                     result hash <b>before</b>
+      #                                     +:child_completed+ is posted.
+      #                                     Use this to write the agent output
+      #                                     back into the parent WorkflowContext.
+      #                                     Thread::Queue provides the
+      #                                     happens-before guarantee.
+      #
+      # @example Writing result into context
+      #   entry :run_agent, ->(ctx) {
+      #     MyAgent.new.run_as_child(ctx.query, ctx: ctx) { |r| ctx.answer = r[:output] }
+      #   }
+      def initialize(agent:, input:, messages: [], thread_id: nil, config: {}, parent_id: nil, result_writer: nil)
+        @agent = agent
+        @input = input
+        @messages = Array(messages).dup
+        @thread_id = thread_id || SecureRandom.uuid
+        @config = config
+        @parent_id = parent_id
+        @result_writer = result_writer
+        @id = @thread_id
+        @current_phase = :idle
+      end
+
+      # Called by {EventLoop} on the +:start+ event.
+      # Transitions to +:running+ and spawns the agent IO thread.
+      def start
+        @current_phase = :running
+        spawn_agent_thread
+      end
+
+      # Called by {EventLoop} for external events dispatched to this id.
+      # +AgentFSM+ is fully driven by its own IO thread and does not respond
+      # to external events after {#start}.
+      def handle(_event)
+        # No-op: AgentFSM is driven entirely by its IO thread.
+      end
+
+      private
+
+      # Spawns the background IO thread that runs the agent invocation.
+      # Captures all instance variables by value so the thread closure is
+      # safe even if the FSM object is modified (though it is not in practice).
+      def spawn_agent_thread
+        agent = @agent
+        input = @input
+        messages = @messages
+        thread_id = @thread_id
+        config = @config
+        fsm_id = @id
+        parent_id = @parent_id
+        result_writer = @result_writer
+
+        Thread.new do
+          # Enable parallel tool dispatch inside this IO thread.
+          Thread.current[:phronomy_agent_parallel_tools] = true
+
+          begin
+            result = agent.send(:_invoke_impl,
+              input,
+              messages: messages,
+              thread_id: thread_id,
+              config: config)
+
+            if parent_id
+              # Let the caller write the result into the context BEFORE the
+              # parent FSMSession advances.  Thread::Queue provides the
+              # happens-before guarantee — no Mutex needed.
+              result_writer&.call(result)
+
+              Phronomy::EventLoop.instance.post(
+                Phronomy::Event.new(type: :child_completed, target_id: parent_id, payload: result)
+              )
+            end
+
+            Phronomy::EventLoop.instance.post(
+              Phronomy::Event.new(type: :finished, target_id: fsm_id, payload: result)
+            )
+          rescue => e
+            Phronomy::EventLoop.instance.post(
+              Phronomy::Event.new(type: :error, target_id: fsm_id, payload: e)
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/orchestrator.rb

@@ -88,31 +88,112 @@ module Phronomy
       # threads. Each task is a Hash describing one agent invocation.
       #
       # Results are returned in the same order as the input +tasks+ array.
-      # If any thread raises an exception, the exception is re-raised in the
-      # calling thread after all threads have completed (via +Thread#value+).
+      # Concurrency is bounded by +max_concurrency+; when nil all tasks run at
+      # once (original behaviour).
       #
-      # @param tasks [Array<Hash>]
-      # @option task [Class]  :agent  agent class to invoke (required)
-      # @option task [String] :input  input string for the agent (required)
-      # @option task [Hash]   :config forwarded to +agent#invoke+ (default: +{}+)
-      # @return [Array<Hash>] agent results in the same order as +tasks+
-      def dispatch_parallel(*tasks)
-        threads = tasks.map do |task|
-          Thread.new do
-            task[:agent].new.invoke(task[:input], config: task.fetch(:config, {}))
-          end
+      # Error semantics are controlled by +on_error+:
+      # - +:raise+ (default) — every task runs to completion; the first
+      #   exception in input order is then re-raised in the calling thread.
+      # - +:skip+            — failed tasks return +nil+; no exception is raised.
+      #
+      # @param tasks           [Array<Hash>]
+      # @option task [Class]   :agent  agent class to invoke (required)
+      # @option task [String]  :input  input string for the agent (required)
+      # @option task [Hash]    :config forwarded to +agent#invoke+ (default: +{}+)
+      # @param max_concurrency [Integer, nil] maximum number of concurrent threads;
+      #   nil means no limit (all tasks run simultaneously)
+      # @param on_error        [Symbol] +:raise+ or +:skip+
+      # @return [Array<Hash, nil>] agent results in the same order as +tasks+
+      # @raise [ArgumentError] if +on_error+ is not +:raise+ or +:skip+
+      # @raise [ArgumentError] if +max_concurrency+ is not a positive Integer or nil
+      def dispatch_parallel(*tasks, max_concurrency: nil, on_error: :raise)
+        unless [:raise, :skip].include?(on_error)
+          raise ArgumentError, "unknown on_error: #{on_error.inspect}"
         end
-        threads.map(&:value)
+        if max_concurrency && !(max_concurrency.is_a?(Integer) && max_concurrency.positive?)
+          raise ArgumentError, "max_concurrency must be a positive Integer"
+        end
+
+        bounded_map(tasks, max_concurrency: max_concurrency, on_error: on_error)
       end
 
       # Runs the same agent against multiple inputs in parallel (fan-out pattern).
       #
-      # @param agent  [Class]         agent class to invoke for every input
-      # @param inputs [Array<String>] list of input strings
-      # @param config [Hash]          forwarded to every +agent#invoke+ call
-      # @return [Array<Hash>] results in the same order as +inputs+
-      def fan_out(agent:, inputs:, config: {})
-        dispatch_parallel(*inputs.map { |input| {agent: agent, input: input, config: config} })
+      # Accepts the same +max_concurrency:+ and +on_error:+ keyword arguments as
+      # {#dispatch_parallel} and forwards them unchanged.
+      #
+      # @param agent           [Class]         agent class to invoke for every input
+      # @param inputs          [Array<String>] list of input strings
+      # @param config          [Hash]          forwarded to every +agent#invoke+ call
+      # @param max_concurrency [Integer, nil]  forwarded to {#dispatch_parallel}
+      # @param on_error        [Symbol]        forwarded to {#dispatch_parallel}
+      # @return [Array<Hash, nil>] results in the same order as +inputs+
+      def fan_out(agent:, inputs:, config: {}, max_concurrency: nil, on_error: :raise)
+        dispatch_parallel(
+          *inputs.map { |input| {agent: agent, input: input, config: config} },
+          max_concurrency: max_concurrency,
+          on_error: on_error
+        )
+      end
+
+      private
+
+      # Worker-pool implementation shared by {#dispatch_parallel} and {#fan_out}.
+      #
+      # Uses a +Queue+ as a work-stealing mechanism: each worker thread pops a
+      # task, executes it, and loops until the queue is empty.  The number of
+      # workers is +min(max_concurrency, tasks.length)+, capped at the task count
+      # so we never spin up idle threads.
+      #
+      # +errors+ is indexed by task position so that the first error in *input*
+      # order is deterministically re-raised when +on_error: :raise+ is used.
+      # A +Mutex+ guards concurrent writes to +errors+ even though Array element
+      # assignment at different indices is safe in MRI; this keeps the code
+      # correct across alternative Ruby runtimes.
+      def bounded_map(tasks, max_concurrency:, on_error:)
+        return [] if tasks.empty?
+
+        results = Array.new(tasks.length)
+        errors = Array.new(tasks.length)
+        errors_mutex = Mutex.new
+
+        queue = Queue.new
+        tasks.each_with_index { |task, i| queue << [i, task] }
+
+        worker_count = [max_concurrency || tasks.length, tasks.length].min
+
+        workers = worker_count.times.map do
+          Thread.new do
+            loop do
+              i, task = begin
+                queue.pop(true)
+              rescue ThreadError
+                break # queue is empty; this worker is done
+              end
+
+              begin
+                results[i] = task[:agent].new.invoke(
+                  task[:input],
+                  config: task.fetch(:config, {})
+                )
+              rescue => e
+                case on_error
+                when :skip
+                  results[i] = nil
+                else
+                  errors_mutex.synchronize { errors[i] = e }
+                end
+              end
+            end
+          end
+        end
+
+        workers.each(&:join)
+
+        first_error = errors.compact.first
+        raise first_error if first_error
+
+        results
       end
     end
   end

data/lib/phronomy/agent/parallel_tool_chat.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # RubyLLM::Chat subclass that executes multiple tool calls concurrently.
+    #
+    # When the LLM returns more than one tool call in a single response, each
+    # tool is dispatched in a dedicated IO thread and all results are collected
+    # before being appended to the message history. This preserves a
+    # deterministic message order while reducing wall-clock latency when tools
+    # are IO-bound (HTTP calls, DB queries, etc.).
+    #
+    # Single-tool responses fall through to the standard sequential path via
+    # +super+, preserving all existing edge-case behaviour (Tool::Halt,
+    # forced_tool_choice, streaming, SuspendSignal, etc.).
+    #
+    # This class is used automatically when the agent is running inside an
+    # {AgentFSM} IO thread (i.e. when the +:phronomy_agent_parallel_tools+
+    # thread-local flag is +true+).  It is not used for direct synchronous
+    # +invoke+ calls so that the streaming callback state remains single-threaded.
+    class ParallelToolChat < RubyLLM::Chat
+      private
+
+      # Overrides RubyLLM::Chat#handle_tool_calls to parallelise execution
+      # when multiple tool calls are present in a single LLM response.
+      #
+      # The method preserves the three-phase protocol of the original:
+      #   1. Pre-execution callbacks (+on_new_message+, +on_tool_call+) —
+      #      sequential so that the Suspendable concern's approval hook can
+      #      raise +SuspendSignal+ before any tool is executed.
+      #   2. Parallel tool execution — one IO thread per tool call.
+      #   3. Post-execution callbacks and message recording — sequential,
+      #      in the original tool-call order.
+      #
+      # @param response [RubyLLM::Message] the LLM response containing tool calls
+      # @yield streaming block forwarded to +complete+
+      def handle_tool_calls(response, &block)
+        tool_calls = response.tool_calls.values
+
+        # Single tool: delegate to the parent implementation to preserve every
+        # edge case (forced_tool_choice, streaming, Halt, SuspendSignal…).
+        return super if tool_calls.size <= 1
+
+        # Phase 1 — pre-execution callbacks (sequential, original order).
+        # The SuspendSignal approval hook is registered via on_tool_call, so it
+        # MUST fire before execution begins.
+        tool_calls.each do |tool_call|
+          @on[:new_message]&.call
+          @on[:tool_call]&.call(tool_call)
+        end
+
+        # Phase 2 — parallel tool execution.
+        thread_results = tool_calls.map do |tool_call|
+          Thread.new { {tool_call: tool_call, result: execute_tool(tool_call)} }
+        end
+        results = thread_results.map(&:value)
+
+        # Phase 3 — post-execution callbacks and message recording (sequential).
+        halt_result = nil
+        results.each do |item|
+          result = item[:result]
+          @on[:tool_result]&.call(result)
+          tool_payload = result.is_a?(RubyLLM::Tool::Halt) ? result.content : result
+          content = content_like?(tool_payload) ? tool_payload : tool_payload.to_s
+          message = add_message(role: :tool, content: content, tool_call_id: item[:tool_call].id)
+          @on[:end_message]&.call(message)
+          halt_result = result if result.is_a?(RubyLLM::Tool::Halt)
+        end
+
+        reset_tool_choice if forced_tool_choice?
+        halt_result || complete(&block)
+      end
+    end
+  end
+end