phronomy 0.28.0 → 0.29.0

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

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Owns the Agents materialized within one application operation. A scope is
+    # Runtime-bound, process-local, and must not be persisted as Workflow state.
+    # @api public
+    class Scope
+      # @api private
+      def self.open
+        raise ArgumentError, "open_scope requires a block" unless block_given?
+        if Phronomy::WaitPolicy.blocking_forbidden?
+          raise Phronomy::EventLoopReentrancyError, "Agent.open_scope cannot block EventLoop"
+        end
+
+        scope = new(environment: ExecutionEnvironment.current)
+        result = nil
+        begin
+          result = yield(scope)
+          result = result.wait_result if result.is_a?(Phronomy::TaskResult)
+        rescue Exception => primary # standard:disable Lint/RescueException
+          raise
+        ensure
+          failures = scope.send(:__close)
+          if primary
+            failures.each do |failure|
+              error = failure.fetch(:error)
+              Phronomy::RuntimeSettings.current.logger&.warn(
+                "[Agent scope] cleanup failed agent_id=#{failure.fetch(:agent_id).inspect}: #{error.class}: #{error.message}"
+              )
+            rescue
+              nil
+            end
+          elsif failures.any?
+            raise ScopeCleanupError.new(failures: failures, result: result)
+          end
+        end
+        result
+      end
+      private_class_method :open
+
+      def initialize(environment:)
+        @environment = environment
+        @ownership = environment.ownership
+        @owner_token = Object.new.freeze
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+        @state = :open
+        @receipts = {}
+        @agents = {}
+      end
+      private_class_method :new
+
+      # @return [Agent::Base]
+      # @api public
+      def create(agent_class, **options, &listener)
+        check_blocking!
+        materialize(:create, agent_class, options, listener, async: false)
+      end
+
+      # @return [TaskResult<Agent::Base>]
+      # @api public
+      def create_async(agent_class, **options, &listener)
+        materialize(:create, agent_class, options, listener, async: true)
+      rescue => error
+        Phronomy::TaskResult.failed(error)
+      end
+
+      # Repeated load in this scope returns the same live owner. Supplying a new
+      # listener or different Store for an already live instance is rejected.
+      # @return [Agent::Base]
+      # @api public
+      def load(agent_class, agent_id, persistence:, **options, &listener)
+        check_blocking!
+        materialize(:load, agent_class, options.merge(agent_id: agent_id, persistence: persistence), listener, async: false)
+      end
+
+      # @return [TaskResult<Agent::Base>]
+      # @api public
+      def load_async(agent_class, agent_id, persistence:, **options, &listener)
+        materialize(:load, agent_class, options.merge(agent_id: agent_id, persistence: persistence), listener, async: true)
+      rescue => error
+        Phronomy::TaskResult.failed(error)
+      end
+
+      # @api private
+      def __close
+        agents = @mutex.synchronize do
+          @state = :closing
+          @condition.wait(@mutex) until @receipts.empty?
+          @agents.values.dup
+        end
+        failures = []
+        agents.each do |agent|
+          agent.unload!
+        rescue => error
+          failures << {agent_id: agent.agent_id, error: error}.freeze
+        end
+        @mutex.synchronize do
+          @agents.clear
+          @environment = @ownership = @owner_token = nil
+          @state = :closed
+        end
+        failures.freeze
+      end
+      private :__close
+
+      private
+
+      def check_blocking!
+        return unless Phronomy::WaitPolicy.blocking_forbidden?
+
+        raise Phronomy::EventLoopReentrancyError, "Agent scope materialization cannot block EventLoop; use create_async/load_async"
+      end
+
+      def materialize(kind, agent_class, options, listener, async:)
+        unless agent_class.is_a?(Class) && agent_class <= Base
+          raise ArgumentError, "agent_class must be an Agent::Base subclass"
+        end
+        if options[:on_event] && listener
+          raise ArgumentError, "Provide either on_event: or a block, not both"
+        end
+        if kind == :load && !options[:persistence]
+          raise ArgumentError, "persistence is required"
+        end
+        key = (options[:agent_id] || (SecureRandom.uuid if kind == :create)).to_s.dup.freeze
+        raise ArgumentError, "agent_id must not be empty" if key.empty?
+        options = options.merge(agent_id: key)
+        receipt = Object.new.freeze
+        @mutex.synchronize do
+          raise Phronomy::Error, "Agent scope is #{@state}" unless @state == :open
+          @receipts[receipt] = key
+        end
+        operation = -> { acquire(kind, agent_class, key, options, listener) }
+        if async
+          begin
+            task = @environment.submit(on_full: :raise, &operation)
+            task.on_physical_complete { finish_receipt(receipt) }
+            task
+          rescue
+            finish_receipt(receipt)
+            raise
+          end
+        else
+          begin
+            operation.call
+          ensure
+            finish_receipt(receipt)
+          end
+        end
+      end
+
+      def acquire(kind, agent_class, key, options, listener)
+        materialized = false
+        agent = @ownership.public_send(kind, key, expected_class: agent_class, scope_owner: @owner_token) do |environment|
+          materialized = true
+          instance = agent_class.send(:__construct_owned_agent, environment, key,
+            **options, load_existing: kind == :load, &listener)
+          RecoveryCoordinator.new(instance).recover_on_load! if kind == :load
+          instance
+        end
+        # Register before any result or post-materialization check reaches the
+        # caller, even when scope closure began while the worker was running.
+        @mutex.synchronize { @agents[agent.object_id] = agent }
+        if kind == :load
+          unless agent.persistence.equal?(options[:persistence])
+            raise Phronomy::ConfigurationError, "Agent #{key.inspect} is already live with a different Persistence instance"
+          end
+          if !materialized && (options[:on_event] || listener)
+            raise Phronomy::ConfigurationError, "Agent #{key.inspect} is already live; load cannot re-bind on_event"
+          end
+        end
+        agent
+      rescue Phronomy::Persistence::ConflictError => error
+        raise unless kind == :create
+        raise Phronomy::AgentAlreadyExistsError, "Agent #{key.inspect} already exists durably: #{error.message}"
+      rescue => error
+        # A fail-closed construction remains reserved in C04. Do not purge or
+        # release that reservation just because no instance reached this scope.
+        report_materialization_error(key, error)
+        raise
+      end
+
+      def finish_receipt(receipt)
+        @mutex.synchronize do
+          @receipts.delete(receipt)
+          @condition.broadcast
+        end
+      end
+
+      def report_materialization_error(key, error)
+        Phronomy::RuntimeSettings.current.logger&.warn("[Agent scope] materialization failed agent_id=#{key.inspect}: #{error.class}: #{error.message}")
+      rescue
+        nil
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Successful application work with one or more failed Agent releases.
+    # Original exceptions and the successful result remain available to the caller.
+    # @api public
+    class ScopeCleanupError < Phronomy::Error
+      attr_reader :failures, :result
+
+      def initialize(failures:, result:)
+        @failures = failures.map { |failure| failure.dup.freeze }.freeze
+        @result = result
+        super("Agent scope cleanup failed for: #{@failures.map { |f| f.fetch(:agent_id) }.join(", ")}",
+          code: "agent.scope_cleanup_failed")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Agent-owned two-phase release. The worker only checks durable facts; the
+    # EventLoop completes the exact process-local reservation after physical I/O.
+    # @api private
+    class UnloadTransition
+      Command = Data.define(:coordinator, :phase)
+      private_constant :Command
+
+      attr_reader :result
+
+      def initialize(agent:, environment:, ownership:)
+        @agent, @environment, @ownership = agent, environment, ownership
+        @result = Phronomy::TaskResult.deferred(name: "agent-unload:#{agent.agent_id}")
+        @mutex = Mutex.new
+        @finished = false
+      end
+
+      def start
+        post(:check)
+        @result
+      end
+
+      def deliver_on_event_loop(command)
+        if command.phase == :check
+          if @environment.existing_registry&.agent_execution_admitted?(@agent.agent_id)
+            raise Phronomy::AgentBusyError, "Agent #{@agent.agent_id.inspect} has a nonterminal execution"
+          end
+          agent_id, persistence = @agent.agent_id, @agent.persistence
+          task = @environment.submit(on_full: :raise) do
+            persistence.transaction do |tx|
+              tx.executions.assert_idle!(agent_id)
+              tx.guard_agent!(agent_id)
+              unless tx.retentions.list(agent_id).empty?
+                raise Phronomy::AgentBusyError, "Agent #{agent_id.inspect} is retained by durable coordination"
+              end
+            end
+          end
+          task.on_complete do |_value, error|
+            @read_error = error
+            task.on_physical_complete { post(:apply) }
+          end
+        else
+          finish(@read_error)
+        end
+      rescue => error
+        finish(error)
+      end
+
+      private
+
+      def post(phase)
+        accepted = @environment.registry.post(Command.new(coordinator: self, phase: phase), completion: @result)
+        finish(Phronomy::RuntimeShutdownError.new("EventLoop rejected Agent unload #{phase}")) unless accepted
+      rescue => error
+        finish(error)
+      end
+
+      def finish(error)
+        first = @mutex.synchronize do
+          next false if @finished
+          @finished = true
+        end
+        return unless first
+
+        begin
+          @ownership.finish_unload(@agent, self, success: error.nil?)
+        rescue => ownership_error
+          error ||= ownership_error
+        end
+        @agent = @environment = @ownership = nil
+        error ? @result.fail(error) : @result.complete(true)
+      end
+    end
+  end
+end

data/lib/phronomy/agent/recovery/recovery_coordinator/continuation.rb

@@ -52,9 +52,9 @@ module Phronomy
             environment.registry.mark_agent_execution_admission(agent.agent_id,
               execution_id: execution.execution_id, state: :recovery_required)
             deliver_resolution_required(execution, coordination_recovery_descriptor(execution))
-            completion.complete({execution_id: execution.execution_id,
-                                 execution_revision: execution.execution_revision,
-                                 recovery: :resolution_required}.freeze)
+            agent.send(:_complete_result_task, completion, {execution_id: execution.execution_id,
+                                                            execution_revision: execution.execution_revision,
+                                                            recovery: :resolution_required}.freeze)
             return
           end
 

data/lib/phronomy/agent/recovery/recovery_coordinator/installation.rb

@@ -38,7 +38,7 @@ module Phronomy
         end
 
         def prepare_plan(execution)
-          root = agent.agent_root
+          root = agent.send(:__root_for_operation)
           manifest_ref = execution.metadata["manifest_ref"]
           base_ref = execution.metadata["base_manifest_ref"] ||
             manifest_ref
@@ -209,7 +209,7 @@ module Phronomy
                 }
               )
             end
-            command.completion.complete(agent)
+            agent.send(:_complete_result_task, command.completion, agent)
             return
           end
 
@@ -246,7 +246,7 @@ module Phronomy
                 result: payload
               )
             end
-            command.completion.complete(agent)
+            agent.send(:_complete_result_task, command.completion, agent)
           when Phronomy::Agent::RecoveryRules::RESUMABLE
             continue_resumable_on_event_loop(
               execution,
@@ -288,7 +288,7 @@ module Phronomy
               end
             end
           end
-          command.completion.fail(caught)
+          agent.send(:_fail_result_task, command.completion, caught)
           # simplecov:enable
         end
 
@@ -317,7 +317,7 @@ module Phronomy
           if framework_batch?(execution)
             internal = Phronomy::TaskResult.deferred(name: "framework-tool-recovery:#{execution.execution_id}")
             continue_recovery_on_event_loop(execution, internal, material: material)
-            completion.complete(agent)
+            agent.send(:_complete_result_task, completion, agent)
             return
           end
 
@@ -359,11 +359,11 @@ module Phronomy
               result_task: internal_task,
               error: nil
             ))
-            completion.complete(agent)
+            agent.send(:_complete_result_task, completion, agent)
           when :recovery_tools_completed, :recovery_provider_completed, :recovery_resolved_failed
             internal_task = Phronomy::TaskResult.deferred(name: "agent-recovery-auto:#{execution.execution_id}")
             continue_recovery_on_event_loop(execution, internal_task, material: material)
-            completion.complete(agent)
+            agent.send(:_complete_result_task, completion, agent)
           else
             raise Phronomy::ExecutionRehydrationRequiredError,
               "no automatic continuation for #{execution.phase.inspect}"

data/lib/phronomy/agent/recovery/recovery_coordinator/resolution.rb

@@ -14,24 +14,22 @@ module Phronomy
             request.execution_id
           )
           unless state && state.agent.equal?(agent)
-            request.completion.fail(
+            agent.send(:_fail_result_task, request.completion,
               Phronomy::ExecutionRehydrationRequiredError.new(
                 "no live recovered execution #{request.execution_id}"
-              )
-            )
+              ))
             return
           end
 
           current = state.execution
           unless current.execution_revision ==
               request.expected_execution_revision
-            request.completion.fail(
+            agent.send(:_fail_result_task, request.completion,
               Phronomy::Persistence::StateConflictError.new(
                 "Recovery resolution revision conflict: expected " \
                 "#{request.expected_execution_revision}, actual " \
                 "#{current.execution_revision}"
-              )
-            )
+              ))
             return
           end
 
@@ -42,28 +40,26 @@ module Phronomy
                 descriptor.fetch(:subject),
                 request.subject
               )
-            request.completion.fail(
+            agent.send(:_fail_result_task, request.completion,
               ArgumentError.new(
                 "Recovery subject is not current for execution #{request.execution_id}"
-              )
-            )
+              ))
             return
           end
 
           unless Array(
             descriptor.fetch(:allowed_outcomes)
           ).map(&:to_sym).include?(request.outcome)
-            request.completion.fail(
+            agent.send(:_fail_result_task, request.completion,
               ArgumentError.new(
                 "Recovery outcome #{request.outcome.inspect} is not allowed for the current subject"
-              )
-            )
+              ))
             return
           end
 
           operation = ResolutionOperation.new(
             execution: current,
-            root: agent.agent_root,
+            root: agent.send(:__root_for_operation),
             subject: request.subject,
             outcome: request.outcome,
             result: request.result,
@@ -77,6 +73,7 @@ module Phronomy
           task = @environment.submit(on_full: :raise) do
             prepare_resolution(operation)
           end
+          request.completion.track(task) if request.completion.respond_to?(:track)
           task.on_complete do |result, error|
             ready = ResolveReady.new(
               coordinator: self,
@@ -86,15 +83,14 @@ module Phronomy
               error: error
             )
             unless post_control(ready)
-              request.completion.fail(
+              agent.send(:_fail_result_task, request.completion,
                 Phronomy::RuntimeShutdownError.new(
                   "EventLoop rejected Recovery resolution apply"
-                )
-              )
+                ))
             end
           end
         rescue => caught
-          request.completion.fail(caught)
+          agent.send(:_fail_result_task, request.completion, caught)
         end
 
         def perform_resolution(operation)
@@ -498,7 +494,7 @@ module Phronomy
 
           continue_recovery_on_event_loop(result.execution, request.completion, material: result.material)
         rescue => caught
-          request.completion.fail(caught)
+          agent.send(:_fail_result_task, request.completion, caught)
         end
       end
     end

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

@@ -147,9 +147,8 @@ module Phronomy
         failure = error_present ?
           RecoverySupport.resolution_failure(error) : nil
 
-        completion = Phronomy::TaskResult.deferred(
-          name: "agent-recovery-resolve:#{execution_id}"
-        )
+        completion = OperationResult.new(agent: agent,
+          name: "agent-recovery-resolve:#{execution_id}")
         command = ResolveCommand.new(
           coordinator: self,
           execution_id: execution_id.to_s.freeze,
@@ -162,18 +161,15 @@ module Phronomy
           completion: completion
         )
         unless post_control(command)
-          completion.fail(
-            Phronomy::RuntimeShutdownError.new(
-              "EventLoop rejected Agent Recovery resolution"
-            )
-          )
+          agent.send(:_fail_result_task, completion,
+            Phronomy::RuntimeShutdownError.new("EventLoop rejected Agent Recovery resolution"))
         end
         completion
       rescue => caught
         completion ||= Phronomy::TaskResult.deferred(
           name: "agent-recovery-resolve:#{execution_id}"
         )
-        completion.fail(caught)
+        agent.send(:_fail_result_task, completion, caught)
         completion
       end
 

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

@@ -26,17 +26,11 @@ module Phronomy
       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)

data/lib/phronomy/agent/stream_callback_error.rb

@@ -22,14 +22,14 @@ module Phronomy
     # @return [Exception] original Application callback exception
     attr_reader :original_error
 
-    def initialize(event_type:, original_error:, result: nil)
+    def initialize(event_type:, original_error:, result: nil, code: nil)
       @event_type = event_type
       @original_error = original_error
       @result = result
 
       super(
         "Stream callback failed while handling #{event_type.inspect}: " \
-        "#{original_error.class}: #{original_error.message}"
+        "#{original_error.class}: #{original_error.message}", code: code
       )
       set_backtrace(original_error.backtrace)
     end

data/lib/phronomy/common/error.rb

@@ -1,5 +1,69 @@
 # frozen_string_literal: true
 
 module Phronomy
-  class Error < StandardError; end
+  class Error < StandardError
+    # Optional stable reason supplied by the owner of the failed operation.
+    # It does not imply retry safety or replace execution status.
+    # @api public
+    attr_reader :code
+
+    # Existing message-only construction retains StandardError behavior.
+    # @api public
+    def initialize(message = nil, code: nil)
+      raise ArgumentError, "error code must be a String or nil" unless code.nil? || code.is_a?(String)
+      @code = code&.dup&.freeze
+      super(message)
+    end
+
+    # Generic diagnostic transport. No domain-specific interpretation.
+    # External exceptions are not extended with this protocol.
+    # @api private
+    def self.diagnostic(error)
+      diagnostic = {"class" => error.class.name, "message" => error.message}
+      diagnostic["code"] = error.code if error.is_a?(Phronomy::Error) && error.code
+      cause = error.cause
+      diagnostic["cause"] = cause_diagnostic(cause, remaining: 3, seen: [error.object_id]) if cause
+      diagnostic
+    end
+
+    # Restores data, never a saved class name or arbitrary instance attributes.
+    # Restored causes are generic errors as well. Old diagnostics remain valid.
+    # @api private
+    def self.from_diagnostic(value, remaining: 3)
+      hash = value.to_h { |key, item| [key.to_s, item] }
+      error = Phronomy::Error.new(
+        "#{hash.fetch("class", "Error")}: #{hash.fetch("message", "Recovery-resolved failure")}",
+        code: hash["code"]
+      )
+      return error unless remaining.positive? && hash["cause"].is_a?(Hash) && hash["cause"].key?("class")
+
+      cause = from_diagnostic(hash["cause"], remaining: remaining - 1)
+      begin
+        raise error, cause: cause
+      rescue Phronomy::Error => restored
+        restored.set_backtrace(nil)
+        restored
+      end
+    end
+
+    def self.cause_diagnostic(error, remaining:, seen:)
+      return {"truncated" => true} if remaining.zero? || seen.include?(error.object_id)
+
+      # Bound newly added cause data; retain the existing top-level format.
+      fields = {"class" => error.class.name, "message" => error.message}
+      fields["code"] = error.code if error.is_a?(Phronomy::Error) && error.code
+      diagnostic = fields.to_h do |key, value|
+        [key, value.is_a?(String) ? value[0, 2048] : value]
+      end
+      # Never turn a truncated reason into a different, apparently valid code.
+      diagnostic.delete("code") if fields["code"] && fields["code"].length > 2048
+      diagnostic["truncated"] = true if diagnostic != fields
+      if error.cause
+        diagnostic["cause"] = cause_diagnostic(error.cause,
+          remaining: remaining - 1, seen: seen + [error.object_id])
+      end
+      diagnostic
+    end
+    private_class_method :cause_diagnostic
+  end
 end

data/lib/phronomy/content_store/base.rb

@@ -28,13 +28,18 @@ module Phronomy
       def fetch_text(content_id)
         value = fetch(content_id).force_encoding(Encoding::UTF_8)
         unless value.valid_encoding?
-          raise IntegrityError, "content is not UTF-8: #{content_id}"
+          raise IntegrityError.new("content is not UTF-8: #{content_id}", code: "content.invalid_encoding")
         end
         value
       end
 
       def fetch_json(content_id)
-        Phronomy::CanonicalJSON.load(fetch(content_id))
+        bytes = fetch(content_id)
+        begin
+          Phronomy::CanonicalJSON.load(bytes)
+        rescue JSON::ParserError => error
+          raise IntegrityError.new("content is not JSON: #{content_id}", code: "content.invalid_json"), cause: error
+        end
       end
 
       def fetch_many(content_ids)

data/lib/phronomy/context/assembly.rb

@@ -97,24 +97,17 @@ module Phronomy
       private
 
       def invoke_policy(policy, policy_input)
-        tracer = @tracer
-        span = tracer.start_span(
-          "context_policy",
-          agent_id: policy_input.agent_id,
-          execution_id: policy_input.execution_id,
-          call_sequence: policy_input.call_sequence,
-          policy_class: policy.class.name || policy.class.to_s,
-          instruction_count: policy_input.instruction.length,
-          knowledge_count: policy_input.knowledge.length,
-          tool_count: policy_input.tools.length,
-          conversation_group_count: policy_input.conversation.length
-        )
-        result = policy.call(policy_input)
-        tracer.finish_span(span)
-        result
-      rescue => error
-        tracer&.finish_span(span, error: error) if defined?(span) && span
-        raise
+        Phronomy::Tracing::Base.trace_with(
+          @tracer, "context_policy", record_output: false,
+          attributes: {agent_id: policy_input.agent_id,
+                       execution_id: policy_input.execution_id,
+                       call_sequence: policy_input.call_sequence,
+                       policy_class: policy.class.name || policy.class.to_s,
+                       instruction_count: policy_input.instruction.length,
+                       knowledge_count: policy_input.knowledge.length,
+                       tool_count: policy_input.tools.length,
+                       conversation_group_count: policy_input.conversation.length}
+        ) { [policy.call(policy_input), nil] }
       end
 
       def store_manifest(