phronomy 0.6.0 → 0.7.0

data/lib/phronomy/agent/concerns/suspendable.rb

@@ -8,6 +8,7 @@ module Phronomy
       # Included in {Phronomy::Agent::Base}. When a tool decorated with
       # +requires_approval true+ is called and no synchronous approval handler
       # has been registered, the invocation is suspended and a
+      # @api private
       # {Phronomy::Agent::Checkpoint} is returned so the caller can resume later.
       module Suspendable
         # Registers a callback that is invoked before executing any tool that has
@@ -25,6 +26,7 @@ module Phronomy
         #   agent = MyAgent.new
         #   agent.on_approval_required { |tool_name, args| prompt_user(tool_name, args) }
         # @return [self]
+        # @api private
         def on_approval_required(&block)
           @approval_handler = block
           self
@@ -43,6 +45,7 @@ module Phronomy
         # @param config     [Hash] same runtime options as #invoke
         # @return [Hash] +{ output: String, suspended: false, messages: Array, usage: Phronomy::TokenUsage }+
         # @raise [Phronomy::GuardrailError] when an output guardrail rejects the value
+        # @api private
         def resume(checkpoint, approved:, config: {})
           # Build a fresh chat with all tools registered.
           chat = build_chat
@@ -95,6 +98,7 @@ module Phronomy
         #   - none of the agent's tools have requires_approval set.
         #
         # @param chat [RubyLLM::Chat]
+        # @api private
         def _register_suspension_hook!(chat)
           return if @approval_handler
           return if self.class.tools.none? { |tc| tc.requires_approval }

data/lib/phronomy/agent/fsm.rb

@@ -57,6 +57,7 @@ module Phronomy
     # {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.
+    # @api private
     class FSM
       # @return [String] unique identifier used as the EventLoop target_id
       attr_reader :id
@@ -87,6 +88,7 @@ module Phronomy
       #   entry :run_agent, ->(ctx) {
       #     MyAgent.new.run_as_child(ctx.query, ctx: ctx) { |r| ctx.answer = r[:output] }
       #   }
+      # @api private
       def initialize(agent:, input:, messages: [], thread_id: nil, config: {}, parent_id: nil, result_writer: nil)
         @agent = agent
         @input = input
@@ -131,6 +133,9 @@ module Phronomy
         Thread.new do
           # Enable parallel tool dispatch inside this IO thread.
           Thread.current[:phronomy_agent_parallel_tools] = true
+          # Forward the concurrency cap to ParallelToolChat.
+          Thread.current[:phronomy_max_parallel_tools] =
+            agent.class.respond_to?(:max_parallel_tools) ? agent.class.max_parallel_tools : 10
 
           begin
             result = agent.send(:_invoke_impl,
@@ -154,9 +159,19 @@ module Phronomy
               Phronomy::Event.new(type: :finished, target_id: fsm_id, payload: result)
             )
           rescue => e
+            if parent_id
+              Phronomy::EventLoop.instance.post(
+                Phronomy::Event.new(type: :child_failed, target_id: parent_id, payload: e)
+              )
+            end
+
             Phronomy::EventLoop.instance.post(
               Phronomy::Event.new(type: :error, target_id: fsm_id, payload: e)
             )
+          ensure
+            # Clear the thread-local context cache for this agent so the IO
+            # thread's cache does not grow unboundedly across invocations.
+            Thread.current[:phronomy_context_version_caches]&.delete(agent.object_id)
           end
         end
       end

data/lib/phronomy/agent/handoff.rb

@@ -22,6 +22,7 @@ module Phronomy
 
       # @param target_agent [Phronomy::Agent::Base] the agent to hand off to
       # @param description  [String, nil] overrides the auto-generated tool description
+      # @api public
       def initialize(target_agent:, description: nil)
         @target_agent = target_agent
         klass_name = target_agent.class.name&.split("::")&.last || "Agent"
@@ -33,6 +34,7 @@ module Phronomy
 
       # Builds an anonymous Phronomy::Tool::Base subclass for this handoff.
       # @return [Class<Phronomy::Tool::Base>]
+      # @api public
       def to_tool_class
         sentinel_value = sentinel
         tn = tool_name
@@ -46,6 +48,7 @@ module Phronomy
 
       # The sentinel string embedded in the tool result.
       # @return [String]
+      # @api public
       def sentinel
         "#{SENTINEL_PREFIX}:#{target_agent.class.name}:#{@uuid}"
       end

data/lib/phronomy/agent/orchestrator.rb

@@ -55,6 +55,7 @@ module Phronomy
       # @param on_error    [Symbol] +:raise+ (default) re-raises any exception
       #   from the subagent; +:skip+ returns +nil+ so the LLM can decide how to
       #   proceed
+      # @api public
       def self.subagent(name, agent_class, on_error: :raise)
         tool_class = Class.new(Phronomy::Tool::Base) do
           tool_name "dispatch_to_#{name}"
@@ -62,7 +63,14 @@ module Phronomy
           param :input, type: :string, desc: "The task or question for the subagent"
 
           define_method(:execute) do |input:|
-            result = agent_class.new.invoke(input)
+            # Inherit the calling orchestrator's thread_id and config when
+            # available so that sub-agent spans and memory stay connected.
+            ctx = Thread.current[:phronomy_orchestrator_context] || {}
+            result = agent_class.new.invoke(
+              input,
+              thread_id: ctx[:thread_id],
+              config: ctx[:config] || {}
+            )
             result[:output]
           rescue
             raise if on_error == :raise
@@ -80,6 +88,7 @@ module Phronomy
       # Returns the subagent registry for this specific class (not inherited).
       #
       # @return [Hash{Symbol => Hash}]
+      # @api public
       def self.registered_subagents
         @registered_subagents ||= {}
       end
@@ -100,13 +109,28 @@ module Phronomy
       # @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;
+      # @option task [String]  :thread_id forwarded to +agent#invoke+ (default: nil)
+      # @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+
+      # @param on_error            [Symbol] +:raise+ or +:skip+
+      # @param timeout             [Numeric, nil] maximum seconds to wait for all workers;
+      #   nil means wait indefinitely. When the deadline is exceeded,
+      #   {Phronomy::TimeoutError} is raised and all surviving worker threads are killed.
+      # @param cancellation_token [Phronomy::CancellationToken, nil] when provided, the
+      #   token is merged into each task's config (unless the task already sets one) so
+      #   that every worker agent checks it before making LLM calls.
+      # @param force_kill [Boolean] when +true+, surviving worker threads are killed with
+      #   +Thread#kill+ after the grace period if they do not stop cooperatively. When
+      #   +false+ (default), workers are asked to stop cooperatively but are never killed;
+      #   the caller receives {Phronomy::TimeoutError} immediately and abandoned workers
+      #   discard their results when they eventually finish. +false+ is safer for
+      #   production because +Thread#kill+ can interrupt +ensure+ blocks.
       # @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)
+      # @raise [Phronomy::TimeoutError] if +timeout+ is exceeded
+      # @api public
+      def dispatch_parallel(*tasks, max_concurrency: nil, on_error: :raise, timeout: nil, cancellation_token: nil, force_kill: false)
         unless [:raise, :skip].include?(on_error)
           raise ArgumentError, "unknown on_error: #{on_error.inspect}"
         end
@@ -114,7 +138,7 @@ module Phronomy
           raise ArgumentError, "max_concurrency must be a positive Integer"
         end
 
-        bounded_map(tasks, max_concurrency: max_concurrency, on_error: on_error)
+        bounded_map(tasks, max_concurrency: max_concurrency, on_error: on_error, timeout: timeout, cancellation_token: cancellation_token, force_kill: force_kill)
       end
 
       # Runs the same agent against multiple inputs in parallel (fan-out pattern).
@@ -125,19 +149,52 @@ module Phronomy
       # @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 thread_id       [String, nil]   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)
+      # @api public
+      def fan_out(agent:, inputs:, config: {}, thread_id: nil, max_concurrency: nil, on_error: :raise, timeout: nil, cancellation_token: nil, force_kill: false)
         dispatch_parallel(
-          *inputs.map { |input| {agent: agent, input: input, config: config} },
+          *inputs.map { |input| {agent: agent, input: input, config: config, thread_id: thread_id} },
           max_concurrency: max_concurrency,
-          on_error: on_error
+          on_error: on_error,
+          timeout: timeout,
+          cancellation_token: cancellation_token,
+          force_kill: force_kill
+        )
+      end
+
+      # Programmatically dispatches a single sub-agent from inside an orchestrator
+      # instance, inheriting the parent's +thread_id+ and +config+ by default.
+      #
+      # @param agent_class [Class]         subclass of {Phronomy::Agent::Base}
+      # @param input       [String]        task or question for the sub-agent
+      # @param config      [Hash, nil]     override config (falls back to parent's)
+      # @param thread_id   [String, nil]   override thread_id (falls back to parent's)
+      # @return [Hash]  the sub-agent's result hash (+:output+, +:messages+)
+      # @api public
+      def subagent(agent_class, input, config: nil, thread_id: nil)
+        ctx = Thread.current[:phronomy_orchestrator_context] || {}
+        agent_class.new.invoke(
+          input,
+          config: config || ctx[:config] || {},
+          thread_id: thread_id || ctx[:thread_id]
         )
       end
 
       private
 
+      # Override invoke_once to expose the current thread_id and config via a
+      # thread-local so that DSL-registered subagent tools can inherit them.
+      def invoke_once(input, messages: [], thread_id: nil, config: {})
+        prev = Thread.current[:phronomy_orchestrator_context]
+        Thread.current[:phronomy_orchestrator_context] = {thread_id: thread_id, config: config}
+        super
+      ensure
+        Thread.current[:phronomy_orchestrator_context] = prev
+      end
+
       # Worker-pool implementation shared by {#dispatch_parallel} and {#fan_out}.
       #
       # Uses a +Queue+ as a work-stealing mechanism: each worker thread pops a
@@ -150,12 +207,27 @@ module Phronomy
       # 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:)
+      #
+      # When +timeout+ is given, workers are first asked to stop cooperatively
+      # via a cancellation flag (so they do not pick up new tasks) and then given
+      # +KILL_GRACE_SECONDS+ to finish any in-flight +ensure+ blocks.  Only
+      # workers that are still alive after the grace period are force-killed, and
+      # a warning is logged in that case.  Use a +CancellationToken+ (see #216)
+      # for full cooperative cancellation of long-running tasks.
+      #
+      # Deadline tracking uses +Process.clock_gettime(Process::CLOCK_MONOTONIC)+
+      # to avoid sensitivity to NTP adjustments and system-clock changes.
+      KILL_GRACE_SECONDS = 0.5
+      private_constant :KILL_GRACE_SECONDS
+
+      def bounded_map(tasks, max_concurrency:, on_error:, timeout: nil, cancellation_token: nil, force_kill: false)
         return [] if tasks.empty?
 
         results = Array.new(tasks.length)
         errors = Array.new(tasks.length)
         errors_mutex = Mutex.new
+        # Mutex-backed cooperative stop token; workers check before each task pick-up.
+        internal_stop_token = Phronomy::CancellationToken.new
 
         queue = Queue.new
         tasks.each_with_index { |task, i| queue << [i, task] }
@@ -165,16 +237,26 @@ module Phronomy
         workers = worker_count.times.map do
           Thread.new do
             loop do
+              break if internal_stop_token.cancelled?
+
               i, task = begin
                 queue.pop(true)
               rescue ThreadError
                 break # queue is empty; this worker is done
               end
 
+              # Merge the shared cancellation token into the task's config unless
+              # the task already supplies its own token.
+              task_config = task.fetch(:config, {})
+              if cancellation_token && !task_config[:cancellation_token]
+                task_config = task_config.merge(cancellation_token: cancellation_token)
+              end
+
               begin
                 results[i] = task[:agent].new.invoke(
                   task[:input],
-                  config: task.fetch(:config, {})
+                  config: task_config,
+                  thread_id: task[:thread_id]
                 )
               rescue => e
                 case on_error
@@ -188,7 +270,37 @@ module Phronomy
           end
         end
 
-        workers.each(&:join)
+        workers.each(&:join) if timeout.nil?
+
+        if timeout
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+          workers.each do |w|
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            w.join([remaining, 0].max)
+          end
+
+          alive = workers.select(&:alive?)
+          unless alive.empty?
+            # Signal workers cooperatively to stop picking up new tasks.
+            internal_stop_token.cancel!
+            if force_kill
+              # Give in-flight ensure blocks a short grace period before kill.
+              alive.each { |w| w.join(KILL_GRACE_SECONDS) }
+              still_alive = alive.select(&:alive?)
+              if still_alive.any?
+                Phronomy.configuration.logger&.warn(
+                  "[Phronomy] dispatch_parallel: #{still_alive.length} worker(s) did not stop " \
+                  "within grace period; force-killing. Use CancellationToken for " \
+                  "cooperative cancellation of long-running tasks."
+                )
+                still_alive.each(&:kill)
+              end
+            end
+            raise Phronomy::TimeoutError,
+              "dispatch_parallel timed out after #{timeout}s " \
+              "(#{alive.length} of #{workers.length} workers still running)"
+          end
+        end
 
         first_error = errors.compact.first
         raise first_error if first_error

data/lib/phronomy/agent/parallel_tool_chat.rb

@@ -18,6 +18,7 @@ module Phronomy
     # {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.
+    # @api private
     class ParallelToolChat < RubyLLM::Chat
       private
 
@@ -34,6 +35,7 @@ module Phronomy
       #
       # @param response [RubyLLM::Message] the LLM response containing tool calls
       # @yield streaming block forwarded to +complete+
+      # @api private
       def handle_tool_calls(response, &block)
         tool_calls = response.tool_calls.values
 
@@ -50,14 +52,29 @@ module Phronomy
         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)} }
+        # Honour the per-agent concurrency cap (max_parallel_tools DSL).
+        # Tool calls are processed in batches of at most `max` threads;
+        # batches run sequentially so the total in-flight thread count never
+        # exceeds the limit.
+        #
+        # Check for cancellation before dispatching each batch so that
+        # already-cancelled tokens do not start new LLM/tool-round-trips.
+        ct = Thread.current[:phronomy_cancellation_token]
+        max = Thread.current[:phronomy_max_parallel_tools] || 10
+        thread_results = tool_calls.each_slice(max).flat_map do |batch|
+          if ct&.cancelled?
+            raise Phronomy::CancellationError, "invocation cancelled before tool execution"
+          end
+
+          threads = batch.map do |tool_call|
+            Thread.new { {tool_call: tool_call, result: execute_tool(tool_call)} }
+          end
+          threads.map(&:value)
         end
-        results = thread_results.map(&:value)
 
         # Phase 3 — post-execution callbacks and message recording (sequential).
         halt_result = nil
-        results.each do |item|
+        thread_results.each do |item|
           result = item[:result]
           @on[:tool_result]&.call(result)
           tool_payload = result.is_a?(RubyLLM::Tool::Halt) ? result.content : result

data/lib/phronomy/agent/react_agent.rb

@@ -37,9 +37,10 @@ module Phronomy
             end
           end
 
-          # Fall back to the last message
-          # guards against the case where the final message is a tool-call or
-          output = messages.reverse.find { |m| m.content && !m.content.empty? }&.content
+          # Select the last assistant-produced content as the output, skipping
+          # raw tool result messages (role: :tool) to avoid returning tool JSON
+          # or status strings as the agent's answer when iterations are exhausted.
+          output = messages.reverse.find { |m| m.content && !m.content.empty? && m.role != :tool }&.content
 
           # Run output guardrails before returning to the caller.
           run_output_guardrails!(output)
@@ -60,6 +61,7 @@ module Phronomy
       # @param config    [Hash]
       # @yield [Phronomy::Agent::StreamEvent]
       # @return [Hash] { output:, messages:, usage: }
+      # @api public
       def stream(input, messages: [], thread_id: nil, config: {}, &block)
         return invoke(input, messages: messages, thread_id: thread_id, config: config) unless block
 
@@ -88,9 +90,9 @@ module Phronomy
             end
           end
 
-          # Fall back to the last message that carries non-nil content (same as
-          # the non-streaming path above).
-          output = messages.reverse.find { |m| m.content && !m.content.empty? }&.content
+          # Select the last assistant-produced content as the output, skipping
+          # raw tool result messages (role: :tool) — same as the non-streaming path.
+          output = messages.reverse.find { |m| m.content && !m.content.empty? && m.role != :tool }&.content
           run_output_guardrails!(output)
 
           result = {output: output, messages: messages, usage: total_usage, iterations_exhausted: iterations_exhausted}

data/lib/phronomy/agent/runner.rb

@@ -30,6 +30,7 @@ module Phronomy
       # @param routes [Hash{Phronomy::Agent::Base => Array<Phronomy::Agent::Base>}]
       #   declares which target agents each source agent may hand off to;
       #   when omitted no handoffs are configured and the entry agent handles everything
+      # @api public
       def initialize(agents:, routes: {})
         @agents = Array(agents)
         raise ArgumentError, "At least one agent is required" if @agents.empty?
@@ -47,6 +48,7 @@ module Phronomy
       # @param config [Hash] forwarded to each agent's #invoke
       # @return [Hash] { output:, messages:, usage:, agent: }
       # @raise [Phronomy::HandoffError] if more than MAX_HANDOFFS handoffs occur
+      # @api public
       def invoke(input, config: {})
         current = @entry_agent
         handoffs_taken = 0

data/lib/phronomy/agent/shared_state.rb

@@ -57,6 +57,7 @@ module Phronomy
 
         # Returns a shallow copy of all findings in insertion order.
         # @return [Array<Hash>]
+        # @api public
         def read_all
           @findings.dup
         end
@@ -66,6 +67,7 @@ module Phronomy
         # @param content [String]  the finding text
         # @param cycle   [Integer] the current cycle number
         # @return [nil]
+        # @api public
         def write(agent:, content:, cycle:)
           @findings << {agent: agent, content: content, cycle: cycle}
           nil
@@ -73,6 +75,7 @@ module Phronomy
 
         # Returns the number of findings recorded so far.
         # @return [Integer]
+        # @api public
         def size
           @findings.size
         end
@@ -85,6 +88,7 @@ module Phronomy
         # @param klass [Class] an Agent::Base subclass
         # @param instruction [String, nil] optional per-agent coordination instruction
         #   appended to the team coordination text in this agent's prompt
+        # @api public
         def member(klass, instruction: nil)
           @members ||= []
           @members << {klass: klass, instruction: instruction}
@@ -94,6 +98,7 @@ module Phronomy
         # per-agent instruction. Prefer {.member} for new code.
         #
         # @param classes [Array<Class>] Agent::Base subclasses
+        # @api public
         def researchers(*classes)
           classes.flatten.each { |klass| member(klass) }
         end
@@ -104,6 +109,7 @@ module Phronomy
         # workflow. Override this when you need a different protocol or tone.
         #
         # @param text [String, nil] the coordination instructions
+        # @api public
         def coordination(text = nil)
           text ? @coordination = text : @coordination
         end
@@ -112,6 +118,7 @@ module Phronomy
         # At least one of +max_cycles+ or +timeout+ must be configured.
         #
         # @param value [Integer, nil]
+        # @api public
         def max_cycles(value = nil)
           value ? @max_cycles = Integer(value) : @max_cycles
         end
@@ -120,6 +127,7 @@ module Phronomy
         # At least one of +max_cycles+ or +timeout+ must be configured.
         #
         # @param value [Numeric, nil]
+        # @api public
         def timeout(value = nil)
           value ? @timeout = value.to_f : @timeout
         end
@@ -128,6 +136,7 @@ module Phronomy
         # cycle; when it returns +true+ the loop terminates early.
         #
         # @yield [KnowledgeStore] receives the store; return +true+ to stop
+        # @api public
         def terminate_when(&block)
           block ? @terminate_when = block : @terminate_when
         end
@@ -136,6 +145,7 @@ module Phronomy
         # When omitted, +store.read_all+ is used as-is.
         #
         # @yield [KnowledgeStore] receives the final store; return value becomes +:output+
+        # @api public
         def aggregate(&block)
           block ? @aggregator = block : @aggregator
         end
@@ -162,6 +172,7 @@ module Phronomy
       # @param config [Hash]   reserved for future use
       # @return [Hash] +:output+, +:cycles+, +:terminated_by+
       # @raise [ArgumentError] when neither +max_cycles+ nor +timeout+ is configured
+      # @api public
       def invoke(input, config: {})
         validate_termination!
 

data/lib/phronomy/agent/suspend_signal.rb

@@ -8,6 +8,7 @@ module Phronomy
     # suspended result hash containing a Checkpoint.
     #
     # This class is intentionally NOT part of the public API.  Callers should
+    # @api private
     # inspect the +:suspended+ key in the result hash returned by #invoke.
     #
     # @api private
@@ -24,6 +25,7 @@ module Phronomy
       # @param tool_name    [String]
       # @param args         [Hash]
       # @param tool_call_id [String]
+      # @api private
       def initialize(tool_name:, args:, tool_call_id:)
         super("Agent suspended waiting for approval of tool: #{tool_name}")
         @tool_name = tool_name

data/lib/phronomy/agent/team_coordinator.rb

@@ -7,9 +7,13 @@ module Phronomy
     # @see https://claude.com/blog/multi-agent-coordination-patterns
     #
     # A coordinator LLM agent decomposes work into tasks and enqueues them
-    # dynamically via built-in tools. A fixed pool of worker agents claims tasks
-    # from the shared queue, carrying forward their conversation history across
-    # assignments to accumulate domain context over time.
+    # dynamically via built-in tools. A fixed set of worker agents processes tasks
+    # sequentially — one task per worker per turn — carrying forward their
+    # conversation history across assignments to accumulate domain context over time.
+    #
+    # Workers are selected in sequence (the worker with the fewest accumulated
+    # messages is chosen by default). Task dispatch is synchronous; there is no
+    # concurrent or parallel execution.
     #
     # The coordinator is an {Agent::Base} subclass that has two built-in tools:
     # - +enqueue_task+ — adds a task description to the queue
@@ -56,6 +60,7 @@ module Phronomy
         # Falls back to +Phronomy.configuration.default_model+ when not set.
         #
         # @param value [String, nil]
+        # @api public
         def coordinator_model(value = nil)
           value ? @coordinator_model = value : @coordinator_model
         end
@@ -65,6 +70,7 @@ module Phronomy
         # and then call +finalize+ when all tasks are enqueued.
         #
         # @param value [String, nil]
+        # @api public
         def coordinator_instructions(value = nil)
           value ? @coordinator_instructions = value : @coordinator_instructions
         end
@@ -75,16 +81,18 @@ module Phronomy
         # Pass the same value as +LLMConfig::PROVIDER+ in your examples.
         #
         # @param value [Symbol, nil]
+        # @api public
         def coordinator_provider(value = nil)
           value ? @coordinator_provider = value : @coordinator_provider
         end
 
-        # Configures the worker pool.
+        # Configures the set of workers.
         #
-        # @param size     [Integer] number of persistent worker instances
+        # @param size     [Integer] number of persistent worker instances (tasks are assigned sequentially)
         # @param agent    [Class]   Agent::Base subclass used for all workers
         # @param on_error [Symbol]  +:raise+ (default) propagates worker exceptions;
         #                           +:skip+ records the failure and continues with remaining tasks
+        # @api public
         def pool(size:, agent:, on_error: :raise)
           @pool_size = Integer(size)
           @worker_agent = agent
@@ -98,6 +106,7 @@ module Phronomy
         #
         # @yield [Array<WorkerState>] available workers
         # @yieldreturn [WorkerState] the chosen worker
+        # @api public
         def schedule(&block)
           @scheduler = block
         end
@@ -108,6 +117,7 @@ module Phronomy
         # When omitted, the raw assignments array is returned.
         #
         # @yield [Array<Hash>] all completed (and skipped) task assignments
+        # @api public
         def aggregate(&block)
           @aggregator = block
         end
@@ -137,6 +147,7 @@ module Phronomy
       # @param config     [Hash]         reserved for future use
       # @return [Object] the return value of the aggregate block, or the raw assignments Array
       # @raise [ArgumentError] when +pool :agent+ has not been configured
+      # @api public
       def invoke(team_input, config: {})
         raise ArgumentError, "pool :agent must be configured before invoking" unless self.class._worker_agent
 
@@ -161,6 +172,7 @@ module Phronomy
       # @yield [Hash] one event per completed/failed task
       # @return [Object] same as +invoke+
       # @raise [ArgumentError] when +pool :agent+ has not been configured
+      # @api public
       def stream(team_input, config: {}, &block)
         return invoke(team_input, config: config) unless block