phronomy 0.26.0 → 0.27.0

data/lib/phronomy/{agent.rb → agent/composition/run_once.rb}

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
+# This convenience API composes a fresh ephemeral Persistence with an Agent.
+# The application entry loads the method definition; Agent execution does not
+# delegate to or require this higher-level composition implementation.
 module Phronomy
   module Agent
-    StreamEvent = Data.define(:type, :payload)
-
     def self.run_once(
       definition:,
       input:,
@@ -17,7 +18,7 @@ module Phronomy
         raise ArgumentError, "Provide either on_event: or a block, not both"
       end
 
-      persistence = Phronomy::Persistence::InMemory.new
+      persistence = Phronomy::Persistence.in_memory
       agent = definition.create(
         context: context,
         knowledge: knowledge,
@@ -29,13 +30,3 @@ module Phronomy
     end
   end
 end
-
-require_relative "agent/async_event_api"
-
-unless Phronomy::Agent::Base < Phronomy::Agent::AsyncEventApi
-  Phronomy::Agent::Base.prepend(Phronomy::Agent::AsyncEventApi)
-end
-
-# Durable Agent Recovery and Agent-incarnation event binding.
-require_relative "agent/recovery_support"
-require_relative "agent/recovery_coordinator"

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

@@ -1,15 +1,19 @@
 # frozen_string_literal: true
 
+require_relative "../../../engine/concurrency/worker_input_restricted"
+
 module Phronomy
   module Agent
     module Context
       module Capability
         # Base class extending RubyLLM::Tool with Phronomy-specific DSL.
         class Base < RubyLLM::Tool
+          include Phronomy::Concurrency::WorkerInputRestricted
+
           class << self
             # @api public
             def tool_name(value = nil)
-              return @tool_name if value.nil?
+              return @tool_name || super() if value.nil?
 
               @tool_name = value.to_s
             end
@@ -30,41 +34,62 @@ module Phronomy
             end
             alias_method :desc, :description
 
-            # RubyLLM stores declared parameters in a class-instance variable.
-            # Copy the parent's registry on first access so child classes inherit
-            # existing parameters while remaining free to add their own.
+            # Phronomy declarations inherit through anonymous Tool decorators.
+            # RubyLLM owns schema construction and provider request rendering.
+            # @api public
+            def declared_parameters
+              return @declared_parameters if instance_variable_defined?(:@declared_parameters)
+
+              @declared_parameters = superclass.declared_parameters.dup
+            end
+
+            # Keep Phronomy's parameter reader and support RubyLLM's schema DSL.
             # @api public
-            def parameters
-              return @parameters if instance_variable_defined?(:@parameters)
+            def parameters(schema = :__phronomy_read__, &block)
+              return declared_parameters if schema == :__phronomy_read__ && !block
 
-              parent = superclass.respond_to?(:parameters) ? superclass.parameters : {}
-              @parameters = parent.dup
+              super((schema == :__phronomy_read__) ? nil : schema, &block)
+            end
+
+            # @api public
+            def parameters_schema_definition
+              return @parameters_schema_definition if instance_variable_defined?(:@parameters_schema_definition)
+
+              superclass.parameters_schema_definition
             end
 
-            # RubyLLM stores an explicit .params schema definition in a
-            # class-instance variable. Readers must fall back to the parent.
             # @api public
             def params_schema_definition
-              return @params_schema_definition if instance_variable_defined?(:@params_schema_definition)
-              return superclass.params_schema_definition if superclass.respond_to?(:params_schema_definition)
+              parameters_schema_definition
+            end
 
-              nil
+            # @api public
+            def params(schema = nil, &block)
+              parameters(schema, &block)
+            end
+
+            # @api public
+            def provider_options(options = :__phronomy_read__)
+              return super unless options == :__phronomy_read__
+              return @provider_options if instance_variable_defined?(:@provider_options)
+
+              @provider_options = duplicate_configuration(superclass.provider_options)
             end
 
-            # RubyLLM provider params are also class-instance state. Copy them on
-            # first access to preserve inheritance without sharing the top-level
-            # mutable Hash between parent and child.
             # @api public
             def provider_params
-              return @provider_params if instance_variable_defined?(:@provider_params)
+              provider_options
+            end
 
-              parent = superclass.respond_to?(:provider_params) ? superclass.provider_params : {}
-              @provider_params = duplicate_configuration(parent)
+            # @api public
+            def with_params(**options)
+              provider_options(options)
             end
 
             # @api public
-            def param(name, enum: nil, properties: nil, **options)
-              super(name, **options)
+            def param(name, enum: nil, properties: nil, desc: nil, **options)
+              options[:description] = desc if desc
+              parameter(name, **options)
               param_enums[name] = duplicate_configuration(enum) if enum
               param_schemas[name] = normalize_nested_schema(properties) if properties
             end
@@ -175,8 +200,8 @@ module Phronomy
                 end
                 @requires_approval = block
               elsif value == :__unset__
-                return @requires_approval if instance_variable_defined?(:@requires_approval)
-                return superclass.requires_approval if superclass.respond_to?(:requires_approval)
+                return @requires_approval unless @requires_approval.nil?
+                return superclass.requires_approval if superclass < RubyLLM::Tool
 
                 false
               else
@@ -225,7 +250,7 @@ module Phronomy
             self.class.tool_name || super
           end
 
-          def params_schema
+          def parameters_schema
             schema = super
             return schema if schema.nil?
 
@@ -264,6 +289,22 @@ module Phronomy
             schema
           end
 
+          # Phronomy retains these readers as part of its Tool contract.
+          # @api public
+          def params_schema
+            parameters_schema
+          end
+
+          # @api public
+          def provider_params
+            provider_options
+          end
+
+          # @api public
+          def parameters
+            self.class.declared_parameters
+          end
+
           # @api public
           def call(args, cancellation_token: nil)
             cancellation_token&.raise_if_cancelled!
@@ -281,7 +322,7 @@ module Phronomy
             if cancellation_token && execute_accepts_cancellation_token?
               validated_args = validated_args.merge(cancellation_token: cancellation_token)
             end
-            result = super(validated_args)
+            result = super(**(validated_args || {}).transform_keys(&:to_sym))
             truncate_result_if_needed(result)
           rescue Phronomy::ToolError, Phronomy::CancellationError
             raise
@@ -307,7 +348,7 @@ module Phronomy
             cancellation_token: nil,
             config: {}
           )
-            Phronomy::Agent::ToolExecutor.call_async(
+            Phronomy::Agent::Context::Capability::ToolExecutor.call_async(
               tool: self,
               args: args,
               cancellation_token: cancellation_token,

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Context
+      module Capability
+        # Routes Tool work according to the Tool execution contract.
+        #
+        # Both execution modes return {Phronomy::TaskResult}; only the execution mechanism
+        # differs.
+        #
+        # :cooperative Tool calls execute inline and must return quickly. call_async
+        # wraps their result in an already-settled TaskResult and never consumes an
+        # OffloadPool worker.
+        #
+        # :offloaded Tool calls route synchronous work through OffloadPool, whose
+        # caller-facing completion handle is also a TaskResult. Phronomy does not distinguish
+        # whether the reason is blocking I/O, CPU-bound work, or another long
+        # synchronous operation.
+        #
+        # @api private
+        module ToolExecutor
+          # @api private
+          def self.call_async(
+            tool:,
+            args:,
+            cancellation_token: nil,
+            config: {},
+            runtime: nil,
+            on_full: :raise
+          )
+            mode = tool.class.execution_mode
+
+            case mode
+            when :cooperative
+              task = Phronomy::TaskResult.deferred(name: "tool-#{tool.name}")
+              begin
+                task.complete(
+                  tool.call(args, cancellation_token: cancellation_token)
+                )
+              rescue => error
+                task.fail(error)
+              end
+              task
+            when :offloaded
+              runtime ||= Phronomy::Runtime.instance
+              runtime.offload.submit(
+                cancellation_token: cancellation_token,
+                on_full: on_full
+              ) do
+                tool.call(args, cancellation_token: cancellation_token)
+              end
+            else
+              raise Phronomy::ConfigurationError,
+                "unknown Tool execution_mode: #{mode.inspect}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/{context_assembler.rb → context_assembly/context_assembler.rb}

@@ -3,7 +3,7 @@
 module Phronomy
   module Agent
     class ContextAssembler
-      ASSEMBLY_POLICY_VERSION = 8
+      ASSEMBLY_POLICY_VERSION = 9
       SEGMENT_ORIGIN_METADATA_KEY = "phronomy_origin"
       POLICY_ORIGIN_METADATA_KEY = "context_policy_origin"
       POLICY_ITEM_ID_METADATA_KEY = "context_policy_item_id"
@@ -59,81 +59,33 @@ module Phronomy
         excluded = [execution.metadata["current_input_record_id"]].compact
         handoff_context = config[:phronomy_handoff_context]
 
-        instructions = []
-        unless system_text.to_s.empty?
-          instructions << ContextPolicyInput::InstructionItem.new(
-            id: "instruction:agent:#{execution.execution_id}:1",
-            kind: :instruction,
-            role: :system,
-            content: system_text.to_s,
-            content_format: :text,
-            estimated_tokens: estimate_value(system_text.to_s),
-            required: true,
-            provenance: ContextPolicyInput::Provenance.new(origin: :agent_configuration),
-            metadata: {}
-          )
-        end
-        if handoff_context
-          instructions << ContextPolicyInput::InstructionItem.new(
-            id: "instruction:handoff:#{execution.execution_id}:1",
-            kind: :handoff_responsibility,
-            role: :user,
-            content: handoff_context.responsibility.to_s,
-            content_format: :text,
-            estimated_tokens: estimate_value(handoff_context.responsibility.to_s),
-            required: true,
-            provenance: ContextPolicyInput::Provenance.new(origin: :handoff_context),
-            metadata: {SEGMENT_ORIGIN_METADATA_KEY => HANDOFF_CONTEXT_ORIGIN}
-          )
-        end
+        instructions = initial_instruction_items(
+          system_text,
+          handoff_context,
+          execution: execution
+        )
 
-        generation = agent_root.transcript_generation
-        eligible_working = Array(execution.working_records).select do |record|
-          record.context_candidate && record.context_generation == generation
-        end
-        candidates = @candidate_resolver.resolve(
-          prior_records: projection.context_records,
-          working_records: eligible_working,
+        candidates = resolve_record_candidates(
+          projection,
+          agent_root: agent_root,
+          execution: execution,
           excluded_record_ids: excluded
         )
-        candidates = merge_hook_candidates(
+        candidates = merge_context_candidates(
           candidates,
           hook_candidates,
+          handoff_context,
           agent_root: agent_root,
           execution: execution,
           call_sequence: 1
         )
-        candidates = merge_handoff_candidates(
-          candidates,
-          handoff_context,
+        current_input = current_input_item(
+          current_input_content,
+          input_ref: input_ref,
+          candidates: candidates,
+          agent_root: agent_root,
           execution: execution
         )
-        next_sequence = Array(candidates).filter_map(&:sequence).max.to_i + 1
-        current_input = ContextPolicyInput::ConversationItem.new(
-          id: "current-input:#{execution.execution_id}",
-          kind: :current_input,
-          role: :user,
-          content: current_input_content,
-          content_format: :text,
-          sequence: next_sequence,
-          estimated_tokens: estimate_value(current_input_content),
-          required: true,
-          provenance: ContextPolicyInput::Provenance.new(
-            origin: :working,
-            content_ref: input_ref,
-            record_id: execution.metadata["current_input_record_id"],
-            agent_id: agent_root.agent_id,
-            execution_id: execution.execution_id
-          ),
-          tool_call_id: nil,
-          tool_call_ids: [],
-          delivery: :ask_argument,
-          metadata: {
-            "source_agent_id" => agent_root.agent_id,
-            "source_execution_id" => execution.execution_id,
-            "handoff_policy_category" => "current_request"
-          }
-        )
 
         prepare(
           agent_root: agent_root,
@@ -168,33 +120,23 @@ module Phronomy
           additional_tools: handoff_tool_classes(config)
         )
 
-        instructions = base_manifest.segments.filter_map do |segment|
-          next unless retained_base_instruction?(segment)
-          instruction_item_from_manifest(segment)
-        end
+        instructions = retained_instruction_items(base_manifest)
 
-        generation = agent_root.transcript_generation
-        eligible_working = Array(execution.working_records).select do |record|
-          record.context_candidate && record.context_generation == generation
-        end
-        candidates = @candidate_resolver.resolve(
-          prior_records: projection.context_records,
-          working_records: eligible_working,
+        candidates = resolve_record_candidates(
+          projection,
+          agent_root: agent_root,
+          execution: execution,
           excluded_record_ids: []
         )
         call_sequence = execution.llm_calls.length + 1
-        candidates = merge_hook_candidates(
+        candidates = merge_context_candidates(
           candidates,
           hook_candidates,
+          handoff_context,
           agent_root: agent_root,
           execution: execution,
           call_sequence: call_sequence
         )
-        candidates = merge_handoff_candidates(
-          candidates,
-          handoff_context,
-          execution: execution
-        )
 
         prepare(
           agent_root: agent_root,
@@ -274,6 +216,111 @@ module Phronomy
 
       private
 
+      def initial_instruction_items(system_text, handoff_context, execution:)
+        instructions = []
+        unless system_text.to_s.empty?
+          instructions << agent_instruction_item(system_text, execution: execution)
+        end
+        if handoff_context
+          instructions << handoff_instruction_item(handoff_context, execution: execution)
+        end
+        instructions
+      end
+
+      def agent_instruction_item(system_text, execution:)
+        ContextPolicyInput::InstructionItem.new(
+          id: "instruction:agent:#{execution.execution_id}:1",
+          kind: :instruction,
+          role: :system,
+          content: system_text.to_s,
+          content_format: :text,
+          estimated_tokens: estimate_value(system_text.to_s),
+          required: true,
+          provenance: ContextPolicyInput::Provenance.new(origin: :agent_configuration),
+          metadata: {}
+        )
+      end
+
+      def handoff_instruction_item(handoff_context, execution:)
+        ContextPolicyInput::InstructionItem.new(
+          id: "instruction:handoff:#{execution.execution_id}:1",
+          kind: :handoff_responsibility,
+          role: :user,
+          content: handoff_context.responsibility.to_s,
+          content_format: :text,
+          estimated_tokens: estimate_value(handoff_context.responsibility.to_s),
+          required: true,
+          provenance: ContextPolicyInput::Provenance.new(origin: :handoff_context),
+          metadata: {SEGMENT_ORIGIN_METADATA_KEY => HANDOFF_CONTEXT_ORIGIN}
+        )
+      end
+
+      def retained_instruction_items(base_manifest)
+        base_manifest.segments.filter_map do |segment|
+          next unless retained_base_instruction?(segment)
+          instruction_item_from_manifest(segment)
+        end
+      end
+
+      def resolve_record_candidates(projection, agent_root:, execution:, excluded_record_ids:)
+        generation = agent_root.transcript_generation
+        eligible_working = Array(execution.working_records).select do |record|
+          record.context_candidate && record.context_generation == generation
+        end
+        @candidate_resolver.resolve(
+          prior_records: projection.context_records,
+          working_records: eligible_working,
+          excluded_record_ids: excluded_record_ids
+        )
+      end
+
+      def merge_context_candidates(
+        candidates, hook_candidates, handoff_context,
+        agent_root:, execution:, call_sequence:
+      )
+        candidates = merge_hook_candidates(
+          candidates,
+          hook_candidates,
+          agent_root: agent_root,
+          execution: execution,
+          call_sequence: call_sequence
+        )
+        merge_handoff_candidates(
+          candidates,
+          handoff_context,
+          execution: execution
+        )
+      end
+
+      def current_input_item(content, input_ref:, candidates:, agent_root:, execution:)
+        next_sequence = Array(candidates).filter_map(&:sequence).max.to_i + 1
+        ContextPolicyInput::ConversationItem.new(
+          id: "current-input:#{execution.execution_id}",
+          kind: :current_input,
+          role: :user,
+          content: content,
+          content_format: :text,
+          sequence: next_sequence,
+          estimated_tokens: estimate_value(content),
+          required: true,
+          provenance: ContextPolicyInput::Provenance.new(
+            origin: :working,
+            content_ref: input_ref,
+            record_id: execution.metadata["current_input_record_id"],
+            agent_id: agent_root.agent_id,
+            execution_id: execution.execution_id
+          ),
+          tool_call_id: nil,
+          tool_call_ids: [],
+          delivery: :ask_argument,
+          metadata: {
+            "source_agent_id" => agent_root.agent_id,
+            "source_execution_id" => execution.execution_id,
+            "handoff_policy_category" => "current_request"
+          }
+        )
+      end
+
       def prepare(
         agent_root:,
         execution:,
@@ -286,7 +333,7 @@ module Phronomy
         tools:,
         current_input:
       )
-        token_budget = TokenBudgetResolver.new(agent: @agent).resolve(model_config)
+        token_budget = TokenBudgetResolver.new.resolve(model_config)
         policy_input = @input_builder.build(
           agent_id: agent_root.agent_id,
           execution_id: execution.execution_id,
@@ -438,7 +485,7 @@ module Phronomy
 
       def sanitized_item_metadata(item)
         raw = item.metadata.to_h.transform_keys(&:to_s)
-        # :working origin is Phronomy-controlled (from perform_initial_preparation),
+        # :working origin is Phronomy-controlled (from InitialPreparation),
         # so handoff routing metadata on working records is equally trusted.
         trusted_handoff = if item.provenance.origin == :handoff || item.provenance.origin == :working
           raw.slice(*TRUSTED_HANDOFF_METADATA_KEYS)
@@ -474,15 +521,23 @@ module Phronomy
           "provider" => @agent.class.provider&.to_s,
           "temperature" => @agent.class.temperature,
           "max_output_tokens" => @agent.class.max_output_tokens,
-          "context_window" => @agent.class.context_window,
-          "cache_instructions" => !!@agent.class.cache_instructions,
-          "parallel_tool_execution" => !!Phronomy.configuration.parallel_tool_execution
+          "cache_instructions" => !!@agent.class.cache_instructions
         }.compact
       end
 
       def apply_model_config_patch(base, patch)
         return base unless patch
-        base.merge(patch.to_h.transform_keys(&:to_s)).compact
+        values = patch.to_h.transform_keys(&:to_s)
+        if values.key?("context_window")
+          raise Phronomy::ConfigurationError,
+            "context_window is model metadata; configure the RubyLLM model registry"
+        end
+        if values.key?("max_output_tokens") && !values["max_output_tokens"].nil?
+          cap = Integer(values["max_output_tokens"])
+          raise ArgumentError, "max_output_tokens must be positive" unless cap.positive?
+          values["max_output_tokens"] = cap
+        end
+        base.merge(values).compact
       end
 
       def normalize_candidates(candidates)

data/lib/phronomy/agent/{context_importer.rb → context_assembly/context_importer.rb}

@@ -8,8 +8,8 @@ module Phronomy
       ) do
         def initialize(**values)
           super(**values.merge(
-            content: Immutable.copy(values[:content]),
-            metadata: Immutable.copy(values[:metadata] || {})
+            content: Phronomy::Values::Immutable.copy(values[:content]),
+            metadata: Phronomy::Values::Immutable.copy(values[:metadata] || {})
           ))
           freeze
         end

data/lib/phronomy/agent/{ruby_llm_materializer.rb → context_assembly/ruby_llm_materializer.rb}

@@ -43,7 +43,7 @@ module Phronomy
           messages: materialize_message_segments(message_segments).freeze,
           tool_classes: tool_set.runtime_tools,
           ask_message: ask_message,
-          model_config: Immutable.copy(model_config),
+          model_config: Phronomy::Values::Immutable.copy(model_config),
           manifest: manifest,
           manifest_ref: manifest_ref
         )
@@ -151,22 +151,19 @@ module Phronomy
         end
 
         tool_calls = materialize_tool_calls(payload["tool_calls"])
-        message = RubyLLM::Message.new(
+        RubyLLM::Message.new(
           role: role,
           content: initial_content_for(role, payload.fetch("content", nil), tool_calls),
           tool_calls: tool_calls.empty? ? nil : tool_calls,
           tool_call_id: payload["tool_call_id"],
-          model_id: payload["model_id"]
+          model: payload["model_id"]
         )
-
-        message.content = payload["content"] if payload.key?("content")
-        message
       end
 
       def initial_content_for(role, content, tool_calls)
         return "" if role == :assistant && content.nil? && !tool_calls.empty?
 
-        content.nil? ? "" : content
+        (content.is_a?(Hash) || content.is_a?(Array)) ? JSON.generate(content) : content
       end
 
       def materialize_tool_calls(payloads)

data/lib/phronomy/agent/context_assembly/runtime_chat_builder.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Constructs provider chat objects from already selected model settings.
+    # Agent hooks retain projection installation and invocation-specific Tools.
+    # @api private
+    class RuntimeChatBuilder
+      def self.build(config)
+        chat = RubyLLM.chat(**chat_options(config))
+        chat.with_temperature(config["temperature"]) if config["temperature"]
+        if config["max_output_tokens"]
+          chat.with_max_output_tokens(config["max_output_tokens"])
+        end
+        chat
+      end
+
+      def self.apply_instructions(chat, text, cache:, provider:)
+        chat.with_instructions(text, cache_until_here: cache)
+      end
+
+      def self.chat_options(config)
+        opts = {}
+        model = config["model"]
+        opts[:model] = model if model
+        provider = config["provider"]
+        if provider
+          opts[:provider] = provider.to_sym
+          opts[:assume_model_exists] = true
+        end
+        opts
+      end
+      private_class_method :chat_options
+    end
+  end
+end