phronomy 0.27.0 → 0.29.0

data/lib/phronomy/agent/recovery/recovery_support.rb

@@ -15,31 +15,22 @@ module Phronomy
       end
 
       def normalize_provider_outcome(value)
-        return value if value.is_a?(Phronomy::Agent::ProviderCallOutcome)
+        return value if value.is_a?(Phronomy::LLMAdapter::Response)
 
         if value.is_a?(Hash)
-          return Phronomy::Agent::ProviderCallOutcome.from_h(value)
+          return Phronomy::LLMAdapter::Response.from_h(value)
         end
 
-        captured = Phronomy::Agent::ProviderCallOutcome.capture(value)
-        return captured if captured
-
         raise ArgumentError,
-          "LLM Recovery :succeeded requires a Provider result or ProviderCallOutcome-compatible Hash"
+          "LLM Recovery :succeeded requires an LLMAdapter::Response or its canonical Hash"
       end
 
       def resolution_failure(error)
-        {
-          "class" => error.class.name.to_s,
-          "message" => error.message.to_s
-        }.freeze
+        Phronomy::Error.diagnostic(error).freeze
       end
 
       def error_from_failure(failure)
-        hash = failure.to_h { |key, value| [key.to_s, value] }
-        Phronomy::Error.new(
-          "#{hash.fetch("class", "Error")}: #{hash.fetch("message", "Recovery-resolved failure")}"
-        )
+        Phronomy::Error.from_diagnostic(failure)
       end
 
       def event_payload(execution, descriptor)
@@ -47,7 +38,7 @@ module Phronomy
           execution_id: execution.execution_id,
           execution_revision: execution.execution_revision,
           reason: descriptor.fetch(:reason),
-          subject: Phronomy::Recovery.normalize_subject(
+          subject: Phronomy::Agent::RecoveryRules.normalize_subject(
             descriptor.fetch(:subject)
           ),
           allowed_outcomes: Array(
@@ -69,7 +60,7 @@ module Phronomy
             type: :llm_call,
             llm_call_id: llm_call_id
           },
-          allowed_outcomes: Phronomy::Recovery::OUTCOMES,
+          allowed_outcomes: Phronomy::Agent::RecoveryRules::OUTCOMES,
           facts: {
             manifest_ref: execution.metadata["manifest_ref"],
             call_sequence: execution.llm_calls.length + 1
@@ -103,7 +94,7 @@ module Phronomy
           allowed_outcomes: Array(
             recovery["allowed_outcomes"] ||
               recovery[:allowed_outcomes] ||
-              Phronomy::Recovery::OUTCOMES
+              Phronomy::Agent::RecoveryRules::OUTCOMES
           ).map(&:to_sym),
           facts: {
             tool_call_id: hash["tool_call_id"],
@@ -145,7 +136,7 @@ module Phronomy
             type: :tool_invocation,
             tool_invocation_id: first.fetch("tool_invocation_id")
           },
-          allowed_outcomes: Phronomy::Recovery::OUTCOMES,
+          allowed_outcomes: Phronomy::Agent::RecoveryRules::OUTCOMES,
           facts: {
             tool_call_id: first["tool_call_id"],
             tool_name: first["tool_name"],
@@ -194,7 +185,7 @@ module Phronomy
         end.freeze
       end
 
-      def build_recovery_hash(subjects, reason: :outcome_unknown, allowed_outcomes: Phronomy::Recovery::OUTCOMES)
+      def build_recovery_hash(subjects, reason: :outcome_unknown, allowed_outcomes: Phronomy::Agent::RecoveryRules::OUTCOMES)
         {
           "version" => ExecutionMetadata::CONTRACT_VERSION,
           "reason" => reason.to_s,

data/lib/phronomy/agent/reserved_execution.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Exact identity reserved by a coordinating domain. Correlation is immutable;
+    # mutable routing fences belong to the coordinator, never to this identity.
+    # @api public
+    ReservedExecution = Data.define(:agent_id, :execution_id, :correlation) do
+      def initialize(agent_id:, execution_id:, correlation: nil)
+        raise ArgumentError, "reserved identities must not be empty" if agent_id.to_s.empty? || execution_id.to_s.empty?
+        super(agent_id: agent_id.to_s.freeze, execution_id: execution_id.to_s.freeze,
+              correlation: Phronomy::Values::Immutable.copy(correlation))
+      end
+    end
+  end
+end

data/lib/phronomy/agent/retention.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # A durable reference prevents whole-Agent purge. The referencing domain
+    # decides when its opaque owner key can be released.
+    # @api public
+    Retention = Data.define(:agent_id, :execution_id, :owner_key) do
+      def initialize(agent_id:, owner_key:, execution_id: nil)
+        raise ArgumentError, "retention identities must not be empty" if agent_id.to_s.empty? || owner_key.to_s.empty?
+        super(agent_id: agent_id.to_s.freeze, execution_id: execution_id&.to_s&.freeze, owner_key: owner_key.to_s.freeze)
+      end
+
+      def to_h = {"agent_id" => agent_id, "execution_id" => execution_id, "owner_key" => owner_key}.freeze
+    end
+  end
+end

data/lib/phronomy/agent/runtime_binding/engine_environment.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Adapts the concrete Engine lifecycle and sessions to Agent's connection.
+    # Construction alone starts no Runtime resources and creates no registry.
+    # @api private
+    class EngineEnvironment < ExecutionEnvironment
+      def initialize(runtime: Phronomy::Runtime.instance)
+        @runtime = runtime
+      end
+
+      def registry = ExecutionRegistry.for(@runtime.event_loop)
+      def existing_registry = ExecutionRegistry.existing_for(@runtime)
+
+      def ownership
+        existing_ownership || @runtime.__register_shutdown_participant(
+          key: OwnershipRegistry, participant: OwnershipRegistry.new(environment: self)
+        )
+      end
+
+      def existing_ownership = @runtime.__shutdown_participant(key: OwnershipRegistry)
+      def executing? = @runtime.event_loop.current?
+      def session_phase(id) = @runtime.event_loop.fsm_session_state(id)
+
+      def submit(**options, &operation)
+        Phronomy::Execution.submit(runtime: @runtime, **options, &operation)
+      end
+
+      # Pool sizing is an execution resource choice, separate from Agent's
+      # authorization decision and timeout selection. Read at submission time.
+      def submit_authorization(timeout:, cancellation_token:, &operation)
+        submit(pool_name: :authorization,
+          size: Phronomy::RuntimeSettings.current.authorization_pool_size,
+          queue_size: Phronomy::RuntimeSettings.current.authorization_queue_size,
+          timeout: timeout, cancellation_token: cancellation_token,
+          on_full: :raise, &operation)
+      end
+
+      def build_llm_client(adapter:)
+        Phronomy::LLMAdapter::AsyncClient.new(adapter: adapter, submitter: self)
+      end
+
+      def build_agent_session(invocation:, resume_event: nil, resume_phase: nil)
+        EngineSessionBuilder.build(invocation: invocation, environment: self,
+          event_loop: @runtime.event_loop, resume_event: resume_event, resume_phase: resume_phase)
+      end
+
+      def build_tool_session(invocation:, parent_sink:, resume_event: nil, resume_phase: nil)
+        ToolSessionBuilder.build(invocation: invocation, environment: self,
+          event_loop: @runtime.event_loop, parent_event_sink: parent_sink,
+          resume_event: resume_event, resume_phase: resume_phase)
+      end
+
+      def register_session(session, completion:)
+        @runtime.event_loop.register(session, completion: completion)
+      end
+    end
+  end
+end

data/lib/phronomy/agent/runtime_binding/engine_session_builder.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Engine-only construction. State vocabulary, ordered guards and entry
+    # operations are supplied by the Agent framework, not defined here.
+    # @api private
+    class EngineSessionBuilder
+      def self.build(invocation:, environment:, event_loop:, resume_event: nil, resume_phase: nil)
+        event_sink = Phronomy::FSMSession::EventSink.new(event_loop: event_loop)
+        invocation.bind_event_sink!(event_sink)
+        actions = InvocationActions.build_entry_actions(invocation.agent,
+          environment, mode: invocation.mode, event_sink: event_sink)
+        phase_machine = PhaseMachineBuilder.new(entry_actions: actions).build
+
+        Phronomy::FSMSession.new(
+          context: invocation,
+          event_sink: event_sink,
+          entry_point: InvocationTransitions::ENTRY_POINT,
+          phase_machine_class: phase_machine,
+          entry_actions: {},
+          auto_state_set: InvocationTransitions::AUTO_STATE_SET,
+          declared_states: InvocationTransitions::DECLARED_STATES,
+          wait_state_names: InvocationTransitions::WAIT_STATES,
+          external_events: InvocationTransitions::EXTERNAL_EVENTS,
+          recursion_limit: InvocationTransitions.recursion_limit(invocation.agent.class.max_iterations),
+          event_loop: event_loop,
+          resume_event: resume_event,
+          resume_phase: resume_phase
+        )
+      end
+    end
+  end
+end

data/lib/phronomy/agent/runtime_binding/phase_machine_builder.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "state_machines"
+
+module Phronomy
+  module Agent
+    class PhaseMachineBuilder
+      def initialize(entry_actions: {}, transitions: InvocationTransitions, operation_name: "Agent")
+        @entry_actions = entry_actions
+        @transitions = transitions
+        @operation_name = operation_name
+      end
+
+      def build
+        entry_actions = @entry_actions
+        callback_builder = method(:build_entry_callback)
+        transitions = @transitions
+        declared_states = transitions::DECLARED_STATES
+        entry_point = transitions::ENTRY_POINT
+
+        Class.new do
+          attr_accessor :context, :current_event
+
+          state_machine :phase, initial: entry_point do
+            declared_states.each { |state_name| state state_name }
+
+            transitions::EVENTS.each do |event_name, definitions|
+              event event_name do
+                definitions.each do |definition|
+                  transition definition[:from] => definition[:to],
+                    :if => ->(machine) {
+                      transitions.allowed?(definition, machine.context)
+                    }
+                end
+              end
+            end
+
+            entry_actions.each do |state_name, callables|
+              callables.each do |callable|
+                after_transition(
+                  to: state_name,
+                  do: callback_builder.call(callable, state_name)
+                )
+              end
+            end
+          end
+        end
+      end
+
+      private
+
+      def build_entry_callback(callable, state_name)
+        ->(machine) {
+          result = callable.call(machine.context)
+          if result.is_a?(Phronomy::TaskResult)
+            raise Phronomy::InvalidAsyncEntryActionError,
+              "#{@operation_name} entry action for #{state_name.inspect} returned Phronomy::TaskResult"
+          end
+          machine.context = result if result.respond_to?(:set_graph_metadata)
+        }
+      end
+    end
+  end
+end

data/lib/phronomy/agent/runtime_binding/tool_session_builder.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Binds Agent Tool child progress to a concrete FSM session. Session routing
+    # is fresh for each incarnation and never replaces a durable Tool identity.
+    # @api private
+    class ToolSessionBuilder
+      def self.build(invocation:, environment:, event_loop:, parent_event_sink:,
+        resume_event: nil, resume_phase: nil)
+        event_sink = Phronomy::FSMSession::EventSink.new(event_loop: event_loop)
+        actions = ToolInvocationActions.build_entry_actions(environment, event_sink, parent_event_sink)
+        phase_machine = PhaseMachineBuilder.new(entry_actions: actions,
+          transitions: ToolInvocationTransitions, operation_name: "Tool").build
+
+        Phronomy::FSMSession.new(
+          context: invocation,
+          event_sink: event_sink,
+          entry_point: ToolInvocationTransitions::ENTRY_POINT,
+          phase_machine_class: phase_machine,
+          entry_actions: {},
+          auto_state_set: ToolInvocationTransitions::AUTO_STATE_SET,
+          declared_states: ToolInvocationTransitions::DECLARED_STATES,
+          wait_state_names: ToolInvocationTransitions::WAIT_STATES,
+          external_events: ToolInvocationTransitions::EXTERNAL_EVENTS,
+          recursion_limit: ToolInvocationTransitions::RECURSION_LIMIT,
+          event_loop: event_loop,
+          resume_event: resume_event,
+          resume_phase: resume_phase
+        )
+      end
+    end
+  end
+end

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

@@ -2,7 +2,7 @@
 
 module Phronomy
   module Agent
-    class RubyLLMMaterializer
+    class RuntimeInput
       RuntimeProjection = Data.define(
         :system, :messages, :tool_classes, :ask_message,
         :model_config, :manifest, :manifest_ref
@@ -63,7 +63,7 @@ module Phronomy
       private
 
       def segment_from_record(record, position: 0)
-        LLMInputManifest::Segment.new(
+        Phronomy::Context::LLMInputManifest::Segment.new(
           position: position,
           category: record.kind,
           role: record.role,
@@ -88,7 +88,7 @@ module Phronomy
       end
 
       def verify_adapter!(manifest)
-        actual = Phronomy.configuration.llm_adapter.class.name
+        actual = Phronomy::Agent::Settings.current.llm_adapter.class.name
         return if manifest.adapter_name.nil? || manifest.adapter_name == actual
 
         raise Phronomy::ConfigurationError,
@@ -97,19 +97,16 @@ module Phronomy
 
       def verify_tool_definitions!(manifest)
         unless manifest.tool_definitions_ref
-          return ToolDefinitionSet.build(
-            @agent,
-            additional_tools: @additional_tools
-          )
+          return @agent.send(:tool_definition_set, additional_tools: @additional_tools)
         end
 
         expected_definitions = fetch_json(manifest.tool_definitions_ref)
         additional = @additional_tools
         if additional.empty?
-          additional = Array(@agent.__coordination_config[:phronomy_handoff_bindings]).map(&:tool_class)
+          additional = Array(@agent.__execution_wiring[:phronomy_control_bindings]).map(&:tool_class)
         end
 
-        ToolDefinitionSet.build(@agent, additional_tools: additional)
+        @agent.send(:tool_definition_set, additional_tools: additional)
           .select_definitions(expected_definitions)
       end
 
@@ -130,7 +127,7 @@ module Phronomy
         when :tool_result
           raise ArgumentError, "raw Tool result is not an LLM message"
         else
-          RubyLLM::Message.new(
+          Phronomy::LLMAdapter::Message.new(
             role: segment.role,
             content: @persistence.contents.fetch_text(segment.content_ref),
             tool_call_id: segment.tool_call_id
@@ -151,39 +148,25 @@ module Phronomy
         end
 
         tool_calls = materialize_tool_calls(payload["tool_calls"])
-        RubyLLM::Message.new(
+        Phronomy::LLMAdapter::Message.new(
           role: role,
-          content: initial_content_for(role, payload.fetch("content", nil), tool_calls),
-          tool_calls: tool_calls.empty? ? nil : tool_calls,
+          content: payload.fetch("content", nil),
+          tool_calls: tool_calls,
           tool_call_id: payload["tool_call_id"],
-          model: payload["model_id"]
+          metadata: {"model_id" => payload["model_id"]}.compact
         )
       end
 
-      def initial_content_for(role, content, tool_calls)
-        return "" if role == :assistant && content.nil? && !tool_calls.empty?
-
-        (content.is_a?(Hash) || content.is_a?(Array)) ? JSON.generate(content) : content
-      end
-
       def materialize_tool_calls(payloads)
-        Array(payloads).each_with_object({}) do |payload, result|
-          tool_call_id = payload.fetch("id").to_s
-          if result.key?(tool_call_id)
-            raise ArgumentError, "duplicate Tool Call in assistant message: #{tool_call_id}"
-          end
-          result[tool_call_id] = materialize_tool_call(payload)
+        Array(payloads).map do |payload|
+          # Read the pre-unit6 durable format explicitly; SDK objects are never
+          # reconstituted during recovery. New records use opaque metadata.
+          metadata = payload.fetch("metadata", {}).dup
+          metadata["thought_signature"] = payload["thought_signature"] if payload["thought_signature"]
+          Phronomy::Tool::CallRequest.new(id: payload.fetch("id"), name: payload.fetch("name"),
+            arguments: payload.fetch("arguments", {}), metadata: metadata)
         end
       end
-
-      def materialize_tool_call(payload)
-        RubyLLM::ToolCall.new(
-          id: payload.fetch("id").to_s,
-          name: payload.fetch("name"),
-          arguments: payload.fetch("arguments", {}),
-          thought_signature: payload["thought_signature"]
-        )
-      end
     end
   end
 end

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

@@ -9,13 +9,15 @@ module Phronomy
       module_function
 
       def manifest_from_ref(agent, ref)
-        raw = agent.persistence.contents.fetch_json(ref)
-        Phronomy::Agent::LLMInputManifest.from_h(raw)
+        Phronomy::Persistence::StorageBoundary.call do
+          raw = agent.persistence.contents.fetch_json(ref)
+          Phronomy::Context::LLMInputManifest.from_h(raw)
+        end
       end
 
       def materialize_projection(agent, manifest_ref)
         manifest = manifest_from_ref(agent, manifest_ref)
-        projection = Phronomy::Agent::RubyLLMMaterializer.new(
+        projection = Phronomy::Agent::RuntimeInput.new(
           agent: agent,
           persistence: agent.persistence
         ).materialize(manifest: manifest, manifest_ref: manifest_ref)
@@ -40,7 +42,7 @@ module Phronomy
         else
           {}
         end
-        usage = Phronomy::TokenUsage.new(
+        usage = Phronomy::LLMAdapter::TokenUsage.new(
           input: usage_hash["input"] || usage_hash[:input] || usage_hash["input_tokens"] || usage_hash[:input_tokens],
           output: usage_hash["output"] || usage_hash[:output] || usage_hash["output_tokens"] || usage_hash[:output_tokens],
           cached: usage_hash["cached"] || usage_hash[:cached] || usage_hash["cache_read_tokens"] || usage_hash[:cache_read_tokens] || usage_hash["cached_tokens"] || usage_hash[:cached_tokens],

data/lib/phronomy/agent/settings.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "../common/configuration_error"
+
+module Phronomy
+  module Agent
+    # Agent-owned option values and policy validation. Composition supplies
+    # concrete components and default values; execution reads at existing sites.
+    # @api private
+    class Settings
+      class << self
+        # Bind at boot without reading settings or starting runtime resources.
+        def install_provider(&provider)
+          raise ArgumentError, "settings provider requires a block" unless provider
+          @provider = provider
+          nil
+        end
+
+        # Read only when requested; no cache or change notification is involved.
+        def current
+          @provider.call
+        end
+      end
+
+      STREAM_CALLBACK_ERROR_POLICIES = %i[report fail_task].freeze
+      private_constant :STREAM_CALLBACK_ERROR_POLICIES
+
+      attr_accessor :default_model, :before_llm_input, :agent_store, :llm_adapter, :authorization_timeout
+      attr_reader :stream_callback_error_policy
+
+      def initialize(llm_adapter:, authorization_timeout:, stream_callback_error_policy:)
+        @llm_adapter = llm_adapter
+        @authorization_timeout = authorization_timeout
+        self.stream_callback_error_policy = stream_callback_error_policy
+      end
+
+      def stream_callback_error_policy=(value)
+        unless STREAM_CALLBACK_ERROR_POLICIES.include?(value)
+          allowed = STREAM_CALLBACK_ERROR_POLICIES.map(&:inspect).join(", ")
+          raise Phronomy::ConfigurationError,
+            "stream_callback_error_policy must be one of: #{allowed}"
+        end
+        @stream_callback_error_policy = value
+      end
+    end
+  end
+end

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

@@ -14,7 +14,7 @@ module Phronomy
         @agent_id = agent_id
       end
 
-      def create_root(definition:, context:, knowledge:, metadata:)
+      def create_root(definition:, context:, knowledge:, metadata:, retention: nil)
         root = Agent::AgentRoot.create(
           agent_id: agent_id,
           agent_definition_id: definition.fetch(:id),
@@ -23,6 +23,7 @@ module Phronomy
         )
         persistence.transaction do |tx|
           tx.agents.create(root)
+          tx.retentions.retain(retention) if retention
           records = initial_context_records(tx: tx, root: root, context: context)
           records.concat(initial_knowledge_records(tx: tx, root: root, knowledge: knowledge))
           unless records.empty?
@@ -137,8 +138,8 @@ module Phronomy
           build_knowledge_record(
             tx: tx,
             root: root,
-            content: content,
-            metadata: {}
+            content: content.is_a?(KnowledgeItem) ? content.content : content,
+            metadata: content.is_a?(KnowledgeItem) ? content.metadata : {}
           )
         end
       end