phronomy 0.26.0 → 0.28.0

data/lib/phronomy/agent/{agent_execution.rb → execution/agent_execution.rb}

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
+require_relative "../../execution/concurrency/worker_input_restricted"
+
 require "securerandom"
 require "time"
 
 module Phronomy
   module Agent
     class AgentExecution
+      include Phronomy::Concurrency::WorkerInputRestricted
+
       ACTIVE_STATUSES = %i[preparing active suspended].freeze
       TERMINAL_STATUSES = %i[completed handed_off failed cancelled rejected blocked].freeze
       TRANSITIONS = {
@@ -55,13 +59,13 @@ module Phronomy
         ATTRIBUTES.each do |name|
           value = attributes.fetch(name)
           value = value.to_sym if %i[status phase].include?(name)
-          instance_variable_set("@#{name}", Immutable.copy(value))
+          instance_variable_set("@#{name}", Phronomy::Values::Immutable.copy(value))
         end
         raise ArgumentError, "unknown execution status: #{status.inspect}" unless TRANSITIONS.key?(status)
         raise ArgumentError, "execution_revision must be non-negative" if execution_revision.negative?
-        Immutable.validate_canonical_json!(metadata, label: "Execution metadata")
+        Phronomy::Values::Immutable.validate_canonical_json!(metadata, label: "Execution metadata")
         if approval_request
-          Immutable.validate_canonical_json!(approval_request, label: "Approval request")
+          Phronomy::Values::Immutable.validate_canonical_json!(approval_request, label: "Approval request")
         end
         freeze
       end
@@ -86,7 +90,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.
       # @api public
       def to_h
         ATTRIBUTES.to_h do |name|

data/lib/phronomy/agent/{agent_invocation.rb → execution/agent_invocation.rb}

@@ -1,22 +1,17 @@
 # frozen_string_literal: true
 
+require_relative "../../execution/concurrency/worker_input_restricted"
+
 require "securerandom"
 require "time"
 
 module Phronomy
   module Agent
     class AgentInvocation
+      include Phronomy::Concurrency::WorkerInputRestricted
+
       # execution_id is the logical Agent execution parent. Concrete Runtime
       # routing identity belongs only to the owning FSMSession incarnation.
-      TOOL_EVENT_TYPES = %i[
-        tool_authorized
-        tool_approval_required
-        tool_completed
-        tool_failed
-        tool_rejected
-        tool_cancelled
-      ].freeze
-
       LLM_EVENT_TYPES = %i[llm_completed llm_failed].freeze
       CALLBACK_FAILED_EVENTS = %i[application_callback_failed].freeze
       SETUP_FAILED_EVENTS = %i[llm_setup_failed tool_setup_failed].freeze
@@ -38,7 +33,8 @@ module Phronomy
       end
 
       attr_accessor :input,
-        :chat,
+        :messages,
+        :tools,
         :output,
         :usage,
         :input_blocked,
@@ -90,7 +86,8 @@ module Phronomy
         @event_sink = nil
         @mode = (mode || :invoke).to_sym
 
-        @chat = nil
+        @messages = []
+        @tools = {}.freeze
         @output = nil
         @usage = nil
         @input_blocked = false
@@ -144,17 +141,6 @@ module Phronomy
         end
 
         durable_id = llm_call_id
-        if durable_id.nil? &&
-            Phronomy::Runtime.instance.event_loop.current?
-          state =
-            Phronomy::Runtime.instance.event_loop.agent_execution_state(
-              execution_id
-            )
-          durable_id = state&.execution&.metadata&.fetch(
-            RecoverySupport::PENDING_LLM_ID_KEY,
-            nil
-          )
-        end
         unless durable_id
           raise Phronomy::ExecutionRehydrationRequiredError,
             "Provider Call semantic identity was not durably established before dispatch"
@@ -209,7 +195,7 @@ module Phronomy
           return true
         end
 
-        return false unless TOOL_EVENT_TYPES.include?(event.type)
+        return false unless InvocationTransitions::TOOL_EVENTS.include?(event.type)
 
         invocation = tool_invocation(event.payload&.fetch(:tool_invocation_id, nil))
         return true unless invocation
@@ -284,7 +270,7 @@ module Phronomy
 
         @user_message_sent = true
         @output = response.content
-        @usage = Phronomy::TokenUsage.from_tokens(response.tokens)
+        @usage = response.usage
         @pending_tool_calls = []
         self
       end
@@ -326,7 +312,7 @@ module Phronomy
       def record_tool_results!
         @tool_invocations.each do |invocation|
           tool_content = invocation.result.to_s
-          @chat.add_message(
+          @messages << Phronomy::LLMAdapter::Message.new(
             role: :tool,
             content: tool_content,
             tool_call_id: invocation.tool_call_id
@@ -435,7 +421,7 @@ module Phronomy
       private
 
       def handoff_matches_for(calls)
-        bindings = Array(@config[:phronomy_handoff_bindings])
+        bindings = Array(@config[:phronomy_control_bindings])
         return [] if bindings.empty?
 
         by_name = bindings.to_h { |binding| [binding.tool_name.to_s, binding] }
@@ -446,25 +432,15 @@ module Phronomy
       end
 
       def build_handoff_request(tool_call, binding, llm_call_id:)
-        handoff = binding.handoff
-        unless handoff.source_agent.equal?(@agent)
-          raise Phronomy::HandoffError,
-            "Handoff capability is not bound to the active Source Agent"
+        unless binding.source_agent_id == @agent.agent_id
+          raise Phronomy::HandoffError, "Control capability is not bound to the active Source Agent"
         end
-
-        args = tool_call.respond_to?(:arguments) ? tool_call.arguments : {}
-        args = (args || {}).to_h.transform_keys(&:to_sym)
-        selection = handoff.policy.selectable_categories.each_with_object({}) do |category, result|
-          key = :"include_#{category}"
-          result[category] = args[key] if args.key?(key)
+        request = binding.request(arguments: tool_call.arguments || {}, llm_call_id: llm_call_id,
+          tool_call_id: tool_call.respond_to?(:id) ? tool_call.id : nil)
+        unless request.is_a?(ControlRequest)
+          raise ArgumentError, "Control capability must return Agent::ControlRequest"
         end
-        Phronomy::Agent::HandoffRequest.new(
-          handoff: handoff,
-          responsibility: args.fetch(:responsibility),
-          selection_intent: selection,
-          llm_call_id: llm_call_id,
-          tool_call_id: tool_call.respond_to?(:id) ? tool_call.id : nil
-        )
+        request
       end
 
       def apply_llm_event(event)
@@ -481,7 +457,7 @@ module Phronomy
         call = @current_llm_call
         @llm_results << {
           llm_call_id: call.fetch(:llm_call_id),
-          response: canonical_response_for_llm_result(result),
+          response: result.response,
           error: result.error,
           streaming: result.streaming,
           manifest_ref: call.fetch(:manifest_ref),
@@ -495,16 +471,17 @@ module Phronomy
         end
 
         if result.error
-          if result.error.is_a?(ToolCallIntercepted)
-            accept_tool_calls!(
-              result.error.tool_calls,
-              llm_call_id: result.llm_call_id
-            )
+          @error = result.error
+        elsif result.response.is_a?(Phronomy::LLMAdapter::Response)
+          @messages << result.response
+          if result.response.tool_call?
+            @usage = result.response.usage
+            accept_tool_calls!(result.response.tool_calls, llm_call_id: result.llm_call_id)
           else
-            @error = result.error
+            apply_llm_response!(result.response)
           end
         else
-          apply_llm_response!(result.response)
+          @error = Phronomy::LLMAdapter::InvalidResultError.new("LLM operation completed without a Response")
         end
         true
       end
@@ -515,7 +492,7 @@ module Phronomy
       end
 
       def warn_stale_llm_result(llm_call_id)
-        Phronomy.configuration.logger&.warn(
+        Phronomy::RuntimeSettings.current.logger&.warn(
           "[Phronomy] Dropped stale Provider result: " \
           "execution_id=#{@execution_id} expected_llm_call_id=#{current_llm_call_id.inspect} " \
           "actual_llm_call_id=#{llm_call_id.inspect}"
@@ -524,14 +501,6 @@ module Phronomy
         nil
       end
 
-      def canonical_response_for_llm_result(result)
-        if result.error.is_a?(ToolCallIntercepted)
-          result.error.assistant_outcome || ProviderCallOutcome.capture(result.response)
-        else
-          ProviderCallOutcome.capture(result.response)
-        end
-      end
-
       # Canonical runtime recording is independent of Application callback health.
       # Once an event is observed it is appended even after a listener has failed.
       def deliver_event(event)
@@ -540,7 +509,7 @@ module Phronomy
         # listener receives the notification event separately.
         @runtime_events << StreamEvent.new(
           type: event.type,
-          payload: Immutable.copy(event.payload)
+          payload: Phronomy::Values::Immutable.copy(event.payload)
         )
         listener = @callback_failure ? nil : @event_listener
         return unless listener
@@ -560,13 +529,13 @@ module Phronomy
         if @event_sink
           accepted = @event_sink.post(:application_callback_failed, {failure: failure})
           unless accepted
-            Phronomy.configuration.logger&.warn(
+            Phronomy::RuntimeSettings.current.logger&.warn(
               "[Phronomy] Callback failure recorded but could not notify " \
               "FSMSession #{@event_sink.fsm_session_id}: execution_id=#{@execution_id}"
             )
           end
         end
-        Phronomy.configuration.logger&.warn(
+        Phronomy::RuntimeSettings.current.logger&.warn(
           "[Phronomy] Application event listener failed: " \
           "#{failure.error.class}: #{failure.error.message}"
         )

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative "../../execution/concurrency/worker_input_restricted"
+
+module Phronomy
+  module Agent
+    # Persists one approval decision with its captured recovery facts.
+    # Admission, live state and session resumption stay with the execution owner.
+    # @api private
+    class ApprovalResumeCommit
+      include Phronomy::Concurrency::WorkerInputRestricted
+
+      Command = Data.define(
+        :execution_id, :expected_execution_revision,
+        :root, :execution, :approval_request_id, :approved, :tool_batch_snapshot
+      )
+      Result = Data.define(:execution, :root)
+
+      # @api private
+      def initialize(agent_id:, persistence:)
+        @agent_id = agent_id
+        @persistence = persistence
+      end
+
+      # @api private
+      def commit(operation)
+        request = validated_approval_request(operation)
+        execution = stage_recovery_snapshot(operation)
+        persist_decision(execution, operation.root, request, operation.approved)
+      end
+
+      private
+
+      def validated_approval_request(operation)
+        request = operation.execution.approval_request || {}
+        request_id = request["id"] || request[:id]
+        unless request_id.to_s == operation.approval_request_id
+          raise ArgumentError,
+            "approval request does not match execution #{operation.execution.execution_id}"
+        end
+        request
+      end
+
+      def stage_recovery_snapshot(operation)
+        return operation.execution unless operation.tool_batch_snapshot
+
+        ExecutionMetadata.with_values(
+          operation.execution,
+          ExecutionMetadata::TOOL_BATCH_METADATA_KEY => operation.tool_batch_snapshot
+        )
+      end
+
+      def persist_decision(execution, root, request, approved)
+        updated = next_root = nil
+        @persistence.transaction do |tx|
+          decision = record_decision(tx, execution, root, request, approved)
+          updated = save_resumed_execution(tx, execution, request, approved, decision)
+          next_root = save_resumed_root(tx, root)
+        end
+        Result.new(execution: updated, root: next_root)
+      end
+
+      def record_decision(tx, execution, root, request, approved)
+        decision_ref = tx.contents.put_json(
+          "approval_request_id" => (request["id"] || request[:id]).to_s,
+          "approved" => approved
+        )
+        JournalRecord.new(
+          agent_id: @agent_id,
+          execution_id: execution.execution_id,
+          kind: :approval_decided,
+          channel: :approval,
+          content_ref: decision_ref,
+          context_generation: root.transcript_generation,
+          context_candidate: false
+        )
+      end
+
+      def save_resumed_execution(tx, current, request, approved, decision)
+        updated = current.with(
+          status: :active,
+          phase: :resuming,
+          working_records: current.working_records + [decision],
+          approval_request: request.merge("approved" => approved)
+        )
+        tx.executions.save(
+          current.execution_id,
+          expected_revision: current.execution_revision,
+          execution: updated
+        )
+        updated
+      end
+
+      def save_resumed_root(tx, current)
+        updated = current.with(
+          agent_revision: current.agent_revision + 1,
+          lifecycle_status: :active
+        )
+        tx.agents.save(
+          current.agent_id,
+          expected_revision: current.agent_revision,
+          root: updated
+        )
+        updated
+      end
+    end
+  end
+end

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

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require_relative "../../execution/concurrency/worker_input_restricted"
+
+module Phronomy
+  module Agent
+    # Commits the operation-specific prerequisites for Provider/Tool dispatch.
+    # The Agent supplies existing context/hook services, never live-state writes.
+    # Inputs and results belong to this worker boundary; delivery stays with the
+    # execution owner. No operation-local state is retained between calls.
+    # @api private
+    class DispatchPreparation
+      include Phronomy::Concurrency::WorkerInputRestricted
+
+      ProviderCommand = Data.define(
+        :execution_id, :fsm_session_id, :expected_execution_revision,
+        :root, :journal_records, :execution, :base_manifest,
+        :invocation_config, :runtime_snapshot, :streaming,
+        :pending_llm_call_id, :pending_llm_started_at
+      )
+      ToolCommand = Data.define(
+        :execution_id, :fsm_session_id, :expected_execution_revision,
+        :root, :execution, :runtime_snapshot, :tool_batch_snapshot, :invocation_config
+      )
+      ProviderResult = Data.define(:execution, :runtime_projection, :error)
+      ToolResult = Data.define(:execution)
+      # @api private
+      def initialize(agent:, persistence:)
+        @agent = agent
+        @persistence = persistence
+      end
+
+      # @api private
+      def prepare_provider(operation)
+        staged = stage_provider_call(operation)
+        recorded = encode_provider_records(operation, staged)
+        assembler, prepared = prepare_provider_context(operation, recorded)
+        committed, manifest, manifest_ref = commit_provider_preparation(
+          operation, recorded, assembler, prepared
+        )
+        materialize_provider_result(committed.execution, manifest, manifest_ref)
+      end
+
+      # @api private
+      def prepare_tools(operation)
+        updated = @persistence.transaction do |tx|
+          assert_local_durable_base!(tx, operation.root)
+          build_tool_dispatch_execution(operation, tx)
+        end
+        change = ExecutionChange.new(agent: @agent, current: operation.execution,
+          root: operation.root, kind: :dispatch, updated: updated, config: operation.invocation_config)
+        ToolResult.new(execution: change.perform)
+      end
+
+      private
+
+      def stage_provider_call(operation)
+        metadata = operation.execution.metadata.dup
+        metadata.delete(ExecutionMetadata::TOOL_BATCH_METADATA_KEY)
+        metadata.delete(ExecutionMetadata::RECOVERY_METADATA_KEY)
+        metadata[ExecutionMetadata::PENDING_LLM_ID_KEY] = operation.pending_llm_call_id
+        metadata[ExecutionMetadata::PENDING_LLM_STARTED_AT_KEY] = operation.pending_llm_started_at
+        metadata[ExecutionMetadata::CONTRACT_VERSION_KEY] = ExecutionMetadata::CONTRACT_VERSION
+        operation.execution.with(
+          execution_revision: operation.execution.execution_revision,
+          metadata: metadata
+        )
+      end
+
+      def encode_provider_records(operation, staged)
+        encoded_records = call_records = nil
+        # Content-addressed records may be added here; Execution is not advanced.
+        @persistence.transaction do |tx|
+          assert_local_durable_base!(tx, operation.root)
+          encoded_records, call_records = RuntimeRecordEncoder.encode(
+            staged,
+            agent_id: @agent.agent_id,
+            tx: tx,
+            snapshot: operation.runtime_snapshot,
+            context_candidate: true,
+            agent_root: operation.root
+          )
+        end
+        staged.with(
+          execution_revision: staged.execution_revision,
+          phase: :preparing_llm_call,
+          working_records: staged.working_records + encoded_records,
+          llm_calls: staged.llm_calls + call_records
+        )
+      end
+
+      def prepare_provider_context(operation, recorded)
+        patch = @agent.send(
+          :run_before_llm_input_hooks,
+          call_sequence: recorded.llm_calls.length + 1,
+          config: operation.invocation_config
+        )
+        assembler = ContextPreparation.new(
+          agent: @agent,
+          persistence: @persistence,
+          journal_records: operation.journal_records
+        )
+        prepared = assembler.prepare_followup(
+          base_manifest: operation.base_manifest,
+          agent_root: operation.root,
+          execution: recorded,
+          config: operation.invocation_config,
+          patch: patch
+        )
+        @agent.send(
+          :check_cancellation!,
+          operation.invocation_config,
+          "invocation cancelled after context policy"
+        )
+        [assembler, prepared]
+      end
+
+      def commit_provider_preparation(operation, recorded, assembler, prepared)
+        manifest, manifest_ref = @persistence.transaction do |tx|
+          assert_local_durable_base!(tx, operation.root)
+          Phronomy::Context::Assembly.new.store(prepared, contents: tx.contents)
+        end
+        updated = execution_with_provider_manifest(recorded, manifest_ref)
+        change = ExecutionChange.new(agent: @agent, current: operation.execution,
+          root: operation.root, kind: :dispatch, updated: updated, config: operation.invocation_config)
+        intended = ProviderResult.new(execution: change.perform, runtime_projection: nil, error: nil)
+        [intended, manifest, manifest_ref]
+      end
+
+      def execution_with_provider_manifest(recorded, manifest_ref)
+        refs = Array(recorded.metadata["manifest_refs"]) + [manifest_ref]
+        recorded.with(
+          phase: :calling_llm,
+          metadata: recorded.metadata.merge(
+            "manifest_ref" => manifest_ref,
+            "manifest_refs" => refs
+          )
+        )
+      end
+
+      def materialize_provider_result(execution, manifest, manifest_ref)
+        projection = materialization_error = nil
+        begin
+          projection = RuntimeInput.new(
+            agent: @agent, persistence: @persistence
+          ).materialize(manifest: manifest, manifest_ref: manifest_ref)
+        rescue => error
+          materialization_error = error
+        end
+        ProviderResult.new(
+          execution: execution, runtime_projection: projection,
+          error: materialization_error
+        )
+      end
+
+      def build_tool_dispatch_execution(operation, tx)
+        encoded_records, call_records = RuntimeRecordEncoder.encode(
+          operation.execution,
+          agent_id: @agent.agent_id,
+          tx: tx,
+          snapshot: operation.runtime_snapshot,
+          context_candidate: true,
+          agent_root: operation.root
+        )
+        operation.execution.with(
+          phase: :dispatching_tools,
+          working_records: operation.execution.working_records + encoded_records,
+          llm_calls: operation.execution.llm_calls + call_records,
+          metadata: tool_dispatch_metadata(operation)
+        )
+      end
+
+      def tool_dispatch_metadata(operation)
+        metadata = operation.execution.metadata.dup
+        metadata.delete(ExecutionMetadata::PENDING_LLM_ID_KEY)
+        metadata.delete(ExecutionMetadata::PENDING_LLM_STARTED_AT_KEY)
+        metadata.delete(ExecutionMetadata::RECOVERY_METADATA_KEY)
+        metadata.delete("framework_calls_pending")
+        metadata[ExecutionMetadata::TOOL_BATCH_METADATA_KEY] =
+          Phronomy::Values::Serializable.convert(operation.tool_batch_snapshot,
+            unsupported_message: "Recovery value is not canonically serializable")
+        metadata[ExecutionMetadata::CONTRACT_VERSION_KEY] = ExecutionMetadata::CONTRACT_VERSION
+        metadata
+      end
+
+      def assert_local_durable_base!(tx, root)
+        tx.assert_agent_watermark!(
+          agent_id: root.agent_id,
+          agent_revision: root.agent_revision,
+          journal_position: root.journal_position
+        )
+      end
+    end
+  end
+end