phronomy 0.26.0 → 0.28.0

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

@@ -0,0 +1,323 @@
+# frozen_string_literal: true
+
+require_relative "../../execution/concurrency/worker_input_restricted"
+
+require "securerandom"
+require "time"
+
+module Phronomy
+  module Agent
+    # Admits and prepares an execution, or replays its saved preparation inputs.
+    # Runtime admission, live-state application and result delivery stay with
+    # the execution owner. Per-operation state is kept in local variables.
+    # @api private
+    class InitialPreparation
+      include Phronomy::Concurrency::WorkerInputRestricted
+
+      Command = Data.define(
+        :root, :journal_records, :input, :config, :preparation_replayable
+      )
+      RecoveryCommand = Data.define(:execution, :root, :journal_records)
+      Result = Data.define(
+        :execution, :root, :runtime_projection, :filtered_input,
+        :config, :appended_records, :error, :admission_outcome
+      )
+
+      # @api private
+      def initialize(agent:, persistence:)
+        @agent = agent
+        @persistence = persistence
+      end
+
+      # @api private
+      def prepare(operation)
+        begin
+          raw_message = @agent.send(:extract_message, operation.input)
+        rescue => error
+          return unadmitted_result(operation, error, :not_established)
+        end
+
+        begin
+          execution, active_root = admit_execution(
+            raw_message,
+            root: operation.root,
+            mode: (operation.config[:phronomy_recovery_mode] || :invoke).to_sym,
+            config: operation.config,
+            preparation_replayable: operation.preparation_replayable
+          )
+        rescue Phronomy::AgentBusyError => error
+          # A durable nonterminal execution keeps Runtime admission fail-closed
+          # until recovery can establish its lineage, including after F4 loss.
+          return unadmitted_result(operation, error, :recovery_required)
+        rescue Phronomy::Persistence::ConflictError,
+          Phronomy::Persistence::NotFoundError,
+          Phronomy::Persistence::SerializationError,
+          ArgumentError,
+          Phronomy::ConfigurationError => error
+          return unadmitted_result(operation, error, :not_established)
+        rescue => error
+          return unadmitted_result(operation, error, :outcome_unknown)
+        end
+
+        prepare_admitted(
+          input: operation.input,
+          config: operation.config,
+          execution: execution,
+          active_root: active_root,
+          journal_records: operation.journal_records
+        )
+      end
+
+      # @api private
+      def recover(operation)
+        execution = operation.execution
+        unless execution.metadata["preparation_replayable"] == true
+          raise Phronomy::ExecutionRehydrationRequiredError,
+            "execution #{execution.execution_id} has no replay-safe initial preparation contract"
+        end
+
+        input = @persistence.contents.fetch_text(execution.metadata.fetch("current_input_ref"))
+        config = recovered_config(execution)
+        prepare_admitted(
+          input: input,
+          config: config,
+          execution: execution,
+          active_root: operation.root,
+          journal_records: operation.journal_records
+        )
+      end
+
+      private
+
+      def unadmitted_result(operation, error, outcome)
+        Result.new(
+          execution: nil,
+          root: operation.root,
+          runtime_projection: nil,
+          filtered_input: nil,
+          config: operation.config,
+          appended_records: [].freeze,
+          error: error,
+          admission_outcome: outcome
+        )
+      end
+
+      def prepare_admitted(input:, config:, execution:, active_root:, journal_records:)
+        current_execution = execution
+        begin
+          filtered_input = filter_input(input, config)
+          staged = stage_filtered_input(current_execution, active_root, filtered_input)
+          assembler, prepared = prepare_context(staged, active_root, filtered_input, config, journal_records)
+          active_execution, manifest, manifest_ref = commit_preparation(
+            staged, active_root, assembler, prepared
+          )
+          # Advance the failure base only after the commit response is known.
+          # F1 response loss must not be reported as a confirmed terminal result.
+          current_execution = active_execution
+          projection = RuntimeInput.new(
+            agent: @agent, persistence: @persistence
+          ).materialize(manifest: manifest, manifest_ref: manifest_ref)
+          Result.new(
+            execution: active_execution,
+            root: active_root,
+            runtime_projection: projection,
+            filtered_input: filtered_input,
+            config: config,
+            appended_records: [].freeze,
+            error: nil,
+            admission_outcome: :active
+          )
+        rescue => error
+          preparation_failure_result(current_execution, active_root, config, error)
+        end
+      end
+
+      def filter_input(input, config)
+        @agent.send(:check_cancellation!, config, "invocation cancelled before input filtering")
+        filtered = @agent.send(:run_input_filters!, input)
+        @agent.send(:check_cancellation!, config, "invocation cancelled before context assembly")
+        filtered
+      end
+
+      def stage_filtered_input(execution, root, filtered_input)
+        message = @agent.send(:extract_message, filtered_input)
+        # Content-addressed source material may precede Policy. Mutable execution
+        # and Agent records are only advanced by the later commit transaction.
+        filtered_ref = @persistence.contents.put_text(message)
+        record = JournalRecord.new(
+          agent_id: @agent.agent_id,
+          execution_id: execution.execution_id,
+          kind: :external_message,
+          channel: :external,
+          role: :user,
+          content_ref: filtered_ref,
+          context_generation: root.transcript_generation,
+          context_candidate: true,
+          metadata: {"handoff_policy_category" => "current_request"}
+        )
+        execution.with(
+          execution_revision: execution.execution_revision,
+          working_records: execution.working_records + [record],
+          metadata: execution.metadata.merge(
+            "current_input_ref" => filtered_ref,
+            "current_input_record_id" => record.record_id
+          )
+        )
+      end
+
+      def prepare_context(staged, root, input, config, journal_records)
+        assembler = ContextPreparation.new(
+          agent: @agent, persistence: @persistence, journal_records: journal_records
+        )
+        prepared = assembler.prepare_initial(
+          input: input,
+          agent_root: root,
+          execution: staged,
+          config: config,
+          patch: @agent.send(:run_before_llm_input_hooks, call_sequence: 1, config: config)
+        )
+        @agent.send(:check_cancellation!, config, "invocation cancelled after context policy")
+        [assembler, prepared]
+      end
+
+      def commit_preparation(staged, root, assembler, prepared)
+        active = manifest = manifest_ref = nil
+        @persistence.transaction do |tx|
+          assert_local_durable_base!(tx, root)
+          manifest, manifest_ref = Phronomy::Context::Assembly.new.store(prepared, contents: tx.contents)
+          active = execution_with_initial_manifest(staged, manifest_ref)
+          tx.executions.save(
+            staged.execution_id,
+            expected_revision: staged.execution_revision,
+            execution: active
+          )
+        end
+        [active, manifest, manifest_ref]
+      end
+
+      def execution_with_initial_manifest(staged, manifest_ref)
+        staged.with(
+          status: :active,
+          phase: :calling_llm,
+          metadata: staged.metadata.merge(
+            "base_manifest_ref" => manifest_ref,
+            "manifest_ref" => manifest_ref,
+            "manifest_refs" => [manifest_ref]
+          )
+        )
+      end
+
+      def admit_execution(raw_message, root:, mode: :invoke, config: {}, preparation_replayable: false)
+        admission = Admission.new(persistence: @persistence, root: root,
+          input: raw_message, config: config,
+          preparation_metadata: initial_preparation_metadata(mode.to_sym, preparation_replayable))
+        participant = config[:phronomy_admission]
+        if admission.correlation && !participant
+          raise Phronomy::ConfigurationError, "Coordinated admission requires its current owner"
+        end
+        participant ? participant.admit(admission) : admission.accept
+        admission.result
+      end
+
+      def initial_preparation_metadata(mode, replayable)
+        {
+          "preparation_replayable" => !!replayable,
+          ExecutionMetadata::CONTRACT_VERSION_KEY => ExecutionMetadata::CONTRACT_VERSION,
+          ExecutionMetadata::INVOCATION_MODE_KEY => mode.to_s,
+          ExecutionMetadata::PENDING_LLM_ID_KEY => SecureRandom.uuid.to_s.freeze,
+          ExecutionMetadata::PENDING_LLM_STARTED_AT_KEY => Time.now.utc.iso8601(6).freeze
+        }
+      end
+
+      def recovered_config(execution)
+        mode = (execution.metadata[ExecutionMetadata::INVOCATION_MODE_KEY] || "invoke").to_sym
+        config = {phronomy_recovery_mode: mode}.merge(@agent.__execution_wiring)
+        if execution.metadata.key?("durable_context_ref")
+          context = @persistence.contents.fetch_json(execution.metadata.fetch("durable_context_ref"))
+          unless context.is_a?(Hash)
+            raise Phronomy::ExecutionRehydrationRequiredError,
+              "execution #{execution.execution_id} has a non-Hash durable_context"
+          end
+          Phronomy::Values::Immutable.validate_canonical_json!(context, label: "Recovered durable_context")
+          config[:durable_context] = Phronomy::Values::Immutable.copy(context)
+        end
+        config.freeze
+      end
+
+      def preparation_failure_result(execution, root, config, error)
+        failure = commit_preparation_failure(execution, root, error)
+        Result.new(
+          execution: failure.fetch(:execution),
+          root: failure.fetch(:root),
+          runtime_projection: nil,
+          filtered_input: nil,
+          config: config,
+          appended_records: failure.fetch(:appended_records),
+          error: failure.fetch(:error),
+          admission_outcome: :terminal
+        )
+      end
+
+      def commit_preparation_failure(execution, root, error)
+        translated_error = error
+        failed = next_root = appended = nil
+        @persistence.transaction do |tx|
+          error_ref = tx.contents.put_json(
+            "class" => translated_error.class.name,
+            "message" => translated_error.message
+          )
+          status = ExecutionFailure.status_for(translated_error)
+          records = preparation_failure_records(execution, root, status, error_ref)
+          appended = tx.journals.append(
+            root.agent_id, expected_position: root.journal_position, records: records
+          )
+          failed = execution.with(
+            status: status,
+            phase: status,
+            working_records: [],
+            error_ref: error_ref,
+            terminal_reason: translated_error.class.name
+          )
+          tx.executions.save(
+            execution.execution_id, expected_revision: execution.execution_revision, execution: failed
+          )
+          next_root = root.with(
+            agent_revision: root.agent_revision + 1,
+            journal_position: root.journal_position + appended.length,
+            lifecycle_status: :idle
+          )
+          tx.agents.save(root.agent_id, expected_revision: root.agent_revision, root: next_root)
+        end
+        {
+          error: translated_error,
+          execution: failed,
+          root: next_root,
+          appended_records: Array(appended).freeze
+        }.freeze
+      end
+
+      def preparation_failure_records(execution, root, status, error_ref)
+        records = execution.working_records.map do |record|
+          JournalRecord.from_h(record.to_h.merge("context_candidate" => false))
+        end
+        records << JournalRecord.new(
+          agent_id: @agent.agent_id,
+          execution_id: execution.execution_id,
+          kind: ExecutionFailure.journal_kind_for(status),
+          channel: :audit,
+          content_ref: error_ref,
+          context_generation: root.transcript_generation,
+          context_candidate: false
+        )
+      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

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

@@ -0,0 +1,368 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Agent-owned entry operations and external-result delivery.
+    # Session construction and resource selection are supplied by the environment.
+    # @api private
+    class InvocationActions
+      def self.build_entry_actions(agent, environment, mode:, event_sink:)
+        calling_action = if mode.to_sym == :stream
+          method(:calling_llm_stream_action).curry.call(agent, environment, event_sink)
+        else
+          method(:calling_llm_action).curry.call(agent, environment, event_sink)
+        end
+
+        {
+          filtering_input: [method(:apply_prepared_input_action).curry.call(agent)],
+          building_context: [method(:prepare_runtime_input_action).curry.call(agent)],
+          calling_llm: [calling_action],
+          starting_tools: [method(:starting_tools_action).curry.call(environment, event_sink)],
+          dispatching_tools: [method(:dispatching_tools_action).curry.call(environment, event_sink)],
+          recording_tool_results: [method(:recording_tool_results_action)],
+          suspended: [method(:suspended_action)],
+          output_filtering: [method(:output_filtering_action).curry.call(agent)],
+          failed: [method(:failed_action)]
+        }
+      end
+
+      def self.apply_prepared_input_action(_agent, invocation)
+        invocation.input = invocation.config.fetch(:phronomy_filtered_input)
+        invocation
+      end
+      private_class_method :apply_prepared_input_action
+
+      def self.prepare_runtime_input_action(agent, invocation)
+        projection = invocation.config.fetch(:phronomy_runtime_projection)
+        agent.send(:prepare_runtime_input, projection, invocation: invocation)
+      end
+      private_class_method :prepare_runtime_input_action
+
+      def self.calling_llm_action(agent, environment, event_sink, invocation)
+        prepare_and_start_llm_call(agent, environment, event_sink, invocation, streaming: false)
+        invocation
+      end
+      private_class_method :calling_llm_action
+
+      def self.calling_llm_stream_action(agent, environment, event_sink, invocation)
+        prepare_and_start_llm_call(agent, environment, event_sink, invocation, streaming: true)
+        invocation
+      end
+      private_class_method :calling_llm_stream_action
+
+      def self.prepare_and_start_llm_call(agent, environment, event_sink, invocation, streaming:)
+        # Callback failure is recorded synchronously on EventLoop before its
+        # explicit failure event is queued. Do not start a competing durable
+        # follow-up operation from the same execution revision while that failure
+        # event is waiting to terminalize the FSMSession.
+        return if invocation.callback_failed?
+
+        if invocation.user_message_sent
+          invocation.config.fetch(:phronomy_execution_coordinator).prepare_provider_dispatch(
+            invocation,
+            event_sink: event_sink,
+            streaming: streaming
+          )
+        else
+          start_provider_call(
+            agent,
+            environment,
+            event_sink,
+            invocation,
+            invocation.config.fetch(:phronomy_runtime_projection),
+            streaming: streaming,
+            replace_messages: false
+          )
+        end
+      rescue => error
+        post_setup_failure(event_sink, error)
+      end
+      private_class_method :prepare_and_start_llm_call
+
+      # Continues a follow-up Provider Call after its durable preparation result
+      # has been validated/applied by ExecutionCoordinator on EventLoop.
+      # @api private
+      def self.start_prepared_provider_call(
+        agent:,
+        environment:,
+        event_sink:,
+        invocation:,
+        projection:,
+        streaming:
+      )
+        start_provider_call(
+          agent,
+          environment,
+          event_sink,
+          invocation,
+          projection,
+          streaming: streaming,
+          replace_messages: true
+        )
+      end
+
+      def self.start_provider_call(
+        agent, environment, event_sink, invocation, projection,
+        streaming:, replace_messages:
+      )
+        call_context = trace_handle = nil
+        config = invocation.config
+        agent.send(:check_cancellation!, config, "invocation cancelled before LLM call")
+        if replace_messages
+          agent.send(:prepare_runtime_input, projection, invocation: invocation)
+          invocation.config[:phronomy_runtime_projection] = projection
+        end
+
+        request = agent.send(:build_llm_request, projection, invocation: invocation)
+        state = environment.registry.agent_execution_state(invocation.execution_id)
+        call_context = invocation.begin_llm_call!(projection,
+          llm_call_id: state&.execution&.metadata&.fetch(ExecutionMetadata::PENDING_LLM_ID_KEY, nil))
+        message = request.message
+        trace_handle = Phronomy::Tracing::Automatic.start(
+          "llm.call",
+          input: message,
+          agent_id: agent.agent_id,
+          execution_id: invocation.execution_id,
+          llm_call_id: call_context.fetch(:llm_call_id),
+          mode: invocation.mode,
+          streaming: streaming,
+          **agent.send(:_build_caller_meta, config)
+        )
+
+        client = environment.build_llm_client(adapter: Phronomy::Agent::Settings.current.llm_adapter)
+        token = config[:cancellation_token]
+        llm_call_id = call_context.fetch(:llm_call_id)
+        operation = if streaming
+          client.stream_async(
+            request, cancellation_token: config[:cancellation_token]
+          ) do |chunk|
+            token&.raise_if_cancelled!("invocation cancelled during streaming")
+            post_stream_chunk(
+              event_sink,
+              llm_call_id,
+              chunk.content
+            )
+          end
+        else
+          client.complete_async(
+            request, cancellation_token: config[:cancellation_token]
+          )
+        end
+        environment.registry.supervise_agent_operation(
+          invocation.execution_id,
+          operation
+        )
+        observe_manifest_call(
+          operation,
+          event_sink,
+          call_context,
+          trace_handle,
+          streaming: streaming
+        )
+      rescue => error
+        finish_provider_trace(trace_handle, nil, error)
+        if call_context
+          post_llm_result(
+            event_sink,
+            call_context,
+            nil,
+            error,
+            streaming: streaming
+          )
+        else
+          post_setup_failure(event_sink, error)
+        end
+      end
+      private_class_method :start_provider_call
+
+      def self.observe_manifest_call(
+        operation,
+        event_sink,
+        call_context,
+        trace_handle,
+        streaming:
+      )
+        operation.on_complete do |response, error|
+          finish_provider_trace(trace_handle, response, error)
+          post_llm_result(
+            event_sink,
+            call_context,
+            response,
+            error,
+            streaming: streaming
+          )
+        end
+      end
+      private_class_method :observe_manifest_call
+
+      def self.finish_provider_trace(trace_handle, response, error)
+        Phronomy::Tracing::Automatic.finish(trace_handle,
+          output: response, usage: response&.usage, error: error)
+      end
+      private_class_method :finish_provider_trace
+
+      def self.post_llm_result(event_sink, call_context, response, error, streaming:)
+        result = LLMOperationResult.new(
+          llm_call_id: call_context.fetch(:llm_call_id),
+          response: response,
+          error: error,
+          streaming: streaming
+        )
+        event_type = if error
+          :llm_failed
+        else
+          :llm_completed
+        end
+        post_session_event!(event_sink, event_type, result)
+      end
+      private_class_method :post_llm_result
+
+      def self.post_stream_chunk(event_sink, llm_call_id, content)
+        post_session_event!(
+          event_sink,
+          :llm_stream_chunk,
+          {llm_call_id: llm_call_id.to_s.freeze, content: content}.freeze
+        )
+      end
+      private_class_method :post_stream_chunk
+
+      def self.post_setup_failure(event_sink, error)
+        post_session_event!(event_sink, :llm_setup_failed, error)
+      end
+      private_class_method :post_setup_failure
+
+      def self.post_session_event!(event_sink, event_type, payload)
+        return if event_sink.post(event_type, payload)
+
+        Phronomy::RuntimeSettings.current.logger&.warn(
+          "[Phronomy] Dropped late #{event_type.inspect} for " \
+          "FSMSession #{event_sink.fsm_session_id}"
+        )
+      end
+      private_class_method :post_session_event!
+
+      def self.starting_tools_action(environment, parent_event_sink, invocation)
+        children = invocation.pending_tool_calls.map do |tool_call|
+          tool = invocation.tools[tool_call.name.to_sym]
+          tool_invocation_id =
+            ToolInvocation.semantic_id(
+              execution_id: invocation.execution_id,
+              llm_call_id: invocation.tool_batch_llm_call_id,
+              tool_call_id: (
+                tool_call.respond_to?(:id) ? tool_call.id : nil
+              ),
+              tool_name: tool_call.name
+            )
+
+          if tool
+            ToolInvocation.new(
+              execution_id: invocation.execution_id,
+              agent: invocation.agent,
+              tool: tool,
+              tool_call: tool_call,
+              config: invocation.config,
+              approval_policy: invocation.approval_policy,
+              approval_context: invocation.approval_context,
+              id: tool_invocation_id
+            )
+          else
+            ToolInvocation.missing(
+              execution_id: invocation.execution_id,
+              agent: invocation.agent,
+              tool_call: tool_call,
+              config: invocation.config,
+              id: tool_invocation_id
+            )
+          end
+        end
+        invocation.tool_invocations = children
+
+        children.reject(&:terminal?).each do |child|
+          session = environment.build_tool_session(invocation: child, parent_sink: parent_event_sink)
+          register_child_session(
+            environment,
+            child,
+            session,
+            parent_event_sink
+          )
+        end
+        invocation
+      end
+      private_class_method :starting_tools_action
+
+      def self.dispatching_tools_action(_environment, parent_event_sink, invocation)
+        invocation.config.fetch(:phronomy_execution_coordinator).prepare_tool_dispatch(
+          invocation,
+          event_sink: parent_event_sink
+        )
+        invocation
+      end
+      private_class_method :dispatching_tools_action
+
+      # Continues Tool physical dispatch after the operation-specific durable
+      # preparation has been confirmed and applied by ExecutionCoordinator.
+      # @api private
+      def self.start_prepared_tool_dispatch(
+        environment:,
+        event_sink:,
+        invocation:
+      )
+        invocation.tool_invocations.select(&:authorized?).each do |child|
+          session = environment.build_tool_session(
+            invocation: child,
+            parent_sink: event_sink,
+            resume_event: :dispatch,
+            resume_phase: :authorized
+          )
+          begin
+            register_child_session(environment, child, session, event_sink)
+          rescue => error
+            child.mark_framework_failed!(error)
+            event_sink.post(:tool_failed, {tool_invocation_id: child.id})
+          end
+        end
+        post_session_event!(event_sink, :tool_dispatch_prepared, nil)
+        invocation
+      end
+
+      def self.register_child_session(environment, child, session, parent_event_sink)
+        completion = Phronomy::TaskResult.deferred(name: "tool-session:#{child.id}")
+        completion.on_complete do |_result, error|
+          next unless error
+
+          # Tool FSMSession completion is settled by EventLoop, so this callback
+          # also executes on EventLoop and remains inside the single-writer domain.
+          child.mark_framework_failed!(error)
+          parent_event_sink.post(:tool_failed, {tool_invocation_id: child.id})
+        end
+        environment.register_session(session, completion: completion)
+      end
+      private_class_method :register_child_session
+
+      def self.recording_tool_results_action(invocation)
+        invocation.record_tool_results!
+      end
+      private_class_method :recording_tool_results_action
+
+      def self.suspended_action(invocation)
+        invocation.prepare_approval_request!
+      end
+      private_class_method :suspended_action
+
+      def self.failed_action(invocation)
+        raise(invocation.error || Phronomy::ToolError.new("Agent invocation failed"))
+      end
+      private_class_method :failed_action
+
+      def self.output_filtering_action(agent, invocation)
+        invocation.output = agent.send(:run_output_filters!, invocation.output)
+        invocation
+      rescue Phronomy::FilterBlockError => error
+        invocation.output_blocked = true
+        invocation.block_error = error
+        invocation
+      end
+      private_class_method :output_filtering_action
+    end
+  end
+end