phronomy 0.16.0 → 0.17.0

data/lib/phronomy/llm_context_window/token_budget.rb

@@ -2,96 +2,25 @@
 
 module Phronomy
   module LlmContextWindow
-    # Raised when a model name is not found in the RubyLLM model registry and
-    # no explicit context_window was provided.
-    class UnknownModelError < Phronomy::Error; end
-
-    # Calculates the effective token budget available for conversation history
-    # and injected knowledge within a single LLM request.
-    #
-    # The window is divided as follows:
-    #
-    #   context_window (total)
-    #   ├─ max_output_tokens  (reserved for model output = max_output_tokens)
-    #   ├─ overhead           (reserved for system prompt + tool definitions)
-    #   └─ effective_input_limit  (available for memory + knowledge)
-    #
-    # @example Auto-derive from RubyLLM model registry
-    #   budget = Phronomy::LlmContextWindow::TokenBudget.new(model: "claude-3-5-sonnet-20241022")
-    #
-    # @example Explicit values (useful for local / unknown models)
-    #   budget = Phronomy::LlmContextWindow::TokenBudget.new(
-    #     context_window:    32_768,
-    #     max_output_tokens: 4_096
-    #   )
-    #
-    # @example With overhead for instructions + tool definitions
-    #   budget = Phronomy::LlmContextWindow::TokenBudget.new(
-    #     model:    "gpt-4o",
-    #     overhead: 800
-    #   )
+    # Immutable arithmetic value for one resolved model context budget.
+    # Model-registry lookup belongs to Agent::TokenBudgetResolver.
     class TokenBudget
-      # @return [Integer] total token limit of the model
-      attr_reader :context_window
-
-      # @return [Integer] tokens reserved for model output
-      attr_reader :max_output_tokens
+      attr_reader :context_window, :max_output_tokens
 
-      # @return [Integer] tokens reserved for instructions and tool definitions
-      attr_reader :overhead
-
-      # @param model             [String, nil]  model identifier looked up in RubyLLM
-      # @param context_window    [Integer, nil] explicit total token limit
-      # @param max_output_tokens [Integer, nil] explicit output reservation; when nil
-      #                                         and model is given, uses max_output_tokens
-      # @param overhead          [Integer]      tokens reserved for instructions/tools
       # @api private
-      # mutant:disable - multiple genuine equivalent mutations: overhead/context_window/max_output_tokens .to_i vs .to_int vs Integer() vs omitted are equivalent for Integer inputs; (max_output_tokens||0).to_i vs (max_output_tokens).to_i and (||nil).to_i are genuine because nil.to_i==0; overhead:nil default is genuine because nil.to_i==0
-      def initialize(model: nil, context_window: nil, max_output_tokens: nil, overhead: 0)
-        @overhead = overhead.to_i
-
-        if context_window
-          # Explicit values — no registry lookup needed.
-          @context_window = context_window.to_i
-          @max_output_tokens = (max_output_tokens || 0).to_i
-        elsif model
-          ruby_llm_model = lookup_model!(model)
-          @context_window = ruby_llm_model.context_window.to_i
-          @max_output_tokens = (max_output_tokens || ruby_llm_model.max_output_tokens).to_i
-        else
-          raise ArgumentError, "Provide either model: or context_window:"
-        end
+      def initialize(context_window:, max_output_tokens:)
+        @context_window = Integer(context_window)
+        @max_output_tokens = Integer(max_output_tokens)
       end
 
-      # Tokens available for conversation history and knowledge after reservations.
-      # Always >= 0.
-      #
-      # @return [Integer]
       # @api private
       def effective_input_limit
-        [@context_window - @max_output_tokens - @overhead, 0].max
+        [@context_window - @max_output_tokens, 0].max
       end
 
-      # Tokens still available after `used` tokens have been allocated.
-      #
-      # @param used [Integer] tokens already committed (e.g. from knowledge injection)
-      # @return [Integer] remaining tokens (always >= 0)
       # @api private
-      # mutant:disable - used.to_i vs used vs used.to_int vs Integer(used) are genuine equivalents when used is an Integer; used:nil default is genuine because nil.to_i==0==default 0
       def available(used: 0)
-        [effective_input_limit - used.to_i, 0].max
-      end
-
-      private
-
-      # mutant:disable - raise(UnknownModelError) and raise(UnknownModelError,nil) and raise(UnknownModelError,"Model '#{nil}' not found") in both branches are genuine equivalents (spec checks exception class only, not message text)
-      def lookup_model!(model_name)
-        found = RubyLLM.models.find(model_name)
-        raise UnknownModelError, "Model '#{model_name}' not found in RubyLLM registry" unless found
-
-        found
-      rescue RubyLLM::ModelNotFoundError
-        raise UnknownModelError, "Model '#{model_name}' not found in RubyLLM registry"
+        [effective_input_limit - Integer(used), 0].max
       end
     end
   end

data/lib/phronomy/multi_agent/orchestrator.rb

@@ -3,85 +3,39 @@
 module Phronomy
   module MultiAgent
     # Base class for orchestrator agents that coordinate multiple subagents.
-    # Implements the Orchestrator-Subagent multi-agent coordination pattern
-    # (Anthropic blog, Pattern 2).
-    #
-    # @see https://claude.com/blog/multi-agent-coordination-patterns
-    #
-    # Extends {Phronomy::Agent::Base} with:
-    # - A +subagent+ class-level DSL for declarative subagent registration. Each
-    #   declared subagent is automatically exposed as an LLM-callable tool.
-    # - +dispatch_parallel+ for programmatic parallel invocation of heterogeneous
-    #   agents.
-    # - +fan_out+ for parallel invocation of the same agent across multiple inputs.
-    #
-    # @example Declarative DSL
-    #   class ResearchOrchestrator < Phronomy::MultiAgent::Orchestrator
-    #     model "gpt-4o"
-    #     instructions "You coordinate research tasks."
-    #     subagent :searcher,   SearchAgent
-    #     subagent :summarizer, SummaryAgent
-    #   end
-    #
-    #   result = ResearchOrchestrator.new.invoke("Research the latest AI news.")
-    #
-    # @example Programmatic parallel dispatch
-    #   class MyOrchestrator < Phronomy::MultiAgent::Orchestrator
-    #     model "gpt-4o"
-    #     instructions "Dispatch tasks in parallel."
-    #
-    #     def run(input)
-    #       results = dispatch_parallel(
-    #         { agent: SearchAgent,   input: "topic A" },
-    #         { agent: AnalysisAgent, input: input }
-    #       )
-    #       results.map { |r| r[:output] }.join("\n")
-    #     end
-    #   end
-    #
-    # @example Fan-out (same agent, multiple inputs)
-    #   results = fan_out(agent: TranslationAgent, inputs: ["Hello", "World"])
     class Orchestrator < Agent::Base
       agent_definition id: "orchestrator", version: 1
-      # Declares a named subagent and registers it as a tool accessible to the
-      # LLM during an +invoke+ call.
-      #
-      # Each call appends a new tool to this class's tool list.  The generated
-      # tool's function name is +dispatch_to_<name>+.  When the LLM calls the
-      # tool, a fresh instance of +agent_class+ is created and +invoke+ is called
-      # with the provided input string.
-      #
-      # @param name        [Symbol] logical name that identifies the subagent
-      # @param agent_class [Class]  subclass of {Phronomy::Agent::Base}
-      # @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)
+      def self.subagent(name, agent_class, on_error: :raise, inherit_knowledge: true)
         tool_class = Class.new(Phronomy::Agent::Context::Capability::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:|
-            # 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(
+            agent = agent_class.new
+            if inherit_knowledge
+              Array(ctx[:knowledge]).each do |entry|
+                agent.add_knowledge(
+                  entry.fetch(:content),
+                  metadata: entry.fetch(:metadata, {})
+                )
+              end
+            end
+
+            result = agent.invoke_async(
               input,
               thread_id: ctx[:thread_id] || parent_ic&.thread_id,
               config: task_config
@@ -93,229 +47,223 @@ 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 ||= {}
-
-        registered_subagents[name] = {agent_class: agent_class, on_error: on_error}
+        registered_subagents[name] = {
+          agent_class: agent_class,
+          on_error: on_error,
+          inherit_knowledge: inherit_knowledge
+        }
       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
-      # 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
-      # once (original behaviour).
-      #
-      # 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 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: +{}+)
-      # @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 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::Concurrency::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
-      # @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)
+      def dispatch_parallel(
+        *tasks,
+        max_concurrency: nil,
+        on_error: :raise,
+        timeout: nil,
+        cancellation_token: nil,
+        invocation_context: nil,
+        inherit_knowledge: true
+      )
+        unless %i[raise skip].include?(on_error)
           raise ArgumentError, "unknown on_error: #{on_error.inspect}"
         end
         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, timeout: timeout, cancellation_token: cancellation_token, invocation_context: invocation_context, force_kill: force_kill)
+        bounded_map(
+          tasks,
+          max_concurrency: max_concurrency,
+          on_error: on_error,
+          timeout: timeout,
+          cancellation_token: cancellation_token,
+          invocation_context: invocation_context,
+          inherit_knowledge: inherit_knowledge
+        )
       end
 
-      # Runs the same agent against multiple inputs in parallel (fan-out pattern).
-      #
-      # 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 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+
       # @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)
+      def fan_out(
+        agent:,
+        inputs:,
+        config: {},
+        thread_id: nil,
+        max_concurrency: nil,
+        on_error: :raise,
+        timeout: nil,
+        cancellation_token: nil,
+        invocation_context: nil,
+        inherit_knowledge: true
+      )
         dispatch_parallel(
-          *inputs.map { |input| {agent: agent, input: input, config: config, thread_id: thread_id} },
+          *inputs.map do |input|
+            {agent: agent, input: input, config: config, thread_id: thread_id}
+          end,
           max_concurrency: max_concurrency,
           on_error: on_error,
           timeout: timeout,
           cancellation_token: cancellation_token,
           invocation_context: invocation_context,
-          force_kill: force_kill
+          inherit_knowledge: inherit_knowledge
         )
       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+)
+      # Programmatic single-subagent dispatch. Context propagation is explicit:
+      # pass invocation_context in +config+ when this call must inherit a parent.
+      # Active parent Knowledge is inherited by default; pass
+      # +inherit_knowledge: false+ to create an isolated subagent.
       # @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(
+      def subagent(
+        agent_class,
+        input,
+        config: nil,
+        thread_id: nil,
+        inherit_knowledge: true
+      )
+        build_subagent(
+          agent_class,
+          inherit_knowledge: inherit_knowledge
+        ).invoke_async(
           input,
-          config: effective_config,
-          thread_id: thread_id || ctx[:thread_id] || parent_ic&.thread_id
+          config: config || {},
+          thread_id: thread_id
         ).wait_result
       end
 
       private
 
-      # 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)
+      # Capture the current invocation directly while materializing Tool classes.
+      # No legacy invoke_once/thread-local bridge is involved.
+      def prepare_tool_class(tool_class, invocation: nil)
         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.
+        subagent_name = tool_class.tool_name.delete_prefix("dispatch_to_")
+        registration = self.class.registered_subagents.find do |name, _|
+          name.to_s == subagent_name
+        end&.last
+        inherits_knowledge = registration ? registration.fetch(:inherit_knowledge, true) : true
+
+        captured_context = {}
+        captured_context[:knowledge] = active_knowledge_snapshot if inherits_knowledge
+        if invocation
+          captured_context.merge!(
+            thread_id: invocation.thread_id,
+            config: invocation.config,
+            invocation_context: invocation.config[:invocation_context]
+          )
+        end
+        captured_context.freeze
+
         effective_name = prepared.new.name
         Class.new(prepared) do
           tool_name effective_name
           define_method(:call) do |args, **kwargs|
-            self._orchestrator_context = orch.instance_variable_get(:@_orchestrator_context)
+            self._orchestrator_context = captured_context
             super(args, **kwargs)
           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.
-      #
-      # 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.
-      #
-      # 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
+      def active_knowledge_snapshot
+        journal_projection.context_records.filter_map do |record|
+          next unless record.kind == :knowledge
+
+          {
+            content: persistence.contents.fetch_text(record.content_ref),
+            metadata: (record.metadata || {}).dup.freeze
+          }.freeze
+        end.freeze
+      end
+
+      def build_subagent(
+        agent_class,
+        inherit_knowledge: true,
+        knowledge_snapshot: nil
+      )
+        agent = agent_class.new
+        return agent unless inherit_knowledge
+
+        snapshot = knowledge_snapshot || active_knowledge_snapshot
+        snapshot.each do |entry|
+          agent.add_knowledge(
+            entry.fetch(:content),
+            metadata: entry.fetch(:metadata, {})
+          )
+        end
+        agent
+      end
+
+      def bounded_map(
+        tasks,
+        max_concurrency:,
+        on_error:,
+        timeout: nil,
+        cancellation_token: nil,
+        invocation_context: nil,
+        inherit_knowledge: true
+      )
         return [] if tasks.empty?
 
+        inheritance_flags = tasks.map do |task|
+          task.fetch(:inherit_knowledge, inherit_knowledge)
+        end
+        knowledge_snapshot = active_knowledge_snapshot if inheritance_flags.any?
+
         results = Array.new(tasks.length)
         errors = Array.new(tasks.length)
-        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.
+        group = Phronomy::Runtime.instance.task_group(
+          limit: max_concurrency || tasks.length
+        )
         effective_ct = cancellation_token || invocation_context&.cancellation_token
 
-        spawned = tasks.each_with_index.map do |task, i|
+        spawned = tasks.each_with_index.map do |task, index|
           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)
+              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_inherits_knowledge = inheritance_flags[index]
+            agent = build_subagent(
+              task[:agent],
+              inherit_knowledge: task_inherits_knowledge,
+              knowledge_snapshot: knowledge_snapshot
+            )
+
+            results[index] = agent.invoke_async(
               task[:input],
               config: task_config,
               thread_id: task[:thread_id] || invocation_context&.thread_id
             ).wait_result
-          rescue => e
-            errors[i] = e unless on_error == :skip
+          rescue => error
+            errors[index] = error unless on_error == :skip
           end
         end
 
         if timeout
           deadline = Phronomy::Concurrency::Deadline.in(timeout)
-          spawned.each { |t| t.join([deadline.remaining_seconds, 0].max) }
+          spawned.each { |task| task.join([deadline.remaining_seconds, 0].max) }
 
           alive = spawned.select(&:alive?)
           unless alive.empty?