phronomy 0.6.0 → 0.7.1

data/lib/phronomy/agent/orchestrator.rb

@@ -55,14 +55,36 @@ 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}"
           description "Dispatch work to the #{name} subagent (#{agent_class.name})"
           param :input, type: :string, desc: "The task or question for the subagent"
 
+          # @_orchestrator_context is injected at call time by prepare_tool_class.
+          attr_writer :_orchestrator_context
+
           define_method(:execute) do |input:|
-            result = agent_class.new.invoke(input)
+            # Inherit the calling orchestrator's thread_id, config, and
+            # InvocationContext so that child subagent spans and memory stay
+            # connected to the parent invocation.
+            ctx = @_orchestrator_context || {}
+            parent_ic = ctx[:invocation_context]
+            task_config = ctx[:config] || {}
+
+            # Propagate parent InvocationContext to the child agent so that
+            # cancellation, deadline, and tracing carry through automatically.
+            if parent_ic && !task_config[:invocation_context]
+              child_ic = parent_ic.merge(parent_task_id: parent_ic.task_id)
+              task_config = task_config.merge(invocation_context: child_ic)
+            end
+
+            result = agent_class.new.invoke_async(
+              input,
+              thread_id: ctx[:thread_id] || parent_ic&.thread_id,
+              config: task_config
+            ).await
             result[:output]
           rescue
             raise if on_error == :raise
@@ -70,6 +92,9 @@ module Phronomy
           end
         end
 
+        # Track this tool class so prepare_tool_class can inject context.
+        @_subagent_tool_classes = (@_subagent_tool_classes || []) + [tool_class]
+
         # Append without clobbering previously registered tools or aliases.
         @tools = (@tools || []) + [tool_class]
         @tool_aliases ||= {}
@@ -77,15 +102,24 @@ module Phronomy
         registered_subagents[name] = {agent_class: agent_class, on_error: on_error}
       end
 
+      # Returns the subagent tool classes registered on this specific class.
+      # Used by {#prepare_tool_class} to inject context.
+      # @return [Array<Class>]
+      # @api private
+      def self._subagent_tool_classes
+        @_subagent_tool_classes || []
+      end
+
       # Returns the subagent registry for this specific class (not inherited).
       #
       # @return [Hash{Symbol => Hash}]
+      # @api public
       def self.registered_subagents
         @registered_subagents ||= {}
       end
 
-      # Dispatches multiple heterogeneous agent tasks in parallel using Ruby
-      # threads. Each task is a Hash describing one agent invocation.
+      # Dispatches multiple heterogeneous agent tasks in parallel using
+      # cooperative {Task}s. Each task is a Hash describing one agent invocation.
       #
       # Results are returned in the same order as the input +tasks+ array.
       # Concurrency is bounded by +max_concurrency+; when nil all tasks run at
@@ -93,20 +127,35 @@ module Phronomy
       #
       # 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.
+      #   exception in input order is then re-raised in the calling task.
       # - +: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;
+      # @option task [String]  :thread_id forwarded to +agent#invoke+ (default: nil)
+      # @param max_concurrency    [Integer, nil] maximum number of concurrent tasks;
       #   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 tasks;
+      #   nil means wait indefinitely. When the deadline is exceeded,
+      #   {Phronomy::TimeoutError} is raised and all surviving tasks are cancelled
+      #   cooperatively.
+      # @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 child agent checks it before making LLM calls.
+      # @param invocation_context [Phronomy::InvocationContext, nil] when provided,
+      #   the context (cancellation_token, deadline, thread_id) is propagated to each
+      #   child agent as a child InvocationContext.
+      # @param force_kill [Boolean] deprecated — cooperative cancellation is always
+      #   used; this parameter is accepted for backwards compatibility but has no effect.
       # @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, invocation_context: nil, force_kill: false)
         unless [:raise, :skip].include?(on_error)
           raise ArgumentError, "unknown on_error: #{on_error.inspect}"
         end
@@ -114,7 +163,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, invocation_context: invocation_context, force_kill: force_kill)
       end
 
       # Runs the same agent against multiple inputs in parallel (fan-out pattern).
@@ -125,70 +174,158 @@ 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 max_concurrency [Integer, nil]  forwarded to {#dispatch_parallel}
-      # @param on_error        [Symbol]        forwarded to {#dispatch_parallel}
+      # @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}
+      # @param invocation_context [Phronomy::InvocationContext, nil] forwarded to
+      #   {#dispatch_parallel} for child context propagation
       # @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, invocation_context: 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,
+          invocation_context: invocation_context,
+          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 = @_orchestrator_context || {}
+        parent_ic = ctx[:invocation_context]
+        effective_config = config || ctx[:config] || {}
+
+        # Propagate parent InvocationContext to the child agent.
+        if parent_ic && !effective_config[:invocation_context]
+          child_ic = parent_ic.merge(parent_task_id: parent_ic.task_id)
+          effective_config = effective_config.merge(invocation_context: child_ic)
+        end
+
+        agent_class.new.invoke_async(
+          input,
+          config: effective_config,
+          thread_id: thread_id || ctx[:thread_id] || parent_ic&.thread_id
+        ).await
+      end
+
       private
 
-      # Worker-pool implementation shared by {#dispatch_parallel} and {#fan_out}.
+      # Override invoke_once to expose the current thread_id and config via an
+      # instance variable so that DSL-registered subagent tools can inherit them
+      # without using Thread.current.
+      def invoke_once(input, messages: [], thread_id: nil, config: {})
+        prev = @_orchestrator_context
+        @_orchestrator_context = {
+          thread_id: thread_id,
+          config: config,
+          invocation_context: config[:invocation_context]
+        }
+        super
+      ensure
+        @_orchestrator_context = prev
+      end
+
+      # Override prepare_tool_class to inject the current orchestrator context
+      # into DSL-registered subagent tools before each call.
+      def prepare_tool_class(tool_class)
+        prepared = super
+        orch = self
+
+        # Only wrap subagent tools (those registered via the .subagent DSL).
+        return prepared unless self.class._subagent_tool_classes.include?(tool_class)
+
+        # Capture the effective tool name before building the anonymous subclass.
+        # Class-level instance variables (@tool_name) are not inherited through
+        # subclassing, so the wrapper must set it explicitly.
+        effective_name = prepared.new.name
+        Class.new(prepared) do
+          tool_name effective_name
+          define_method(:call) do |args|
+            self._orchestrator_context = orch.instance_variable_get(:@_orchestrator_context)
+            super(args)
+          end
+        end
+      end
+
+      # Task-based worker pool shared by {#dispatch_parallel} and {#fan_out}.
+      #
+      # Spawns one {Task} per input using a {TaskGroup} so that +max_concurrency+
+      # acts as a semaphore: spare tasks block on {TaskGroup#spawn} until a slot
+      # becomes available.  Results are written back to +results+ in input order;
+      # +errors+ captures the first error per position so that the first error in
+      # *input* order is deterministically re-raised when +on_error: :raise+ is used.
       #
-      # 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.
+      # When +timeout+ is given, each spawned task is joined with the remaining
+      # deadline.  Any still-alive tasks are cancelled cooperatively via
+      # {TaskGroup#cancel_all!} before {Phronomy::TimeoutError} is raised.
+      # The +force_kill+ argument is deprecated: cooperative cancellation is always
+      # used regardless of its value.
       #
-      # +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:)
+      # Deadline tracking uses +Process.clock_gettime(Process::CLOCK_MONOTONIC)+
+      # to avoid sensitivity to NTP adjustments and system-clock changes.
+      def bounded_map(tasks, max_concurrency:, on_error:, timeout: nil, cancellation_token: nil, invocation_context: nil, force_kill: false) # rubocop:disable Lint/UnusedMethodArgument
         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
+        group = Phronomy::Runtime.instance.task_group(limit: max_concurrency || tasks.length)
+
+        # Resolve the effective cancellation token: explicit argument wins;
+        # fall back to the one embedded in the InvocationContext if present.
+        effective_ct = cancellation_token || invocation_context&.cancellation_token
+
+        spawned = tasks.each_with_index.map do |task, i|
+          group.spawn do
+            task_config = task.fetch(:config, {})
+
+            # Merge the shared cancellation token unless the task already has one.
+            if effective_ct && !task_config[:cancellation_token]
+              task_config = task_config.merge(cancellation_token: effective_ct)
+            end
+
+            # Propagate parent InvocationContext to each child task so that
+            # cancellation, deadline, and tracing carry through automatically.
+            if invocation_context && !task_config[:invocation_context]
+              child_ic = invocation_context.merge(parent_task_id: invocation_context.task_id)
+              task_config = task_config.merge(invocation_context: child_ic)
             end
+
+            results[i] = task[:agent].new.invoke_async(
+              task[:input],
+              config: task_config,
+              thread_id: task[:thread_id] || invocation_context&.thread_id
+            ).await
+          rescue => e
+            errors[i] = e unless on_error == :skip
           end
         end
 
-        workers.each(&:join)
+        if timeout
+          deadline = Phronomy::Deadline.in(timeout)
+          spawned.each { |t| t.join([deadline.remaining_seconds, 0].max) }
+
+          alive = spawned.select(&:alive?)
+          unless alive.empty?
+            group.cancel_all!
+            raise Phronomy::TimeoutError,
+              "dispatch_parallel timed out after #{timeout}s " \
+              "(#{alive.length} of #{spawned.length} tasks still running)"
+          end
+        else
+          spawned.each(&:await)
+        end
 
         first_error = errors.compact.first
         raise first_error if first_error

data/lib/phronomy/agent/parallel_tool_chat.rb

@@ -5,20 +5,39 @@ module Phronomy
     # 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.).
+    # tool is dispatched according to its +execution_mode+:
+    # - +:cooperative+ tools run via +Runtime.instance.spawn+, delegating
+    #   scheduling to the configured runtime backend.
+    # - +:blocking_io+ tools are offloaded to a +BlockingAdapterPool+ worker
+    #   thread so they do not occupy a scheduler task slot.
+    # All results are collected before being appended to the message history,
+    # preserving 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.
+    # This class is used automatically when EventLoop mode is enabled
+    # ({Phronomy.configuration.event_loop}).  It is not used for direct
+    # synchronous +invoke+ calls so that the streaming callback state remains
+    # single-threaded.
+    # @api private
     class ParallelToolChat < RubyLLM::Chat
+      # @param max_parallel_tools [Integer] maximum simultaneous tool executions
+      # @param cancellation_token [Phronomy::CancellationToken, nil] token observed before each batch
+      # @param opts [Hash] remaining kwargs forwarded to RubyLLM::Chat
+      # @api private
+      def initialize(max_parallel_tools: 10, cancellation_token: nil, **opts)
+        super(**opts)
+        @max_parallel_tools = max_parallel_tools
+        @cancellation_token = cancellation_token
+      end
+
+      # Allows the owning agent to update the token between retries.
+      # @api private
+      attr_writer :cancellation_token
+
       private
 
       # Overrides RubyLLM::Chat#handle_tool_calls to parallelise execution
@@ -28,12 +47,14 @@ module Phronomy
       #   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.
+      #   2. Parallel tool execution — cooperative tools via Runtime.instance.spawn
+      #      (respects the configured runtime backend), blocking_io tools via BlockingAdapterPool.
       #   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+
+      # @api private
       def handle_tool_calls(response, &block)
         tool_calls = response.tool_calls.values
 
@@ -50,14 +71,48 @@ 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)} }
+        # :cooperative tools run inside a Task (no pool).
+        # :blocking_io/:cpu_bound/:external_process tools are submitted directly
+        # to BlockingAdapterPool when available — eliminating the extra Task
+        # Thread that previously wrapped each pool operation.
+        #
+        # Both Phronomy::Task and BlockingAdapterPool::PendingOperation support
+        # #await, so results are collected uniformly below.
+        ct = @cancellation_token
+        max = @max_parallel_tools
+        tool_results = tool_calls.each_slice(max).flat_map do |batch|
+          if ct&.cancelled?
+            raise Phronomy::CancellationError, "invocation cancelled before tool execution"
+          end
+
+          # Dispatch all tools in this batch via ToolExecutor (centralised routing).
+          dispatched = batch.map do |tc|
+            tool = tools[tc.name.to_sym]
+            unless tool
+              next {tool_call: tc, awaitable: nil, result: {
+                error: "Model tried to call unavailable tool `#{tc.name}`. " \
+                       "Available tools: #{tools.keys.to_json}."
+              }}
+            end
+
+            awaitable = Phronomy::ToolExecutor.call_async(
+              tool: tool,
+              args: tc.arguments,
+              cancellation_token: ct
+            )
+            {tool_call: tc, awaitable: awaitable, result: nil}
+          end
+
+          # Await all dispatched operations in original order.
+          dispatched.map do |item|
+            result = item[:awaitable] ? item[:awaitable].await : item[:result]
+            {tool_call: item[:tool_call], result: result}
+          end
         end
-        results = thread_results.map(&:value)
 
         # Phase 3 — post-execution callbacks and message recording (sequential).
         halt_result = nil
-        results.each do |item|
+        tool_results.each do |item|
           result = item[:result]
           @on[:tool_result]&.call(result)
           tool_payload = result.is_a?(RubyLLM::Tool::Halt) ? result.content : result
@@ -70,6 +125,25 @@ module Phronomy
         reset_tool_choice if forced_tool_choice?
         halt_result || complete(&block)
       end
+
+      # Overrides RubyLLM::Chat#execute_tool to forward the cancellation token
+      # explicitly and to route the call through {ToolExecutor} so that the
+      # execution_mode decision is made in a single place.
+      def execute_tool(tool_call)
+        tool = tools[tool_call.name.to_sym]
+        unless tool
+          return {
+            error: "Model tried to call unavailable tool `#{tool_call.name}`. " \
+                   "Available tools: #{tools.keys.to_json}."
+          }
+        end
+
+        Phronomy::ToolExecutor.call_async(
+          tool: tool,
+          args: tool_call.arguments,
+          cancellation_token: @cancellation_token
+        ).await
+      end
     end
   end
 end

data/lib/phronomy/agent/react_agent.rb

@@ -13,6 +13,10 @@ module Phronomy
         caller_meta = {}
         caller_meta[:user_id] = config[:user_id] if config[:user_id]
         caller_meta[:session_id] = config[:session_id] if config[:session_id]
+        if (ic = config[:invocation_context])
+          caller_meta[:task_id] = ic.task_id if ic.task_id
+          caller_meta[:parent_task_id] = ic.parent_task_id if ic.parent_task_id
+        end
 
         trace("agent.invoke", input: input, **caller_meta) do |_span|
           # Run input guardrails before any LLM interaction.
@@ -37,9 +41,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,12 +65,17 @@ 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
 
         caller_meta = {}
         caller_meta[:user_id] = config[:user_id] if config[:user_id]
         caller_meta[:session_id] = config[:session_id] if config[:session_id]
+        if (ic = config[:invocation_context])
+          caller_meta[:task_id] = ic.task_id if ic.task_id
+          caller_meta[:parent_task_id] = ic.parent_task_id if ic.parent_task_id
+        end
 
         trace("agent.invoke", input: input, **caller_meta) do |_span|
           run_input_guardrails!(input)
@@ -88,9 +98,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