phronomy 0.26.0 → 0.28.0

data/lib/phronomy/agent/base.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
+require_relative "../execution/concurrency/worker_input_restricted"
+
 require "securerandom"
-require_relative "concerns/filterable"
-require_relative "concerns/before_llm_input"
-require_relative "concerns/error_translation"
+require_relative "filterable"
+require_relative "before_llm_input"
 
 module Phronomy
   module Agent
@@ -31,10 +32,11 @@ module Phronomy
     #     max_iterations 15
     #   end
     class Base
+      include Phronomy::Concurrency::WorkerInputRestricted
+
       include Phronomy::Runnable
-      include Concerns::Filterable
-      include Concerns::BeforeLLMInput
-      include Concerns::ErrorTranslation
+      include Filterable
+      include BeforeLLMInput
 
       APPROVAL_CONFIGURATION_INIT_MUTEX = Mutex.new
       private_constant :APPROVAL_CONFIGURATION_INIT_MUTEX
@@ -44,7 +46,7 @@ module Phronomy
           if name
             @model = name
           else
-            @model || Phronomy.configuration.default_model
+            @model || Phronomy::Agent::Settings.current.default_model
           end
         end
 
@@ -119,30 +121,24 @@ 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
 
-        # Binds one Application-constructed ContextPolicy instance to this
+        # Binds one Application-constructed Phronomy::Context::ContextPolicy instance to this
         # Agent class. Policy binding is Application code/runtime wiring rather
         # than durable Agent state.
         def context_policy(*args)
           if args.empty?
             return @context_policy if instance_variable_defined?(:@context_policy)
             return superclass.context_policy if superclass.respond_to?(:context_policy)
-            return ContextPolicies::Default.instance
+            raise Phronomy::ConfigurationError, "Agent ContextPolicy has not been configured"
           end
-          unless args.length == 1 && args.first.is_a?(ContextPolicy)
+          unless args.length == 1 && args.first.is_a?(Phronomy::Context::ContextPolicy)
             raise ArgumentError,
-              "context_policy expects one Phronomy::Agent::ContextPolicy instance"
+              "context_policy expects one Phronomy::Context::ContextPolicy instance"
           end
 
           @context_policy = args.first
@@ -173,6 +169,7 @@ module Phronomy
           agent_id: SecureRandom.uuid,
           context: nil,
           knowledge: [],
+          retention: nil,
           persistence: nil,
           metadata: {},
           on_event: nil,
@@ -182,6 +179,7 @@ module Phronomy
             agent_id: agent_id,
             context: context,
             knowledge: knowledge,
+            retention: retention,
             persistence: persistence,
             metadata: metadata,
             on_event: on_event,
@@ -191,7 +189,7 @@ module Phronomy
 
         # Resolves one existing logical Agent. A live process-local owner wins
         # without a Persistence reload; otherwise the durable Agent is hydrated.
-        def load(agent_id, persistence:, on_event: nil, &event_block)
+        def load(agent_id, persistence:, on_event: nil, execution_wiring: {}, &event_block)
           raise ArgumentError, "persistence is required" unless persistence
           if on_event && event_block
             raise ArgumentError, "Provide either on_event: or a block, not both"
@@ -201,10 +199,9 @@ module Phronomy
           raise ArgumentError, "agent_id must not be empty" if key.empty?
 
           listener_supplied = !on_event.nil? || !event_block.nil?
-          runtime = Phronomy::Runtime.instance
           materialized = false
 
-          agent = runtime.__load_agent(key, expected_class: self) do |owner_runtime|
+          agent = OwnershipRegistry.current.load(key, expected_class: self) do |owner_runtime|
             materialized = true
             instance = __construct_owned_agent(
               owner_runtime,
@@ -212,6 +209,7 @@ module Phronomy
               agent_id: key,
               persistence: persistence,
               load_existing: true,
+              execution_wiring: execution_wiring,
               on_event: on_event,
               &event_block
             )
@@ -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_current&.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_current&.agent_execution_owner(execution_id)
           unless owner
             raise Phronomy::ExecutionRehydrationRequiredError,
               "no live execution owner for #{execution_id}; durable rehydration is required"
@@ -267,9 +268,15 @@ module Phronomy
         end
       end
 
+      # Bound at Agent construction; no execution may silently switch Runtime.
       # @api private
-      def __coordination_config
-        @_phronomy_coordination_config || {}.freeze
+      def __execution_environment
+        @_phronomy_runtime_owner || ExecutionEnvironment.current
+      end
+
+      # @api private
+      def __execution_wiring
+        @_phronomy_execution_wiring || {}.freeze
       end
 
       # Framework-owned idempotent Tool operations opt into exact replay.
@@ -278,26 +285,29 @@ module Phronomy
 
       # @api private
       def __framework_call?(name)
-        __framework_tool_replayable?(name) || Array(__coordination_config[:phronomy_handoff_bindings]).any? { |binding| binding.tool_name == name }
+        __framework_tool_replayable?(name) || Array(__execution_wiring[:phronomy_control_bindings]).any? { |binding| binding.tool_name == name }
       end
 
-      # Captured Tool wiring is supplied explicitly; this hook only writes semantic values.
-      # @api private
-      def __prepare_coordination_record(execution, tx:) = execution
-
       # Runtime configuration only; no value returned here is serialized.
       # @api private
       def __invocation_config(config) = config
 
+      def knowledge_snapshot = persistence.knowledge_snapshot(agent_id: agent_id)
+
+      # Listener inheritance is an explicit orchestration choice, not a private getter.
+      def event_listener = _phronomy_event_listener
+
       attr_reader :agent_id, :persistence
 
       def initialize(
         agent_id: nil,
         context: nil,
         knowledge: [],
+        retention: nil,
         persistence: nil,
         metadata: {},
         load_existing: false,
+        execution_wiring: {},
         on_event: nil,
         &event_block
       )
@@ -305,6 +315,11 @@ module Phronomy
           raise ArgumentError, "Provide either on_event: or a block, not both"
         end
         @_phronomy_event_listener = on_event || event_block
+        @_phronomy_execution_wiring = execution_wiring.dup.freeze
+        @initial_retention = retention
+        if retention && retention.agent_id != agent_id.to_s
+          raise ArgumentError, "retention must refer to the new Agent"
+        end
 
         reserved_agent_id = @_phronomy_reserved_agent_id
         effective_agent_id = if agent_id.nil?
@@ -336,9 +351,8 @@ module Phronomy
             "load_existing: is an internal hydration option; use .load(agent_id, persistence:)"
         end
 
-        runtime = Phronomy::Runtime.instance
         begin
-          runtime.__create_agent(effective_agent_id, expected_class: self.class) do |owner_runtime|
+          OwnershipRegistry.current.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,
@@ -395,34 +409,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 +438,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 runtime.existing_registry&.agent_execution_admitted?(agent_id)
+          registry.abort_purge(self, token)
           raise Phronomy::AgentBusyError,
             "Agent #{agent_id.inspect} has a nonterminal top-level execution"
         end
@@ -460,12 +449,11 @@ module Phronomy
         begin
           persistence.transaction do |tx|
             tx.executions.assert_idle!(agent_id)
-            if (routing = tx.handoff_states.load(agent_id))
-              unless routing.phase == "stable" && tx.executions.list_active(routing.active_agent_id).empty?
-                raise Phronomy::AgentBusyError, "Handoff anchor #{agent_id} owns an unfinished turn"
-              end
-              tx.handoff_states.delete(agent_id, expected_revision: routing.handoff_revision)
+            tx.guard_agent!(agent_id)
+            unless tx.retentions.list(agent_id).empty?
+              raise Phronomy::AgentBusyError, "Agent #{agent_id} is retained by durable coordination history"
             end
+            tx.cancellations.delete_for_agent(agent_id)
             tx.journals.delete(agent_id)
             tx.executions.delete_for_agent(agent_id)
             tx.agents.delete(agent_id)
@@ -475,16 +463,16 @@ module Phronomy
           Phronomy::Persistence::NotFoundError,
           Phronomy::Persistence::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
 
@@ -584,8 +572,8 @@ module Phronomy
         load_existing:
       )
         @persistence = persistence ||
-          Phronomy.configuration.persistence ||
-          Phronomy::Persistence::InMemory.new
+          Phronomy::Agent::Settings.current.agent_store ||
+          DefaultPersistence.build
         @agent_id = agent_id.to_s.freeze
 
         if load_existing
@@ -630,117 +618,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, retention: @initial_retention
         )
       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 +687,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
@@ -821,7 +720,7 @@ module Phronomy
       end
 
       def _check_event_loop_reentrancy(sync_method, async_method)
-        if Phronomy::Runtime.instance.event_loop.current?
+        if Phronomy::WaitPolicy.blocking_forbidden?
           raise Phronomy::EventLoopReentrancyError,
             "#{self.class.name}##{sync_method} cannot run on the EventLoop thread. " \
             "Use #{async_method} and return immediately."
@@ -836,12 +735,6 @@ module Phronomy
         task.fail(error)
       end
 
-      def _translated_error(error)
-        translate_and_reraise!(error)
-      rescue => translated
-        translated
-      end
-
       def _deliver_stream_event(listener, event)
         return unless listener
 
@@ -885,7 +778,7 @@ module Phronomy
       end
 
       def _warn_stream_callback_error(message)
-        logger = Phronomy.configuration.logger
+        logger = Phronomy::RuntimeSettings.current.logger
         unless logger
           _kernel_warn_safely(message)
           return
@@ -933,52 +826,28 @@ module Phronomy
         meta
       end
 
-      def _apply_runtime_projection_to_chat(chat, projection, invocation: nil)
-        if projection.system
-          apply_instructions(
-            chat,
-            projection.system,
-            cache: projection.model_config["cache_instructions"],
-            provider: projection.model_config["provider"]
-          )
-        end
-        projection.tool_classes.each do |tool_class|
-          chat.with_tool(prepare_tool_class(tool_class, invocation: invocation))
+      def prepare_runtime_input(projection, invocation:)
+        tools = projection.tool_classes.map do |tool|
+          prepared = prepare_tool_class(tool, invocation: invocation)
+          prepared.is_a?(Class) ? prepared.new : prepared
         end
-        projection.messages.each { |message| chat.messages << message }
-        chat
+        invocation.tools = tools.to_h { |tool| [tool.name.to_sym, tool] }.freeze
+        invocation.messages = projection.messages.dup
+        invocation
       end
 
-      def build_chat(model_config: nil)
-        config = model_config || {
-          "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
-        }
-        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
+      def build_llm_request(projection, invocation:)
+        definitions = Phronomy::Tool::DefinitionSet.build(tools: invocation.tools.values).definitions
+        Phronomy::LLMAdapter::Request.new(
+          model_config: projection.model_config, system: projection.system,
+          messages: invocation.messages, tools: definitions, message: projection.ask_message
+        )
       end
 
       def build_instructions(input)
         instr = self.class.instructions
         case instr
-        when Phronomy::Agent::Context::Instruction::PromptTemplate
+        when Phronomy::Context::PromptTemplate
           vars = input.is_a?(Hash) ? input : {input: input}
           instr.format_system(**vars) || instr.format(**vars)
         when String then instr
@@ -987,15 +856,6 @@ module Phronomy
         end
       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
-      end
-
       def extract_message(input)
         case input
         when String then input
@@ -1018,69 +878,21 @@ module Phronomy
         raise Phronomy::CancellationError, message
       end
 
+      def tool_definition_set(additional_tools: [])
+        runtime_tools = (self.class.tools + Array(additional_tools)).freeze
+        Phronomy::Tool::DefinitionSet.build(
+          tools: runtime_tools.map { |tool| prepare_tool_class(tool) },
+          runtime_tools: runtime_tools
+        )
+      end
+
       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