phronomy 0.26.0 → 0.28.0

data/lib/phronomy/agent/filterable.rb

@@ -0,0 +1,182 @@
+# 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)
+        @_instance_input_filters ||= []
+        @_instance_input_filters << _resolve_filter(filter)
+        self
+      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)
+        @_instance_output_filters ||= []
+        @_instance_output_filters << _resolve_filter(filter)
+        self
+      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)
+        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
+
+      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_context.rb → handoff/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)
@@ -69,11 +69,11 @@ module Phronomy
             candidate_category: values.fetch(:candidate_category).to_sym,
             policy_category: values.fetch(:policy_category).to_sym,
             role: values[:role]&.to_sym,
-            content: Phronomy::Agent::Immutable.copy(values.fetch(:content)),
+            content: Phronomy::Values::Immutable.copy(values.fetch(:content)),
             content_format: format,
             tool_call_id: values[:tool_call_id]&.to_s&.freeze,
             provenance: provenance,
-            metadata: Phronomy::Agent::Immutable.copy(values[:metadata] || {})
+            metadata: Phronomy::Values::Immutable.copy(values[:metadata] || {})
           ))
           freeze
         end
@@ -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_projection.rb → handoff/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/agent/handoff_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  class HandoffError < Error; end
+end

data/lib/phronomy/agent/{journal_projection.rb → journal/journal_projection.rb}

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
+require_relative "../../execution/concurrency/worker_input_restricted"
+
 module Phronomy
   module Agent
     class JournalProjection
+      include Phronomy::Concurrency::WorkerInputRestricted
+
       MESSAGE_KINDS = %i[
         external_message
         assistant_message

data/lib/phronomy/agent/{journal_record.rb → journal/journal_record.rb}

@@ -41,9 +41,9 @@ module Phronomy
         ATTRIBUTES.each do |name|
           value = values.fetch(name)
           value = value.to_sym if %i[kind channel role visibility].include?(name) && value
-          instance_variable_set("@#{name}", Immutable.copy(value))
+          instance_variable_set("@#{name}", Phronomy::Values::Immutable.copy(value))
         end
-        Immutable.validate_canonical_json!(metadata, label: "Journal metadata")
+        Phronomy::Values::Immutable.validate_canonical_json!(metadata, label: "Journal metadata")
         freeze
       end
 
@@ -52,7 +52,7 @@ module Phronomy
       end
 
       # Current semantic payload representation. Persistence format identity and
-      # compatibility validation are owned by Persistence::DurableCodec.
+      # compatibility validation are owned by Agent::Persistence::Codec.
       def to_h
         ATTRIBUTES.to_h { |name| [name.to_s, public_send(name)] }
       end

data/lib/phronomy/agent/{llm_call_record.rb → journal/llm_call_record.rb}

@@ -31,11 +31,11 @@ module Phronomy
         ATTRIBUTES.each do |name|
           value = values.fetch(name)
           value = value.to_sym if name == :status
-          instance_variable_set("@#{name}", Immutable.copy(value))
+          instance_variable_set("@#{name}", Phronomy::Values::Immutable.copy(value))
         end
         raise ArgumentError, "unknown LLM Call status: #{status.inspect}" unless STATUSES.include?(status)
         raise ArgumentError, "LLM Call sequence must be positive" unless sequence.positive?
-        Immutable.validate_canonical_json!(metadata, label: "LLM Call metadata")
+        Phronomy::Values::Immutable.validate_canonical_json!(metadata, label: "LLM Call metadata")
         freeze
       end
 

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/{agent_root.rb → lifecycle/agent_root.rb}

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
+require_relative "../../execution/concurrency/worker_input_restricted"
+
 require "time"
 
 module Phronomy
   module Agent
     class AgentRoot
+      include Phronomy::Concurrency::WorkerInputRestricted
+
       LIFECYCLE_STATUSES = %i[idle active suspended closed invalidated].freeze
 
       ATTRIBUTES = %i[
@@ -36,7 +40,7 @@ module Phronomy
         ATTRIBUTES.each do |name|
           value = attributes.fetch(name)
           value = value.to_sym if name == :lifecycle_status
-          instance_variable_set("@#{name}", Immutable.copy(value))
+          instance_variable_set("@#{name}", Phronomy::Values::Immutable.copy(value))
         end
         unless LIFECYCLE_STATUSES.include?(lifecycle_status)
           raise ArgumentError, "unknown Agent lifecycle status: #{lifecycle_status.inspect}"
@@ -44,7 +48,7 @@ module Phronomy
         raise ArgumentError, "agent_revision must be non-negative" if agent_revision.negative?
         raise ArgumentError, "context_revision must be non-negative" if context_revision.negative?
         raise ArgumentError, "journal_position must be non-negative" if journal_position.negative?
-        Immutable.validate_canonical_json!(metadata, label: "Agent metadata")
+        Phronomy::Values::Immutable.validate_canonical_json!(metadata, label: "Agent metadata")
         freeze
       end
 

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Agent owns this fresh-instance construction contract. Application
+    # composition supplies the concrete default once during loading.
+    # @api private
+    module DefaultPersistence
+      FACTORIES = {}
+      private_constant :FACTORIES
+
+      # A private boot binding, not an application extension registry.
+      # @api private
+      def self.install_factory(factory)
+        raise ArgumentError, "factory must respond to call" unless factory.respond_to?(:call)
+
+        FACTORIES.replace(persistence: factory).freeze
+        nil
+      end
+
+      # Invoke only after explicit and configured instances have been excluded.
+      # No instance is cached, shared, or installed in global configuration.
+      # @api private
+      def self.build
+        FACTORIES.fetch(:persistence).call
+      end
+    end
+  end
+end

data/lib/phronomy/{engine/runtime/agent_ownership_registry.rb → agent/lifecycle/ownership_registry.rb}

@@ -1,18 +1,27 @@
 # frozen_string_literal: true
 
 module Phronomy
-  class Runtime
+  module Agent
     # Process-local authoritative owner registry for mutable Agent instances.
     #
     # This is not a cache. While a Runtime is alive, one agent_id maps to at most
     # one mutable live Agent object. Construction is reserved before durable
     # create/load so concurrent callers cannot materialize independent objects.
-    class AgentOwnershipRegistry
+    # @api private
+    class OwnershipRegistry
+      # Candidates have no side effects. Runtime retains the first registration.
+      # Existing instances remain available for lookup and transition completion
+      # after admission closes; their own gate rejects new ownership changes.
+      def self.current = ExecutionEnvironment.current.ownership
+      def self.existing_current = ExecutionEnvironment.current.existing_ownership
+      def self.for(environment) = environment.ownership
+      def self.existing_for(environment) = environment.existing_ownership
+
       Entry = Data.define(:state, :agent, :token)
       private_constant :Entry
 
-      def initialize(runtime:)
-        @runtime = runtime
+      def initialize(environment:)
+        @environment = environment
         @mutex = Mutex.new
         @condition = ConditionVariable.new
         @entries = {}
@@ -24,7 +33,7 @@ module Phronomy
         token = reserve_create!(key)
 
         begin
-          agent = yield(@runtime)
+          agent = yield(@environment)
         rescue Phronomy::AgentAlreadyExistsError,
           Phronomy::Persistence::ConflictError,
           Phronomy::Persistence::NotFoundError,
@@ -84,7 +93,7 @@ module Phronomy
         end
 
         begin
-          agent = yield(@runtime)
+          agent = yield(@environment)
           publish_constructed!(
             key,
             token,
@@ -147,7 +156,7 @@ module Phronomy
           end
           @entries[key] = Entry.new(state: :purging, agent: agent, token: token)
         end
-        agent.send(:__mark_purging!, @runtime)
+        agent.send(:__mark_purging!, @environment)
         token
       end
 
@@ -156,10 +165,10 @@ module Phronomy
         @mutex.synchronize do
           entry = @entries[key]
           validate_purge_entry!(entry, agent, token, key)
+          agent.send(:__mark_purged!, @environment)
           @entries.delete(key)
           @condition.broadcast
         end
-        agent.send(:__mark_purged!, @runtime)
         true
       end
 
@@ -169,10 +178,10 @@ module Phronomy
         @mutex.synchronize do
           entry = @entries[key]
           validate_purge_entry!(entry, agent, token, key)
+          agent.send(:__restore_live_after_purge_abort!, @environment)
           @entries[key] = Entry.new(state: :live, agent: agent, token: nil)
           @condition.broadcast
         end
-        agent.send(:__restore_live_after_purge_abort!, @runtime)
         true
       end
 
@@ -183,6 +192,7 @@ module Phronomy
         key = normalize_agent_id(agent.agent_id)
         @mutex.synchronize do
           validate_purge_entry!(@entries[key], agent, token, key)
+          agent.send(:__mark_ownership_recovery_required!, @environment)
           @entries[key] = Entry.new(
             state: :recovery_required,
             agent: agent,
@@ -190,7 +200,6 @@ module Phronomy
           )
           @condition.broadcast
         end
-        agent.send(:__mark_ownership_recovery_required!, @runtime)
         true
       end
 
@@ -204,7 +213,7 @@ module Phronomy
 
       # Live/recovery-required entries do not prevent Runtime shutdown. Only an
       # ownership transition that is still actively changing state must settle.
-      def wait_until_stable(deadline)
+      def wait_until_idle(deadline)
         @mutex.synchronize do
           while @entries.values.any? { |entry| %i[constructing purging].include?(entry.state) }
             remaining = deadline - monotonic_now
@@ -217,7 +226,7 @@ module Phronomy
         end
       end
 
-      def shutdown!
+      def after_runtime_shutdown
         agents = @mutex.synchronize do
           @state = :terminated
           owned = @entries.values.filter_map(&:agent).uniq
@@ -225,7 +234,7 @@ module Phronomy
           @condition.broadcast
           owned
         end
-        agents.each { |agent| agent.send(:__release_runtime_owner!, @runtime) }
+        agents.each { |agent| agent.send(:__release_runtime_owner!, @environment) }
         true
       end
 
@@ -253,7 +262,7 @@ module Phronomy
             "constructed Agent identity mismatch: reserved #{key.inspect}, got #{agent.agent_id.inspect}"
         end
 
-        agent.send(:__bind_runtime_owner!, @runtime)
+        agent.send(:__bind_runtime_owner!, @environment)
         @mutex.synchronize do
           entry = @entries[key]
           unless entry&.state == :constructing && entry.token.equal?(token)
@@ -268,7 +277,7 @@ module Phronomy
         # :nocov:
         if fail_closed
           fail_construction_closed!(key, token, agent: agent)
-          agent&.send(:__mark_ownership_recovery_required!, @runtime)
+          agent&.send(:__mark_ownership_recovery_required!, @environment)
         else
           release_construction!(key, token)
         end