phronomy 0.26.0 → 0.28.0

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

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Agent phase vocabulary and ordered external transitions. Both the phase
+    # machine and FSMSession read this definition; Engine has no Agent policy.
+    # Automatic and external transition priority belongs to this Agent contract.
+    # @api private
+    module InvocationTransitions
+      ENTRY_POINT = :idle
+
+      AUTO_STATE_SET = {
+        idle: true,
+        filtering_input: true,
+        building_context: true,
+        starting_tools: true,
+        evaluating_tools: true,
+        recording_tool_results: true,
+        output_filtering: true
+      }.freeze
+
+      DECLARED_STATES = %i[
+        idle filtering_input building_context calling_llm starting_tools
+        evaluating_tools waiting_for_tools dispatching_tools
+        recording_tool_results suspended output_filtering handed_off completed blocked failed
+      ].freeze
+
+      WAIT_STATES = %i[suspended].freeze
+
+      TOOL_EVENTS = %i[
+        tool_authorized
+        tool_approval_required
+        tool_completed
+        tool_failed
+        tool_rejected
+        tool_cancelled
+      ].freeze
+
+      EXTERNAL_EVENTS = begin
+        tool_transitions = TOOL_EVENTS.to_h do |event_name|
+          [event_name, [{from: :waiting_for_tools, to: :evaluating_tools, guard: nil}]]
+        end
+
+        events = tool_transitions.merge(
+          llm_completed: [
+            {from: :calling_llm, to: :failed, guard: ->(ctx) { ctx.callback_failed? }},
+            {from: :calling_llm, to: :failed, guard: ->(ctx) { ctx.handoff_failed? }},
+            {from: :calling_llm, to: :handed_off, guard: ->(ctx) { ctx.handoff_requested? }},
+            {from: :calling_llm, to: :starting_tools, guard: ->(ctx) { ctx.tool_call_pending? }},
+            {from: :calling_llm, to: :output_filtering, guard: nil}
+          ],
+          llm_failed: [
+            {from: :calling_llm, to: :failed, guard: nil}
+          ],
+          llm_setup_failed: [
+            {from: :calling_llm, to: :failed, guard: nil}
+          ],
+          tool_setup_failed: [
+            {from: :dispatching_tools, to: :failed, guard: nil}
+          ],
+          tool_dispatch_prepared: [
+            {from: :dispatching_tools, to: :evaluating_tools, guard: nil}
+          ],
+          resume: [
+            {from: :suspended, to: :waiting_for_tools, guard: nil}
+          ],
+          application_callback_failed: [
+            {from: :filtering_input, to: :failed, guard: nil},
+            {from: :building_context, to: :failed, guard: nil},
+            {from: :calling_llm, to: :failed, guard: nil},
+            {from: :starting_tools, to: :failed, guard: nil},
+            {from: :evaluating_tools, to: :failed, guard: nil},
+            {from: :waiting_for_tools, to: :failed, guard: nil},
+            {from: :dispatching_tools, to: :failed, guard: nil},
+            {from: :recording_tool_results, to: :failed, guard: nil},
+            {from: :output_filtering, to: :failed, guard: nil}
+          ]
+        )
+        events.each_value do |transitions|
+          transitions.each(&:freeze).freeze
+        end
+        events.freeze
+      end
+
+      AUTOMATIC_EVENTS = {
+        state_completed: [
+          {from: :idle, to: :filtering_input, guard: nil},
+          {from: :filtering_input, to: :building_context, guard: ->(ctx) { ctx.input_passed? }},
+          {from: :filtering_input, to: :blocked, guard: ->(ctx) { ctx.input_blocked? }},
+          {from: :building_context, to: :calling_llm, guard: nil},
+          {from: :starting_tools, to: :evaluating_tools, guard: nil},
+          {from: :evaluating_tools, to: :failed, guard: ->(ctx) { ctx.tool_batch_failed? }},
+          {from: :evaluating_tools, to: :blocked, guard: ->(ctx) { ctx.tool_batch_rejected? }},
+          {from: :evaluating_tools, to: :recording_tool_results, guard: ->(ctx) { ctx.tool_batch_completed? }},
+          {from: :evaluating_tools, to: :suspended, guard: ->(ctx) { ctx.approval_required? }},
+          {from: :evaluating_tools, to: :dispatching_tools, guard: ->(ctx) { ctx.ready_to_dispatch? }},
+          {from: :evaluating_tools, to: :waiting_for_tools, guard: nil},
+          {from: :recording_tool_results, to: :calling_llm, guard: nil},
+          {from: :output_filtering, to: :completed, guard: ->(ctx) { ctx.output_passed? }},
+          {from: :output_filtering, to: :blocked, guard: ->(ctx) { ctx.output_blocked? }}
+        ].each(&:freeze).freeze
+      }.freeze
+
+      EVENTS = AUTOMATIC_EVENTS.merge(EXTERNAL_EVENTS).freeze
+
+      def self.next_phase(phase, event, context)
+        definition = EVENTS.fetch(event.to_sym, []).find do |candidate|
+          candidate[:from] == phase.to_sym &&
+            allowed?(candidate, context)
+        end
+        definition&.fetch(:to)
+      end
+
+      def self.allowed?(definition, context)
+        guard = definition[:guard]
+        !guard || !!(context && guard.call(context))
+      end
+
+      def self.recursion_limit(max_iterations)
+        12 + ((max_iterations || 10) * 8)
+      end
+    end
+  end
+end

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
+          tools_requested = outcome&.tool_call? || false
+          call_error = 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.to_h.values.any? { |value| !value.nil? }
+            tx.contents.put_json(json_value(outcome.usage.to_h))
+          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],
+              "tools_requested" => tools_requested,
+              "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(&:id),
+          "tool_names" => calls.map(&:name)
+        }
+      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/execution_change.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Limited synchronous participant SPI. Agent owns all record mutations,
+    # revision checks and outcome publication. A participant owns its own
+    # transaction and passes only an opaque extension and a transfer receipt.
+    # @api public
+    class ExecutionChange
+      attr_reader :kind, :agent_id, :execution_id, :extension, :operations,
+        :control_request, :cancel_requested, :recovery_required, :durable_context,
+        :correlation, :coordinator
+
+      # Agent execution constructs changes; applications implement participants.
+      # @api private
+      def initialize(agent:, current:, root:, kind:, updated: nil, terminal: nil, config: {}, &write)
+        @agent, @store, @current, @root = agent, agent.persistence, current, root
+        @coordinator = @store.coordinator
+        @kind, @updated, @write = kind, updated, write
+        @agent_id, @execution_id = current.agent_id, current.execution_id
+        @extension = current.metadata["execution_extension"] && ExecutionExtensionState.from_h(current.metadata["execution_extension"])
+        @correlation = Phronomy::Values::Immutable.copy(current.metadata["reservation"])
+        @control_request = terminal&.handoff
+        @cancel_requested = terminal&.cancel_requested || false
+        error = terminal && (terminal.callback_failure&.to_stream_callback_error || terminal.source_error || terminal.block_error || terminal.invocation_error)
+        @control_request = nil if error || terminal&.phase == :suspended
+        @recovery_required = error.is_a?(Phronomy::ExecutionRehydrationRequiredError)
+        @finishing = kind == :terminal && !@recovery_required && (error || terminal.phase != :suspended)
+        @operations = Array(updated&.metadata&.fetch(ExecutionMetadata::TOOL_BATCH_METADATA_KEY, nil)).filter_map do |entry|
+          next unless entry.fetch("status") == "authorized"
+          Store::AuthorizedOperation.new(invocation_id: entry.fetch("tool_invocation_id"), name: entry.fetch("tool_name"),
+            arguments: Phronomy::Values::Immutable.copy(entry.fetch("arguments").compact))
+        end.freeze
+        ref = current.metadata["durable_context_ref"]
+        @durable_context = ref && Phronomy::Values::Immutable.copy(@store.contents.fetch_json(ref))
+        @participant = config[:phronomy_execution_participant]
+        @thread = Thread.current
+        validate_binding!
+      end
+
+      def finishing? = !!@finishing
+
+      # Runs current wiring and proves the complete captured change after an
+      # ambiguous response. A savepoint never grants publication permission.
+      # @api private
+      def perform
+        raise Phronomy::ConfigurationError, "Execution change is single-use" if @performed
+        @performed = true
+        perform_once
+      end
+
+      # @api private
+      def perform_once
+        if @participant
+          @participant.commit(self)
+        else
+          coordinator.atomic { |scope|
+            prepare_in(scope)
+            commit_in(scope)
+          }
+        end
+        unless @scope&.committed? && @result
+          raise Phronomy::Persistence::TransactionError, "Execution change has not committed its outer scope"
+        end
+        @result
+      rescue => error
+        raise unless @after && @scope&.outermost?
+        outcome = Phronomy::Persistence::SaveOutcome.compare(before: @before, after: @after, original_error: error) do
+          coordinator.atomic do |scope|
+            @participant&.guard_change(self, scope)
+            @store.guard_agents(scope, agent_ids: [agent_id])
+            snapshot(scope)
+          end
+        end
+        return @result if outcome.disposition == :committed
+        raise error if outcome.disposition == :not_committed
+        raise Phronomy::ExecutionRehydrationRequiredError, "Execution change outcome is unknown: #{(outcome.read_error || error).message}"
+      end
+
+      private :perform_once
+
+      # Capture the complete pre-state after the participant has acquired its
+      # ordered guards, before it changes its own records.
+      def prepare_in(scope)
+        raise Phronomy::Persistence::TransactionError, "Execution change belongs to another thread" unless @thread.equal?(Thread.current)
+        raise Phronomy::ConfigurationError, "Execution change is single-use" if @scope
+        @store.guard_agents(scope, agent_ids: [agent_id])
+        @before = snapshot(scope)
+        @cancel_requested ||= @store.cancellation_requested?(agent_id: agent_id, execution_id: execution_id, scope: scope)
+        @scope = scope
+        nil
+      end
+
+      # Must be called once in the participant's original synchronous context.
+      # No arbitrary execution setter or callback is exposed to the participant.
+      def commit_in(scope, state: extension, transfer_receipt: nil, pending: false)
+        raise Phronomy::Persistence::TransactionError, "Execution change belongs to another thread" unless @thread.equal?(Thread.current)
+        raise Phronomy::ConfigurationError, "Execution change must use its prepared scope exactly once" unless @scope.equal?(scope) && !@used
+        @used = true
+        if state && (!extension || state.binding_key != extension.binding_key || state.binding_version != extension.binding_version)
+          raise Phronomy::ConfigurationError, "Execution extension identity cannot change"
+        end
+        raise ArgumentError, "dispatch cannot choose a terminal outcome" if kind == :dispatch && (transfer_receipt || pending)
+        raise ArgumentError, "only a control request can transfer responsibility" if transfer_receipt && !control_request
+        raise ArgumentError, "pending work requires cancellation or recovery" if pending && !(cancel_requested || recovery_required)
+        @store.participate(scope) do |records|
+          records.assert_agent_watermark!(agent_id: agent_id, agent_revision: @root.agent_revision, journal_position: @root.journal_position)
+          observed = records.executions.load(execution_id)
+          unless observed.agent_id == agent_id && observed.execution_revision == @current.execution_revision
+            raise Phronomy::Persistence::StateConflictError, "Execution changed before participation"
+          end
+          if kind == :dispatch
+            updated = attach_state(@updated, state)
+            records.executions.save(execution_id, expected_revision: @current.execution_revision, execution: updated)
+            @result = updated
+          else
+            @result = @write.call(records, state, transfer_receipt, pending)
+          end
+        end
+        @after = snapshot(scope)
+        nil
+      end
+
+      # Finalized input material; policies are interpreted by the participant.
+      def transfer_context(scope)
+        raise ArgumentError, "there is no control request" unless control_request
+        @store.participate(scope) do |records|
+          manifest = SavedContextReader.manifest_from_ref(@agent, @current.metadata.fetch("manifest_ref"))
+          TransferProjection.new.build(request: control_request, manifest: manifest, persistence: records, source_agent: @agent)
+        end
+      end
+
+      private
+
+      def validate_binding!
+        return unless extension
+        binding = @participant&.binding
+        unless binding && binding.binding_key == extension.binding_key && binding.binding_version == extension.binding_version
+          raise Phronomy::ExecutionRehydrationRequiredError, "Execution #{execution_id} needs participant #{extension.binding_key}@#{extension.binding_version}"
+        end
+      end
+
+      def attach_state(execution, state)
+        execution.with(execution_revision: execution.execution_revision,
+          metadata: execution.metadata.merge("execution_extension" => state&.to_h).compact)
+      end
+
+      def snapshot(scope)
+        agent_state = @store.participate(scope) do |records|
+          root = records.agents.load(agent_id)
+          execution = records.executions.load(execution_id)
+          journal = records.journals.read(agent_id, after: @root.journal_position,
+            limit: [root.journal_position - @root.journal_position, 1].max)
+          ref = execution.metadata.dig("execution_extension", "state_ref")
+          [root.to_h, execution.to_h, journal.map(&:to_h), ref && records.contents.fetch_json(ref), records.cancellations.requested?(agent_id, execution_id)]
+        end
+        [agent_state, @participant&.change_evidence(self, scope)]
+      end
+    end
+  end
+end

data/lib/phronomy/agent/execution_environment.rb

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

data/lib/phronomy/agent/execution_extension_state.rb

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

data/lib/phronomy/agent/execution_observation.rb

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