phronomy 0.27.0 → 0.29.0

data/lib/phronomy/agent/execution_environment.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Process-local execution connection selected by composition. Agent owns
+    # admission, progress, approval, durable outcome and recovery decisions;
+    # this extension supplies serial delivery, session routing and resources.
+    # Environments and session handles are never persistence authority.
+    # @api private
+    class ExecutionEnvironment
+      class << self
+        def install_provider(provider)
+          raise ArgumentError, "Agent execution provider must be callable" unless provider.respond_to?(:call)
+          @provider = provider
+        end
+
+        def current
+          @provider&.call || raise(Phronomy::ConfigurationError, "Agent execution environment has not been configured")
+        end
+      end
+
+      def registry = raise(NotImplementedError)
+      def existing_registry = raise(NotImplementedError)
+      def ownership = raise(NotImplementedError)
+      def existing_ownership = raise(NotImplementedError)
+      def executing? = raise(NotImplementedError)
+      def session_phase(id) = raise(NotImplementedError)
+      def submit(**options, &operation) = raise(NotImplementedError)
+      def submit_authorization(timeout:, cancellation_token:, &operation) = raise(NotImplementedError)
+      def build_llm_client(adapter:) = raise(NotImplementedError)
+      def build_agent_session(invocation:, resume_event: nil, resume_phase: nil) = raise(NotImplementedError)
+      def build_tool_session(invocation:, parent_sink:, resume_event: nil, resume_phase: nil) = raise(NotImplementedError)
+      def register_session(session, completion:) = raise(NotImplementedError)
+    end
+  end
+end

data/lib/phronomy/agent/execution_extension_state.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # An opaque state reference owned and interpreted by its bound participant.
+    # @api public
+    ExecutionExtensionState = Data.define(:binding_key, :binding_version, :state_ref) do
+      def initialize(binding_key:, binding_version:, state_ref: nil)
+        raise ArgumentError, "binding_key is required" if binding_key.to_s.empty?
+        raise ArgumentError, "binding_version must be positive" unless binding_version.is_a?(Integer) && binding_version.positive?
+        super(binding_key: binding_key.to_s.freeze, binding_version: binding_version, state_ref: state_ref&.to_s&.freeze)
+      end
+
+      def to_h
+        {"binding_key" => binding_key, "binding_version" => binding_version, "state_ref" => state_ref}.freeze
+      end
+
+      def self.from_h(value) = new(**value.transform_keys(&:to_sym))
+    end
+  end
+end

data/lib/phronomy/agent/execution_observation.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Stable domain observation; does not expose repositories or FSM phases.
+    # @api public
+    ExecutionObservation = Data.define(:agent_id, :execution_id, :status, :result,
+      :error, :reservation, :transfer_receipt, :cancellation_requested) do
+      def initialize(**values)
+        super(**values.transform_values { |value| Phronomy::Values::Immutable.copy(value) })
+      end
+
+      def self.from_result(value)
+        new(agent_id: value.fetch(:agent_id), execution_id: value.fetch(:execution_id), status: value.fetch(:status),
+          result: value[:result], error: value[:error], reservation: nil, transfer_receipt: nil, cancellation_requested: false)
+      end
+
+      def absent? = status == :absent
+      def terminal? = !%i[absent preparing active suspended].include?(status)
+      def continuable? = %i[preparing active].include?(status) && !cancellation_requested
+      def active? = %i[preparing active suspended].include?(status)
+
+      def value!
+        raise Phronomy::Persistence::NotFoundError, "Execution #{execution_id} is absent" if absent?
+        raise RecoverySupport.error_from_failure(error) if error
+        to_result
+      end
+
+      def to_result
+        Phronomy::Values::Immutable.copy(execution_id: execution_id, agent_id: agent_id,
+          status: status, result: result, output: result, error: error)
+      end
+    end
+  end
+end

data/lib/phronomy/agent/filterable.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Adds input, output, and tool-result filter support to an agent.
+    #
+    # Filters transform (or block) values at three call sites:
+    #   - *input*       — the raw user input string, before the LLM is called
+    #   - *output*      — the final LLM output string, before it is returned
+    #   - *tool result* — the return value of each tool call
+    #
+    # Each filter in the chain receives the value returned by the previous one.
+    # A {Phronomy::FilterBlockError} raised inside any filter propagates to the
+    # caller.
+    #
+    # @api private
+    module Filterable
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # Class-level DSL mixed into the including agent class.
+      module ClassMethods
+        # Registers a filter applied to every invocation's user input.
+        # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+        # when a class is given it is instantiated with +.new+.
+        # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+        # @return [void]
+        # @api public
+        def input_filter(filter)
+          @_class_input_filters ||= []
+          @_class_input_filters << _resolve_filter(filter)
+        end
+
+        # Registers a filter applied to every invocation's final LLM output.
+        # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+        # when a class is given it is instantiated with +.new+.
+        # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+        # @return [void]
+        # @api public
+        def output_filter(filter)
+          @_class_output_filters ||= []
+          @_class_output_filters << _resolve_filter(filter)
+        end
+
+        # Registers a filter applied to every tool result for all tools.
+        # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+        # when a class is given it is instantiated with +.new+.
+        # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+        # @return [void]
+        # @api public
+        def tool_result_filter(filter)
+          @_class_tool_result_filters ||= []
+          @_class_tool_result_filters << _resolve_filter(filter)
+        end
+
+        # @return [Array<Phronomy::Filter::Base>]
+        # @api private
+        def _class_input_filters
+          @_class_input_filters || []
+        end
+
+        # @return [Array<Phronomy::Filter::Base>]
+        # @api private
+        def _class_output_filters
+          @_class_output_filters || []
+        end
+
+        # @return [Array<Phronomy::Filter::Base>]
+        # @api private
+        def _class_tool_result_filters
+          @_class_tool_result_filters || []
+        end
+
+        private
+
+        # Coerce +filter+ to an instance: if a Class is passed, call +.new+;
+        # otherwise return the object as-is.
+        # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+        # @return [Phronomy::Filter::Base]
+        # @api private
+        def _resolve_filter(filter)
+          filter.is_a?(Class) ? filter.new : filter
+        end
+      end
+
+      # Registers an input filter on this instance.
+      # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+      # when a class is given it is instantiated with +.new+.
+      # Runs in addition to any class-level input filters.
+      # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+      # @return [self]
+      # @api public
+      def add_input_filter(filter)
+        __with_operation do
+          @_instance_input_filters ||= []
+          @_instance_input_filters << _resolve_filter(filter)
+          self
+        end
+      end
+
+      # Registers an output filter on this instance.
+      # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+      # when a class is given it is instantiated with +.new+.
+      # Runs in addition to any class-level output filters.
+      # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+      # @return [self]
+      # @api public
+      def add_output_filter(filter)
+        __with_operation do
+          @_instance_output_filters ||= []
+          @_instance_output_filters << _resolve_filter(filter)
+          self
+        end
+      end
+
+      # Registers a tool result filter on this instance.
+      #
+      # When called with two arguments, the filter is scoped to the given tool
+      # class only.  When called with one argument, it applies to all tools.
+      # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+      # when a class is given it is instantiated with +.new+.
+      #
+      # @overload add_tool_result_filter(filter)
+      #   @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>] applied to every tool
+      # @overload add_tool_result_filter(tool_class, filter)
+      #   @param tool_class [Class] scope the filter to this tool
+      #   @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+      # @return [self]
+      # @api public
+      def add_tool_result_filter(tool_class_or_filter, filter = nil)
+        __with_operation do
+          if filter.nil?
+            # Single-argument form: apply to all tools.
+            @_instance_tool_result_filters ||= []
+            @_instance_tool_result_filters << _resolve_filter(tool_class_or_filter)
+          else
+            # Two-argument form: scoped to one tool class.
+            @_scoped_tool_result_filters ||= {}
+            (@_scoped_tool_result_filters[tool_class_or_filter] ||= []) << _resolve_filter(filter)
+          end
+          self
+        end
+      end
+
+      private
+
+      # Run input filters (class-level then instance-level).
+      # @param input [String, Hash] the raw user input
+      # @return [String, Hash] the (possibly transformed) input
+      # @api private
+      def run_input_filters!(input)
+        class_filters = self.class._class_input_filters
+        inst_filters = @_instance_input_filters || []
+        (class_filters + inst_filters).inject(input) { |val, f| f.call(val) }
+      end
+
+      # Run output filters (class-level then instance-level).
+      # @param output [String] the LLM output
+      # @return [String] the (possibly transformed) output
+      # @api private
+      def run_output_filters!(output)
+        class_filters = self.class._class_output_filters
+        inst_filters = @_instance_output_filters || []
+        (class_filters + inst_filters).inject(output) { |val, f| f.call(val) }
+      end
+
+      # Collect all tool-result filters (global + scoped) for a given tool class.
+      # @param tool_class [Class]
+      # @return [Array<Phronomy::Filter::Base>]
+      # @api private
+      def _tool_result_filters_for(tool_class)
+        global = self.class._class_tool_result_filters + (@_instance_tool_result_filters || [])
+        scoped = (@_scoped_tool_result_filters || {})[tool_class] || []
+        global + scoped
+      end
+
+      # Coerce +filter+ to an instance: if a Class is passed, call +.new+;
+      # otherwise return the object as-is.
+      # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+      # @return [Phronomy::Filter::Base]
+      # @api private
+      def _resolve_filter(filter)
+        filter.is_a?(Class) ? filter.new : filter
+      end
+    end
+  end
+end

data/lib/phronomy/agent/handoff/{handoff_context.rb → transfer_context.rb}

@@ -2,7 +2,7 @@
 
 module Phronomy
   module Agent
-    class HandoffContext
+    class TransferContext
       Provenance = Data.define(
         :origin_agent_id,
         :origin_record_id,
@@ -59,7 +59,7 @@ module Phronomy
         def initialize(**values)
           provenance = values.fetch(:provenance)
           unless provenance.is_a?(Provenance)
-            raise ArgumentError, "HandoffContext::Item provenance must be Provenance"
+            raise ArgumentError, "TransferContext::Item provenance must be Provenance"
           end
           format = (values[:content_format] || :text).to_sym
           unless %i[text json].include?(format)
@@ -96,7 +96,7 @@ module Phronomy
 
       def self.from_h(value)
         source = value.transform_keys(&:to_s)
-        raise ArgumentError, "HandoffContext schema mismatch" unless source.keys.sort == %w[items responsibility]
+        raise ArgumentError, "TransferContext schema mismatch" unless source.keys.sort == %w[items responsibility]
         new(responsibility: source.fetch("responsibility"), items: source.fetch("items").map do |raw|
           values = raw.transform_keys(&:to_sym)
           values[:provenance] = Provenance.new(**values.fetch(:provenance).transform_keys(&:to_sym))
@@ -111,7 +111,7 @@ module Phronomy
         @items = Array(items).freeze
         raise ArgumentError, "Handoff Context responsibility must not be empty" if @responsibility.strip.empty?
         unless @items.all? { |item| item.is_a?(Item) }
-          raise ArgumentError, "Handoff Context items must be HandoffContext::Item values"
+          raise ArgumentError, "Handoff Context items must be TransferContext::Item values"
         end
         freeze
       end

data/lib/phronomy/agent/handoff/{handoff_projection.rb → transfer_projection.rb}

@@ -2,32 +2,19 @@
 
 module Phronomy
   module Agent
-    class HandoffProjection
+    class TransferProjection
       CONTROL_CATEGORIES = %i[instruction handoff_responsibility].freeze
       JSON_CATEGORIES = %i[assistant_message tool_message].freeze
 
       Identity = Data.define(:agent_id)
-      Edge = Data.define(:policy, :target_agent)
-      Snapshot = Data.define(:handoff, :responsibility, :selection_intent)
-      private_constant :Identity, :Edge, :Snapshot
-
-      # A terminal command contains values only, captured on EventLoop.
-      def build_terminal(view:, manifest:, persistence:, source_agent_id:)
-        request = Snapshot.new(
-          handoff: Edge.new(policy: HandoffPolicy.from_h(view.policy), target_agent: Identity.new(agent_id: view.target_agent_id)),
-          responsibility: view.responsibility,
-          selection_intent: view.selection_intent.transform_keys(&:to_sym)
-        )
-        build(request: request, manifest: manifest, persistence: persistence,
-          source_agent: Identity.new(agent_id: source_agent_id))
-      end
+      private_constant :Identity
 
       def build(request:, manifest:, persistence:, source_agent:)
-        unless request.is_a?(HandoffRequest) || request.is_a?(Snapshot)
-          raise ArgumentError, "request must be a HandoffRequest"
+        unless request.is_a?(ControlRequest)
+          raise ArgumentError, "request must be an Agent::ControlRequest"
         end
-        unless manifest.is_a?(Phronomy::Agent::LLMInputManifest)
-          raise ArgumentError, "manifest must be an LLMInputManifest"
+        unless manifest.is_a?(Phronomy::Context::LLMInputManifest)
+          raise ArgumentError, "manifest must be an Phronomy::Context::LLMInputManifest"
         end
 
         groups = project_visible_groups(manifest)
@@ -42,12 +29,12 @@ module Phronomy
               policy_category: group.fetch(:policy_category),
               persistence: persistence,
               source_agent: source_agent,
-              target_agent: request.handoff.target_agent
+              target_agent: Identity.new(agent_id: request.target_agent_id)
             )
           end
         end
 
-        HandoffContext.new(
+        TransferContext.new(
           responsibility: request.responsibility,
           items: items
         )
@@ -116,7 +103,7 @@ module Phronomy
         end
 
         # Compatibility for finalized pre-ACS-04 manifests. New manifests use
-        # context_policy_conversation_group_id and do not recreate Selection::Unit.
+        # context_policy_conversation_group_id and do not recreate Phronomy::Context::Unit.
         unit_id = segment.metadata["selection_unit_id"] ||
           segment.metadata[:selection_unit_id]
         return "unit:#{unit_id}" if unit_id
@@ -125,13 +112,7 @@ module Phronomy
       end
 
       def include_group?(request, category)
-        policy = request.handoff.policy
-        return true if policy.required?(category)
-        return false if policy.forbidden?(category)
-
-        request.selection_intent.fetch(category) do
-          policy.default_include?(category)
-        end
+        request.selection.fetch(category, false)
       end
 
       def materialize_item(segment, policy_category:, persistence:, source_agent:, target_agent:)
@@ -147,7 +128,7 @@ module Phronomy
           target_agent: target_agent
         )
 
-        HandoffContext::Item.new(
+        TransferContext::Item.new(
           candidate_category: category,
           policy_category: policy_category,
           role: segment.role,
@@ -169,7 +150,7 @@ module Phronomy
           metadata[:context_policy_content_format]
         if explicit
           format = explicit.to_sym
-          unless Phronomy::Agent::ContextPolicyInput::CONTENT_FORMATS.include?(format)
+          unless Phronomy::Context::ContextPolicyInput::CONTENT_FORMATS.include?(format)
             raise Phronomy::HandoffError,
               "unsupported Context content format in Manifest: #{explicit.inspect}"
           end
@@ -182,7 +163,7 @@ module Phronomy
       def provenance_for(metadata, segment:, source_agent:, target_agent:)
         inherited = metadata["handoff_provenance"]
         if inherited
-          base = HandoffContext::Provenance.new(
+          base = TransferContext::Provenance.new(
             origin_agent_id: inherited["origin_agent_id"] || inherited[:origin_agent_id],
             origin_record_id: inherited["origin_record_id"] || inherited[:origin_record_id],
             origin_execution_id: inherited["origin_execution_id"] || inherited[:origin_execution_id],
@@ -193,7 +174,7 @@ module Phronomy
           return base.forwarded_to(target_agent.agent_id)
         end
 
-        HandoffContext::Provenance.new(
+        TransferContext::Provenance.new(
           origin_agent_id: metadata["source_agent_id"] || source_agent.agent_id,
           origin_record_id: metadata["journal_record_id"],
           origin_execution_id: metadata["source_execution_id"],

data/lib/phronomy/{llm_contract/transport_error.rb → agent/handoff_error.rb}

@@ -3,5 +3,5 @@
 require_relative "../common/error"
 
 module Phronomy
-  class TransportError < Error; end
+  class HandoffError < Error; end
 end

data/lib/phronomy/agent/journal/journal_projection.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../../engine/concurrency/worker_input_restricted"
+require_relative "../../execution/concurrency/worker_input_restricted"
 
 module Phronomy
   module Agent

data/lib/phronomy/agent/knowledge_item.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Materialized knowledge accepted by create(knowledge:) without internal DTOs.
+    # @api public
+    KnowledgeItem = Data.define(:content, :metadata) do
+      def initialize(content:, metadata: {})
+        super(content: String(content).dup.freeze, metadata: Phronomy::Values::Immutable.copy(metadata))
+      end
+    end
+  end
+end

data/lib/phronomy/agent/lifecycle/agent_root.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../../engine/concurrency/worker_input_restricted"
+require_relative "../../execution/concurrency/worker_input_restricted"
 
 require "time"
 

data/lib/phronomy/agent/lifecycle/lifetime_api.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Public admission boundaries. The explicit operation capability belongs to
+    # C04, including queued work and domain completion after logical cancellation.
+    # @api private
+    module LifetimeApi
+      # Releases only the Runtime incarnation; durable state and Store stay intact.
+      # @return [TaskResult<Boolean>]
+      # @api public
+      def unload_async
+        return Phronomy::TaskResult.completed(false) if @_phronomy_runtime_owner_state == :unloaded
+
+        __assert_agent_accessible!
+        transition, start = __execution_environment.ownership.reserve_unload(self)
+        start ? transition.start : transition.result
+      rescue => error
+        Phronomy::TaskResult.failed(error)
+      end
+
+      # A timeout stops this wait, never the accepted release.
+      # @return [Boolean]
+      # @api public
+      def unload!(timeout: nil)
+        _check_event_loop_reentrancy(:unload!, :unload_async)
+        unload_async.wait_result(timeout: timeout)
+      end
+
+      private
+
+      def __with_operation(async: false, read_only: false)
+        lease = __acquire_operation!(read_only: read_only)
+        followed = false
+        value = yield
+        if async && lease
+          lease.follow(value)
+          followed = true
+        end
+        value
+      rescue Phronomy::AgentUnloadedError, Phronomy::AgentBusyError, Phronomy::RuntimeShutdownError => error
+        raise unless async
+        Phronomy::TaskResult.failed(error)
+      ensure
+        lease&.release unless followed
+      end
+
+      # Accepted C04 commands carry their admission/operation capability. Their
+      # continuations read the snapshot without entering the public admission gate.
+      def __root_for_operation
+        __assert_agent_accessible!
+        @root
+      end
+
+      def __acquire_operation!(read_only: false)
+        __assert_agent_accessible!
+        return nil if @_phronomy_runtime_owner_state == :constructing
+
+        __execution_environment.ownership.acquire_operation(self, read_only: read_only)
+      end
+
+      def __mark_unloaded!
+        @_phronomy_runtime_owner_state = :unloaded
+        @root = nil
+        @_phronomy_journal_records = [].freeze
+        @_phronomy_event_listener = nil
+        @_phronomy_execution_wiring = {}.freeze
+        @execution_coordinator = nil
+        @tool_approval_policy = @before_llm_input = nil
+        @_instance_input_filters = @_instance_output_filters = nil
+        @_instance_tool_result_filters = @_scoped_tool_result_filters = nil
+        @initial_retention = nil
+      end
+    end
+  end
+end

data/lib/phronomy/agent/lifecycle/operation_lease.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # C04 capability for accepted work. Never inferred from the current thread.
+    # @api private
+    class OperationLease
+      def initialize(registry, agent, token)
+        @registry, @agent, @token = registry, agent, token
+        @mutex = Mutex.new
+      end
+
+      def release
+        ownership = @mutex.synchronize do
+          next unless @registry
+          current = [@registry, @agent, @token]
+          @registry = @agent = @token = nil
+          current
+        end
+        ownership&.first&.release_operation(ownership[1], ownership[2])
+      end
+
+      def follow(task)
+        if task.respond_to?(:on_physical_complete)
+          task.on_physical_complete { release }
+        else
+          task.on_complete { |_value, _error| release }
+        end
+        task
+      end
+    end
+  end
+end

data/lib/phronomy/agent/lifecycle/operation_result.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Logical cancellation of a public handle does not release Agent ownership.
+    # Only the domain runner acknowledges the end of its accepted operation.
+    # @api private
+    class OperationResult < Phronomy::Concurrency::PhysicalCompletionTask
+      def initialize(agent:, name:)
+        super(name: name)
+        @operation_lease = agent.send(:__acquire_operation!)
+        @lifetime_mutex = Mutex.new
+        @work = 0
+        @finished = false
+        @released = false
+      end
+
+      def finish_operation!
+        @lifetime_mutex.synchronize { @finished = true }
+        release_if_quiet
+      end
+
+      def track(task)
+        @lifetime_mutex.synchronize { @work += 1 }
+        task.on_physical_complete do
+          @lifetime_mutex.synchronize { @work -= 1 }
+          release_if_quiet
+        end
+        task
+      end
+
+      def settle(value = nil, error: nil)
+        finish_operation!
+        error ? fail(error) : complete(value)
+      end
+
+      private
+
+      def release_if_quiet
+        released = @lifetime_mutex.synchronize do
+          next unless @finished && @work.zero? && !@released
+          @released = true
+          current = @operation_lease
+          @operation_lease = nil
+          [current]
+        end
+        return unless released
+        released.first&.release
+        mark_physical_complete!
+      end
+    end
+  end
+end