phronomy 0.25.0 → 0.27.0

data/lib/phronomy/agent/execution/runtime_record_encoder.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Encodes execution facts using the caller's existing content transaction.
+    # It neither opens a transaction nor changes durable or live execution state.
+    # @api private
+    module RuntimeRecordEncoder
+      module_function
+
+      def encode(
+        execution,
+        agent_id:,
+        tx:,
+        snapshot:,
+        context_candidate:,
+        agent_root:
+      )
+        root = agent_root
+        records = []
+        calls = []
+
+        snapshot.fetch(:llm_results).each_with_index do |item, index|
+          outcome = item[:response]
+          error = item[:error]
+          llm_call_id = item.fetch(:llm_call_id).to_s
+          intercepted = error.is_a?(ToolCallIntercepted)
+          call_error = intercepted ? nil : error
+          output_ref = assistant_output_ref(tx, outcome)
+          assistant_ref = assistant_message_ref(tx, outcome)
+          error_ref = if call_error
+            tx.contents.put_json(
+              "class" => call_error.class.name,
+              "message" => call_error.message
+            )
+          end
+          usage_ref = if outcome && !outcome.usage.empty?
+            tx.contents.put_json(json_value(outcome.usage))
+          end
+          call = LLMCallRecord.new(
+            llm_call_id: llm_call_id,
+            execution_id: execution.execution_id,
+            sequence: execution.llm_calls.length + index + 1,
+            status: call_error ? :failed : :completed,
+            manifest_ref: item.fetch(:manifest_ref),
+            output_ref: output_ref,
+            error_ref: error_ref,
+            usage_ref: usage_ref,
+            started_at: item.fetch(:started_at),
+            completed_at: Time.now.utc.iso8601(6),
+            metadata: {
+              "streaming" => item[:streaming],
+              "tool_call_intercepted" => intercepted,
+              "assistant_outcome_captured" => !outcome.nil?,
+              "tool_call_count" => outcome ? outcome.tool_calls.length : 0
+            }
+          )
+          calls << call
+          call_ref = tx.contents.put_json(call.to_h)
+          records << JournalRecord.new(
+            agent_id: agent_id,
+            execution_id: execution.execution_id,
+            llm_call_id: llm_call_id,
+            kind: :llm_call_recorded,
+            channel: :audit,
+            content_ref: call_ref,
+            context_generation: root.transcript_generation,
+            context_candidate: false
+          )
+
+          if assistant_ref
+            records << JournalRecord.new(
+              agent_id: agent_id,
+              execution_id: execution.execution_id,
+              llm_call_id: llm_call_id,
+              kind: :assistant_message,
+              channel: :llm,
+              role: :assistant,
+              content_ref: assistant_ref,
+              context_generation: root.transcript_generation,
+              context_candidate: context_candidate,
+              metadata: assistant_message_metadata(outcome)
+            )
+          end
+        end
+
+        if (active = snapshot[:active_call])
+          abandoned = LLMCallRecord.new(
+            llm_call_id: active.fetch(:llm_call_id),
+            execution_id: execution.execution_id,
+            sequence: execution.llm_calls.length + calls.length + 1,
+            status: :cancelled,
+            manifest_ref: active.fetch(:manifest_ref),
+            started_at: active.fetch(:started_at),
+            completed_at: Time.now.utc.iso8601(6),
+            metadata: {
+              "reason" => "execution_terminalized_before_provider_settlement"
+            }
+          )
+          calls << abandoned
+          records << JournalRecord.new(
+            agent_id: agent_id,
+            execution_id: execution.execution_id,
+            llm_call_id: abandoned.llm_call_id,
+            kind: :llm_call_recorded,
+            channel: :audit,
+            content_ref: tx.contents.put_json(abandoned.to_h),
+            context_generation: root.transcript_generation,
+            context_candidate: false
+          )
+        end
+
+        snapshot.fetch(:runtime_events).each do |event|
+          case event.type
+          when :tool_call
+            next
+          when :tool_result
+            payload = event.payload
+            llm_call_id = payload[:llm_call_id] || payload["llm_call_id"]
+            tool_call_id = payload.fetch(:tool_call_id).to_s
+            tool_name = payload.fetch(:tool_name).to_s
+            next if execution.working_records.any? do |record|
+              record.kind == :tool_message && record.causation_id.to_s == tool_call_id && record.llm_call_id.to_s == llm_call_id.to_s
+            end
+            result_ref = put_runtime_content(tx, payload.fetch(:tool_result))
+            records << JournalRecord.new(
+              agent_id: agent_id,
+              execution_id: execution.execution_id,
+              llm_call_id: llm_call_id,
+              kind: :tool_result,
+              channel: :tool,
+              content_ref: result_ref,
+              causation_id: tool_call_id,
+              context_generation: root.transcript_generation,
+              context_candidate: false,
+              metadata: {
+                "tool_call_id" => tool_call_id,
+                "tool_name" => tool_name
+              }
+            )
+
+            message_payload = if payload.key?(:tool_message)
+              payload.fetch(:tool_message)
+            else
+              payload.fetch("tool_message")
+            end
+            records << JournalRecord.new(
+              agent_id: agent_id,
+              execution_id: execution.execution_id,
+              llm_call_id: llm_call_id,
+              kind: :tool_message,
+              channel: :tool,
+              role: :tool,
+              content_ref: tx.contents.put_json(json_value(message_payload)),
+              causation_id: tool_call_id,
+              context_generation: root.transcript_generation,
+              context_candidate: context_candidate,
+              metadata: {
+                "tool_call_id" => tool_call_id,
+                "tool_name" => tool_name
+              }
+            )
+          end
+        end
+        [records, calls]
+      end
+
+      def assistant_message_ref(tx, outcome)
+        return unless outcome
+
+        payload = {
+          "role" => "assistant",
+          "content" => json_value(outcome.content),
+          "tool_calls" => json_value(Array(outcome.tool_calls)),
+          "model_id" => outcome.metadata["model_id"]
+        }.compact
+        tx.contents.put_json(payload)
+      end
+
+      def assistant_message_metadata(outcome)
+        calls = Array(outcome&.tool_calls)
+        {
+          "tool_call_ids" => calls.map { |call| call.fetch("id").to_s },
+          "tool_names" => calls.map { |call| call.fetch("name").to_s }
+        }
+      end
+
+      def assistant_output_ref(tx, outcome)
+        return unless outcome&.content_present?
+
+        content = outcome.content
+        text = content.is_a?(String) ? content : Phronomy::CanonicalJSON.dump(content)
+        tx.contents.put_text(text)
+      end
+
+      def put_runtime_content(tx, value)
+        value.is_a?(String) ?
+          tx.contents.put_text(value) : tx.contents.put_json(json_value(value))
+      end
+
+      def json_value(value)
+        Phronomy::Values::Serializable.convert(value,
+          unsupported_message: "unsupported canonical runtime value")
+      end
+
+      private_class_method :assistant_message_ref, :assistant_message_metadata,
+        :assistant_output_ref
+    end
+  end
+end

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

@@ -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

data/lib/phronomy/agent/handoff/handoff_execution_coordinator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Selects Handoff persistence; execution ownership and delivery remain in
+    # ExecutionCoordinator. This is not a public subclass extension contract.
+    class HandoffExecutionCoordinator < Phronomy::Agent::ExecutionCoordinator
+      private
+
+      def build_outcome_committer
+        HandoffOutcomeCommitter.new(agent: @agent, persistence: @agent.persistence)
+      end
+    end
+  end
+end

data/lib/phronomy/agent/handoff/handoff_outcome_committer.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Phronomy
+  module Agent
+    # Adds atomic Source transfer while sharing ordinary result persistence.
+    # Outcome selection deliberately retains Handoff-specific precedence.
+    # @api private
+    class HandoffOutcomeCommitter < ExecutionOutcomeCommitter
+      # @api private
+      def commit_outcome(operation)
+        view = operation.terminal_view
+        if view.callback_failure
+          return commit_failed_outcome(
+            operation,
+            view.callback_failure.to_stream_callback_error
+          )
+        end
+        error = view.source_error || view.block_error || view.invocation_error
+        raise error if error.is_a?(Phronomy::ExecutionRehydrationRequiredError)
+        return commit_failed_outcome(operation, error) if error
+        return commit_suspended(operation) if view.phase == :suspended
+
+        raise view.block_error if view.input_blocked || view.output_blocked
+        raise view.invocation_error if view.invocation_error
+
+        return commit_handed_off(operation) if view.handoff
+
+        commit_completed(operation)
+      rescue => caught
+        reconcile_terminal_error(operation, caught)
+      end
+
+      private
+
+      def commit_handed_off(operation)
+        handed_off = next_root = appended = nil
+        @persistence.transaction do |tx|
+          routing = validated_source_routing(tx, operation.execution)
+          context_ref = persist_handoff_context(tx, operation)
+          target_id = transfer_routing(tx, operation, routing, context_ref)
+          records, handed_off = encode_handoff(tx, operation, target_id, context_ref)
+          appended = append_journal(tx, operation.root, records)
+          save_execution(tx, operation.execution, handed_off)
+          next_root = save_terminal_root(tx, operation.root, appended)
+        end
+        Outcome.new(type: :handed_off, execution: handed_off, root: next_root,
+          appended_records: Array(appended).freeze,
+          result: result_base(handed_off, next_root).freeze,
+          error: nil, approval_request: nil)
+      end
+
+      def validated_source_routing(tx, current)
+        coordination = current.metadata.fetch("coordination")
+        routing = tx.handoff_states.load(coordination.fetch("main_agent_id"))
+        unless routing && routing.active_agent_id == @agent.agent_id && routing.handoff_revision == coordination.fetch("handoff_revision")
+          raise Phronomy::Storage::ConflictError, "Handoff routing changed before Source transfer"
+        end
+        if Array(routing.metadata["cancelled_execution_ids"]).include?(current.execution_id)
+          raise Phronomy::CancellationError, "Handoff Source turn was cancelled"
+        end
+        routing
+      end
+
+      def persist_handoff_context(tx, operation)
+        manifest = SavedContextReader.manifest_from_ref(@agent, operation.execution.metadata.fetch("manifest_ref"))
+        context = HandoffProjection.new.build_terminal(view: operation.terminal_view.handoff,
+          manifest: manifest, persistence: tx, source_agent_id: @agent.agent_id)
+        tx.contents.put_json(context.to_h)
+      end
+
+      def transfer_routing(tx, operation, routing, context_ref)
+        request = operation.terminal_view.handoff
+        target_id = "handoff-target-#{Digest::SHA256.hexdigest([operation.execution.execution_id, request.target_agent_id].join("\0"))}"
+        target_root = tx.agents.load(request.target_agent_id)
+        target_definition = {"id" => target_root.agent_definition_id, "version" => target_root.agent_definition_version}
+        transfer = routing.with(active_agent_id: request.target_agent_id,
+          active_handoff_context_ref: context_ref, phase: "target_pending",
+          pending_source_execution_id: operation.execution.execution_id, pending_target_execution_id: target_id,
+          metadata: routing.metadata.merge("target_definition" => target_definition))
+        tx.handoff_states.save(routing.main_agent_id, expected_revision: routing.handoff_revision, state: transfer)
+        target_id
+      end
+
+      def encode_handoff(tx, operation, target_id, context_ref)
+        current = operation.execution
+        request = operation.terminal_view.handoff
+        encoded_records, call_records = encode_runtime_records(tx, operation, context_candidate: false)
+        audit_record = encode_handoff_audit(tx, operation)
+        records = current.working_records + encoded_records + [audit_record]
+        handed_off = current.with(
+          status: :handed_off,
+          phase: :handed_off,
+          working_records: [],
+          llm_calls: current.llm_calls + call_records,
+          approval_request: nil,
+          terminal_reason: "handed_off",
+          metadata: current.metadata.merge("handoff_target_agent_id" => request.target_agent_id,
+            "handoff_target_execution_id" => target_id, "handoff_context_ref" => context_ref)
+        )
+        [records, handed_off]
+      end
+
+      def encode_handoff_audit(tx, operation)
+        request = operation.terminal_view.handoff
+        audit_ref = tx.contents.put_json(
+          "target_agent_id" => request.target_agent_id,
+          "responsibility" => request.responsibility,
+          "selection_intent" => request.selection_intent.to_h do |category, included|
+            [category.to_s, included]
+          end
+        )
+        JournalRecord.new(
+          agent_id: @agent.agent_id,
+          execution_id: operation.execution.execution_id,
+          llm_call_id: request.llm_call_id,
+          kind: :execution_handed_off,
+          channel: :audit,
+          content_ref: audit_ref,
+          context_generation: operation.root.transcript_generation,
+          context_candidate: false,
+          metadata: {
+            "target_agent_id" => request.target_agent_id,
+            "handoff_tool_call_id" => request.tool_call_id
+          }.compact
+        )
+      end
+    end
+  end
+end

data/lib/phronomy/agent/{handoff_state.rb → handoff/handoff_state.rb}

@@ -14,7 +14,7 @@ module Phronomy
         source = values.transform_keys(&:to_s)
         raise ArgumentError, "HandoffState schema mismatch" unless source.keys.sort == ATTRIBUTES.sort
         canonical = Phronomy::CanonicalJSON.load(Phronomy::CanonicalJSON.dump(source))
-        ATTRIBUTES.each { |key| instance_variable_set("@#{key}", Phronomy::Agent::Immutable.copy(canonical.fetch(key))) }
+        ATTRIBUTES.each { |key| instance_variable_set("@#{key}", Phronomy::Values::Immutable.copy(canonical.fetch(key))) }
         raise ArgumentError, "missing main_agent_id" if main_agent_id.to_s.empty?
         raise ArgumentError, "invalid handoff_revision" unless handoff_revision.is_a?(Integer) && handoff_revision >= 0
         raise ArgumentError, "invalid metadata" unless metadata.is_a?(Hash)

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

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
+require_relative "../../engine/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/{agent_root.rb → lifecycle/agent_root.rb}

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
+require_relative "../../engine/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,13 +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.for(runtime)
+        existing_for(runtime) || runtime.__register_shutdown_participant(
+          key: self, participant: new(runtime: runtime)
+        )
+      end
+
+      def self.existing_for(runtime)
+        runtime.__shutdown_participant(key: self)
+      end
+
       Entry = Data.define(:state, :agent, :token)
       private_constant :Entry
 
@@ -26,9 +40,9 @@ module Phronomy
         begin
           agent = yield(@runtime)
         rescue Phronomy::AgentAlreadyExistsError,
-          Phronomy::Persistence::ConflictError,
-          Phronomy::Persistence::NotFoundError,
-          Phronomy::Persistence::SerializationError,
+          Phronomy::Storage::ConflictError,
+          Phronomy::Storage::NotFoundError,
+          Phronomy::Storage::SerializationError,
           ArgumentError,
           Phronomy::ConfigurationError
           release_construction!(key, token)
@@ -156,10 +170,10 @@ module Phronomy
         @mutex.synchronize do
           entry = @entries[key]
           validate_purge_entry!(entry, agent, token, key)
+          agent.send(:__mark_purged!, @runtime)
           @entries.delete(key)
           @condition.broadcast
         end
-        agent.send(:__mark_purged!, @runtime)
         true
       end
 
@@ -169,10 +183,10 @@ module Phronomy
         @mutex.synchronize do
           entry = @entries[key]
           validate_purge_entry!(entry, agent, token, key)
+          agent.send(:__restore_live_after_purge_abort!, @runtime)
           @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 +197,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!, @runtime)
           @entries[key] = Entry.new(
             state: :recovery_required,
             agent: agent,
@@ -190,7 +205,6 @@ module Phronomy
           )
           @condition.broadcast
         end
-        agent.send(:__mark_ownership_recovery_required!, @runtime)
         true
       end
 
@@ -204,7 +218,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 +231,7 @@ module Phronomy
         end
       end
 
-      def shutdown!
+      def after_runtime_shutdown
         agents = @mutex.synchronize do
           @state = :terminated
           owned = @entries.values.filter_map(&:agent).uniq

data/lib/phronomy/{agent_already_exists_error.rb → agent/lifecycle_contract/agent_already_exists_error.rb}

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

data/lib/phronomy/{agent_busy_error.rb → agent/lifecycle_contract/agent_busy_error.rb}

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

data/lib/phronomy/{agent_purged_error.rb → agent/lifecycle_contract/agent_purged_error.rb}

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

data/lib/phronomy/agent/lifecycle_contract/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/{stream_callback_error.rb → agent/lifecycle_contract/stream_callback_error.rb}

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../../common/error"
+
 module Phronomy
   # Raised when an Application stream callback fails and
   # +stream_callback_error_policy+ is +:fail_task+.