phronomy 0.25.0 → 0.27.0

data/lib/phronomy/agent/base.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../engine/concurrency/worker_input_restricted"
+
 require "securerandom"
 require_relative "concerns/filterable"
 require_relative "concerns/before_llm_input"
@@ -31,6 +33,8 @@ module Phronomy
     #     max_iterations 15
     #   end
     class Base
+      include Phronomy::Concurrency::WorkerInputRestricted
+
       include Phronomy::Runnable
       include Concerns::Filterable
       include Concerns::BeforeLLMInput
@@ -119,15 +123,9 @@ module Phronomy
           if val.nil?
             @max_output_tokens
           else
-            @max_output_tokens = val.to_i
-          end
-        end
-
-        def context_window(val = nil)
-          if val.nil?
-            @context_window
-          else
-            @context_window = val.to_i
+            value = Integer(val)
+            raise ArgumentError, "max_output_tokens must be positive" unless value.positive?
+            @max_output_tokens = value
           end
         end
 
@@ -204,7 +202,7 @@ module Phronomy
           runtime = Phronomy::Runtime.instance
           materialized = false
 
-          agent = runtime.__load_agent(key, expected_class: self) do |owner_runtime|
+          agent = OwnershipRegistry.for(runtime).load(key, expected_class: self) do |owner_runtime|
             materialized = true
             instance = __construct_owned_agent(
               owner_runtime,
@@ -235,14 +233,17 @@ module Phronomy
         # Returns only the process-local live Agent owner. Does not access
         # Persistence and returns nil when this Runtime has no live owner.
         def get(agent_id)
-          Phronomy::Runtime.instance.__get_agent(agent_id, expected_class: self)
+          key = agent_id.to_s
+          raise ArgumentError, "agent_id must not be empty" if key.empty?
+
+          OwnershipRegistry.existing_for(Phronomy::Runtime.instance)&.get(key, expected_class: self)
         end
 
         # Resolves the live Agent instance that currently owns execution_id in
         # this process. The Runtime returns only a read-only ownership view;
         # mutable Agent execution state remains EventLoop-owned.
         def live_for_execution(execution_id)
-          owner = Phronomy::Runtime.instance.__agent_execution_owner(execution_id)
+          owner = Phronomy::Agent::ExecutionRegistry.existing_for(Phronomy::Runtime.instance)&.agent_execution_owner(execution_id)
           unless owner
             raise Phronomy::ExecutionRehydrationRequiredError,
               "no live execution owner for #{execution_id}; durable rehydration is required"
@@ -338,7 +339,7 @@ module Phronomy
 
         runtime = Phronomy::Runtime.instance
         begin
-          runtime.__create_agent(effective_agent_id, expected_class: self.class) do |owner_runtime|
+          OwnershipRegistry.for(runtime).create(effective_agent_id, expected_class: self.class) do |owner_runtime|
             __prepare_runtime_owner!(owner_runtime, effective_agent_id)
             initialize_owned_state(
               agent_id: effective_agent_id,
@@ -350,7 +351,7 @@ module Phronomy
             )
             self
           end
-        rescue Phronomy::Persistence::ConflictError => error
+        rescue Phronomy::Storage::ConflictError => error
           raise Phronomy::AgentAlreadyExistsError,
             "Agent #{effective_agent_id.inspect} already exists durably: #{error.message}"
         end
@@ -395,34 +396,8 @@ module Phronomy
       def add_knowledge(content, metadata: {})
         __assert_live_agent!
         current = agent_root
-        next_root = nil
-        appended = nil
-        persistence.transaction do |tx|
-          tx.executions.assert_idle!(agent_id)
-          record = build_knowledge_record(
-            tx: tx,
-            root: current,
-            content: content,
-            metadata: metadata
-          )
-          appended = tx.journals.append(
-            agent_id,
-            expected_position: current.journal_position,
-            records: [record]
-          )
-          next_root = current.with(
-            agent_revision: current.agent_revision + 1,
-            context_revision: current.context_revision + 1,
-            journal_position: current.journal_position + appended.length
-          )
-          tx.agents.save(
-            agent_id,
-            expected_revision: current.agent_revision,
-            root: next_root
-          )
-        end
-        _append_journal_records(appended)
-        @root = next_root
+        update = state_writer.add_knowledge(root: current, content: content, metadata: metadata)
+        apply_state_update(update)
         self
       end
 
@@ -450,9 +425,10 @@ module Phronomy
 
         __assert_live_agent!
         runtime = @_phronomy_runtime_owner
-        token = runtime.__begin_agent_purge(self)
-        if runtime.__agent_execution_admitted?(agent_id)
-          runtime.__abort_agent_purge(self, token)
+        registry = OwnershipRegistry.for(runtime)
+        token = registry.begin_purge(self)
+        if Phronomy::Agent::ExecutionRegistry.existing_for(runtime)&.agent_execution_admitted?(agent_id)
+          registry.abort_purge(self, token)
           raise Phronomy::AgentBusyError,
             "Agent #{agent_id.inspect} has a nonterminal top-level execution"
         end
@@ -471,20 +447,20 @@ module Phronomy
             tx.agents.delete(agent_id)
           end
         rescue Phronomy::AgentBusyError,
-          Phronomy::Persistence::ConflictError,
-          Phronomy::Persistence::NotFoundError,
-          Phronomy::Persistence::SerializationError,
+          Phronomy::Storage::ConflictError,
+          Phronomy::Storage::NotFoundError,
+          Phronomy::Storage::SerializationError,
           ArgumentError
-          runtime.__abort_agent_purge(self, token)
+          registry.abort_purge(self, token)
           raise
         rescue
           # Without F1 reconciliation support we cannot infer that a failed
           # durable delete did not commit. Keep the identity fail-closed.
-          runtime.__leave_agent_purge_uncertain(self, token)
+          registry.leave_purge_uncertain(self, token)
           raise
         end
 
-        runtime.__complete_agent_purge(self, token)
+        registry.complete_purge(self, token)
         true
       end
 
@@ -585,7 +561,7 @@ module Phronomy
       )
         @persistence = persistence ||
           Phronomy.configuration.persistence ||
-          Phronomy::Persistence::InMemory.new
+          DefaultPersistence.build
         @agent_id = agent_id.to_s.freeze
 
         if load_existing
@@ -630,117 +606,27 @@ module Phronomy
 
       def create_agent_root!(context:, knowledge:, metadata:)
         definition = self.class.agent_definition
-        root = Agent::AgentRoot.create(
-          agent_id: agent_id,
-          agent_definition_id: definition.fetch(:id),
-          agent_definition_version: definition.fetch(:version),
-          metadata: metadata
-        )
-        persistence.transaction do |tx|
-          tx.agents.create(root)
-          records = initial_context_records(tx: tx, root: root, context: context)
-          records.concat(initial_knowledge_records(tx: tx, root: root, knowledge: knowledge))
-          unless records.empty?
-            appended = tx.journals.append(agent_id, expected_position: 0, records: records)
-            root = root.with(
-              agent_revision: 1,
-              context_revision: 1,
-              journal_position: appended.length
-            )
-            tx.agents.save(agent_id, expected_revision: 0, root: root)
-          end
-        end
-        root
-      end
-
-      def initial_context_records(tx:, root:, context:)
-        return [] unless context
-
-        imported = context.respond_to?(:records) ? context :
-          Agent::ContextImporter.import_messages(context)
-        imported.records.map do |record|
-          content_ref = case record.content_format
-          when :text then tx.contents.put_text(record.content)
-          when :json then tx.contents.put_json(record.content)
-          else
-            raise ArgumentError,
-              "unsupported imported content format: #{record.content_format.inspect}"
-          end
-          Agent::JournalRecord.new(
-            agent_id: agent_id,
-            kind: record.kind,
-            channel: record.channel,
-            role: record.role,
-            content_ref: content_ref,
-            context_generation: root.transcript_generation,
-            context_candidate: true,
-            metadata: record.metadata
-          )
-        end
-      end
-
-      def initial_knowledge_records(tx:, root:, knowledge:)
-        Array(knowledge).map do |content|
-          build_knowledge_record(
-            tx: tx,
-            root: root,
-            content: content,
-            metadata: {}
-          )
-        end
-      end
-
-      def build_knowledge_record(tx:, root:, content:, metadata:)
-        Agent::JournalRecord.new(
-          agent_id: agent_id,
-          kind: :knowledge,
-          channel: :context,
-          role: :user,
-          content_ref: tx.contents.put_text(String(content)),
-          context_generation: root.transcript_generation,
-          context_candidate: true,
-          metadata: metadata || {}
+        state_writer.create_root(
+          definition: definition, context: context, knowledge: knowledge, metadata: metadata
         )
       end
 
       def mutate_context!(kind, context_affecting: true)
         __assert_live_agent!
         current = agent_root
-        next_root = nil
-        appended = nil
-        persistence.transaction do |tx|
-          tx.executions.assert_idle!(agent_id)
-          record = Agent::JournalRecord.new(
-            agent_id: agent_id,
-            kind: kind,
-            channel: :state,
-            context_generation: current.transcript_generation,
-            context_candidate: false
-          )
-          appended = tx.journals.append(
-            agent_id,
-            expected_position: current.journal_position,
-            records: [record]
-          )
-          proposed = yield(current)
-          next_root = proposed.with(
-            journal_position: current.journal_position + appended.length,
-            context_revision: context_affecting ?
-              yield_context_revision(current, proposed) : current.context_revision
-          )
-          tx.agents.save(
-            agent_id,
-            expected_revision: current.agent_revision,
-            root: next_root
-          )
-        end
-        _append_journal_records(appended)
-        @root = next_root
+        update = state_writer.mutate_context(
+          root: current, kind: kind, context_affecting: context_affecting
+        ) { |root| yield(root) }
+        apply_state_update(update)
+      end
+
+      def state_writer
+        StateWriter.new(persistence: persistence, agent_id: agent_id)
       end
 
-      def yield_context_revision(current, proposed)
-        (proposed.context_revision == current.context_revision) ?
-          current.context_revision + 1 : proposed.context_revision
+      def apply_state_update(update)
+        _append_journal_records(update.records)
+        @root = update.root
       end
 
       def _journal_records_snapshot
@@ -789,7 +675,8 @@ module Phronomy
         return true if @_phronomy_runtime_owner_state == :constructing
 
         runtime = @_phronomy_runtime_owner
-        unless runtime&.__agent_owned?(self)
+        registry = OwnershipRegistry.existing_for(runtime) if runtime
+        unless registry&.owned?(self)
           raise Phronomy::RuntimeShutdownError,
             "Agent #{agent_id.inspect} is no longer the live owner in its Runtime"
         end
@@ -799,18 +686,12 @@ module Phronomy
       def _prepare_invocation_config(config, invocation_context)
         __assert_live_agent!
         _reject_removed_generic_identity_keys!(config)
-        effective_config = invocation_context ?
+        invocation_context ?
           config.merge(invocation_context: invocation_context) : config
 
-        if invocation_context && effective_config[:cancellation_token].nil?
-          if (tok = invocation_context.effective_timeout_token)
-            effective_config = effective_config.merge(
-              cancellation_token: tok,
-              phronomy_timeout_deadline: invocation_context.deadline
-            )
-          end
-        end
-        effective_config
+        # ExecutionCoordinator connects context and individual controls together
+        # at admission, before returning the result. Do not arm a second timer
+        # here or replace one cancellation source with another.
       end
 
       def _reject_removed_generic_identity_keys!(config)
@@ -949,7 +830,7 @@ module Phronomy
           )
         end
         projection.tool_classes.each do |tool_class|
-          chat.with_tool(prepare_tool_class(tool_class, invocation: invocation))
+          chat.with_tools(prepare_tool_class(tool_class, invocation: invocation))
         end
         projection.messages.each { |message| chat.messages << message }
         chat
@@ -960,25 +841,9 @@ module Phronomy
           "model" => self.class.model,
           "provider" => self.class.provider,
           "temperature" => self.class.temperature,
-          "max_output_tokens" => self.class.max_output_tokens,
-          "parallel_tool_execution" => Phronomy.configuration.parallel_tool_execution
+          "max_output_tokens" => self.class.max_output_tokens
         }
-        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
-        parallel_class = config["parallel_tool_execution"] ?
-          Phronomy::MultiAgent::ParallelToolChat : nil
-        chat = parallel_class ? parallel_class.new(**opts) : RubyLLM.chat(**opts)
-        chat.with_temperature(config["temperature"]) if config["temperature"]
-        if config["max_output_tokens"] && chat.respond_to?(:with_max_output_tokens)
-          chat.with_max_output_tokens(config["max_output_tokens"])
-        end
-        chat
+        RuntimeChatBuilder.build(config)
       end
 
       def build_instructions(input)
@@ -994,12 +859,7 @@ module Phronomy
       end
 
       def apply_instructions(chat, text, cache: false, provider: nil)
-        if cache && provider.to_s == "anthropic"
-          content = RubyLLM::Providers::Anthropic::Content.new(text, cache: true)
-          chat.with_instructions(content)
-        else
-          chat.with_instructions(text)
-        end
+        RuntimeChatBuilder.apply_instructions(chat, text, cache: cache, provider: provider)
       end
 
       def extract_message(input)
@@ -1027,66 +887,10 @@ module Phronomy
       def prepare_tool_class(tool_class, invocation: nil)
         return tool_class unless tool_class.is_a?(Class)
 
-        resolved = if (alias_name = self.class.tool_aliases[tool_class])
-          Class.new(tool_class) do
-            tool_name alias_name
-          end
-        else
-          tool_class
-        end
-
-        result_filters = _tool_result_filters_for(tool_class)
-        return resolved if result_filters.empty?
-
-        effective_name = resolved.new.name
-        custom_async_call =
-          resolved.instance_method(:call_async).owner !=
-          Phronomy::Agent::Context::Capability::Base
-
-        Class.new(resolved) do
-          tool_name effective_name
-          define_method(:call) do |args, **kwargs|
-            result = super(args, **kwargs)
-            result_filters.inject(result) { |val, filter|
-              filter.call(val, tool_name: name, args: args)
-            }
-          end
-
-          if custom_async_call
-            define_method(:call_async) do |args, **kwargs|
-              source = super(args, **kwargs)
-              filtered = Phronomy::Concurrency::PhysicalCompletionTask.deferred(
-                name: "tool-filter-#{name}"
-              )
-              source_has_physical_signal = source.respond_to?(:on_physical_complete)
-              source.on_physical_complete { filtered.mark_physical_complete! } if
-                source_has_physical_signal
-              source.on_complete do |value, error|
-                if error
-                  filtered.mark_physical_complete! unless source_has_physical_signal
-                  if source.respond_to?(:status) && source.status == :cancelled
-                    filtered.cancel!(error)
-                  else
-                    filtered.fail(error)
-                  end
-                  next
-                end
-
-                begin
-                  result = result_filters.inject(value) { |val, filter|
-                    filter.call(val, tool_name: name, args: args)
-                  }
-                  filtered.mark_physical_complete! unless source_has_physical_signal
-                  filtered.complete(result)
-                rescue => filter_error
-                  filtered.mark_physical_complete! unless source_has_physical_signal
-                  filtered.fail(filter_error)
-                end
-              end
-              filtered
-            end
-          end
-        end
+        binding = ToolBinding.new(
+          tool_class, alias_name: self.class.tool_aliases[tool_class]
+        )
+        binding.prepare(result_filters: _tool_result_filters_for(tool_class))
       end
     end
   end

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,