phronomy 0.22.0 → 0.24.0

data/lib/phronomy/agent/agent_root.rb

@@ -8,19 +8,19 @@ module Phronomy
       LIFECYCLE_STATUSES = %i[idle active suspended closed invalidated].freeze
 
       ATTRIBUTES = %i[
-        agent_id agent_definition_id definition_version agent_revision
+        agent_id agent_definition_id agent_definition_version agent_revision
         context_revision journal_position lifecycle_status transcript_generation
         created_at updated_at metadata
       ].freeze
 
       attr_reader(*ATTRIBUTES)
 
-      def self.create(agent_id:, agent_definition_id:, definition_version:, metadata: {})
+      def self.create(agent_id:, agent_definition_id:, agent_definition_version:, metadata: {})
         now = Time.now.utc.iso8601(6)
         new(
           agent_id: agent_id,
           agent_definition_id: agent_definition_id,
-          definition_version: definition_version,
+          agent_definition_version: agent_definition_version,
           agent_revision: 0,
           context_revision: 0,
           journal_position: 0,

data/lib/phronomy/agent/approval_evaluation_request.rb

@@ -2,17 +2,25 @@
 
 module Phronomy
   module Agent
-    # Immutable input passed to Tool approval policy callables.
+    # Value-oriented input passed to Tool approval policy callables.
     #
     # This object intentionally contains the internal, validated arguments used
-    # for policy evaluation. It must not be exposed directly to Application UI.
+    # for policy evaluation. It carries Agent identity metadata and Tool
+    # description data only; it never exposes live Agent or Tool objects.
+    #
+    # Hash, Array, and String values are recursively copied/frozen. Other
+    # application-owned opaque values remain application-owned; complete
+    # value-type enforcement for those objects is outside ACS-11.
+    #
+    # This object must not be exposed directly to Application UI.
     # Use {ToolApprovalRequest} for notifications.
     #
     # @api public
     class ApprovalEvaluationRequest
-      attr_reader :agent,
-        :agent_invocation_id,
-        :tool,
+      attr_reader :agent_id,
+        :agent_definition_id,
+        :agent_definition_version,
+        :execution_id,
         :tool_name,
         :tool_schema,
         :tool_invocation_id,
@@ -27,9 +35,10 @@ module Phronomy
       VALID_DECISIONS = %i[allow require_approval reject].freeze
 
       def initialize(
-        agent:,
-        agent_invocation_id:,
-        tool:,
+        agent_id:,
+        agent_definition_id:,
+        agent_definition_version:,
+        execution_id:,
         tool_name:,
         tool_schema:,
         tool_invocation_id:,
@@ -41,9 +50,21 @@ module Phronomy
         metadata: {},
         default_decision: nil
       )
-        @agent = agent
-        @agent_invocation_id = agent_invocation_id
-        @tool = tool
+        if agent_id.nil? || agent_id.to_s.empty?
+          raise ArgumentError, "ApprovalEvaluationRequest requires agent_id"
+        end
+        if agent_definition_id.nil? || agent_definition_id.to_s.empty?
+          raise ArgumentError,
+            "ApprovalEvaluationRequest requires agent_definition_id"
+        end
+        if execution_id.nil? || execution_id.to_s.empty?
+          raise ArgumentError, "ApprovalEvaluationRequest requires execution_id"
+        end
+
+        @agent_id = agent_id.to_s.freeze
+        @agent_definition_id = agent_definition_id.to_s.freeze
+        @agent_definition_version = Integer(agent_definition_version)
+        @execution_id = execution_id.to_s.freeze
         @tool_name = tool_name.to_s.freeze
         @tool_schema = immutable_copy(tool_schema)
         @tool_invocation_id = tool_invocation_id.to_s.freeze
@@ -61,9 +82,10 @@ module Phronomy
       # @api private
       def with(facts: @facts, default_decision: @default_decision)
         self.class.new(
-          agent: @agent,
-          agent_invocation_id: @agent_invocation_id,
-          tool: @tool,
+          agent_id: @agent_id,
+          agent_definition_id: @agent_definition_id,
+          agent_definition_version: @agent_definition_version,
+          execution_id: @execution_id,
           tool_name: @tool_name,
           tool_schema: @tool_schema,
           tool_invocation_id: @tool_invocation_id,
@@ -90,11 +112,7 @@ module Phronomy
         when String
           value.dup.freeze
         else
-          begin
-            value.frozen? ? value : value.dup.freeze
-          rescue TypeError
-            value
-          end
+          value
         end
       end
     end

data/lib/phronomy/agent/async_event_api.rb

@@ -2,108 +2,85 @@
 
 module Phronomy
   module Agent
-    # Public Agent execution API. Agent instances are always stateful and all
-    # operations are coordinated through Phronomy::Persistence.
+    # Public Agent execution facade.
+    #
+    # CG-09 clean break:
+    # - application event listeners are bound to the live Agent incarnation at
+    #   new/create/load time;
+    # - invoke/invoke_async/stream/stream_async do not accept per-call event
+    #   listeners or listener blocks;
+    # - approval notifications share the Agent listener as :approval_required;
+    # - Recovery resolution uses resolve/resolve_async.
     module AsyncEventApi
       def invoke(
         input,
-        thread_id: nil,
         config: {},
         invocation_context: nil,
-        on_event: nil,
-        &block
+        **removed_options,
+        &removed_block
       )
-        listener = resolve_event_listener(on_event, block)
-        if invocation_context
-          thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
-        end
+        _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
+        config = _prepare_invocation_config(config, invocation_context)
         _check_event_loop_reentrancy(:invoke, :invoke_async)
-        trace("agent.invoke", input: input, **_build_caller_meta(config)) do |_span|
-          result = invoke_async(
-            input,
-            thread_id: thread_id,
-            config: config,
-            on_event: listener
-          ).wait_result
-          [result, result[:usage]]
-        end
+        _start_agent_operation(
+          input,
+          config: config,
+          mode: :invoke,
+          listener: _phronomy_event_listener
+        ).wait_result
       end
 
       def invoke_async(
         input,
-        thread_id: nil,
         config: {},
         invocation_context: nil,
-        on_tool_approval_required: nil,
-        on_event: nil,
-        &block
+        **removed_options,
+        &removed_block
       )
-        listener = resolve_event_listener(on_event, block)
-        if invocation_context
-          thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
-        end
-        approval = _approval_configuration_snapshot(on_tool_approval_required)
-        execution_coordinator.start(
+        _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
+        config = _prepare_invocation_config(config, invocation_context)
+        _start_agent_operation(
           input,
-          thread_id: thread_id,
           config: config,
           mode: :invoke,
-          approval_policy: approval[:policy],
-          approval_listener: approval[:listener],
-          on_event: listener
+          listener: _phronomy_event_listener
         )
       end
 
       def stream(
         input,
-        thread_id: nil,
         config: {},
         invocation_context: nil,
-        on_tool_approval_required: nil,
-        on_event: nil,
-        &block
+        **removed_options,
+        &removed_block
       )
-        listener = resolve_event_listener(on_event, block)
-        raise ArgumentError, "stream requires on_event: or a block" unless listener
-        if invocation_context
-          thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
-        end
+        _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
+        listener = _required_stream_listener!(:stream)
+        config = _prepare_invocation_config(config, invocation_context)
         _check_event_loop_reentrancy(:stream, :stream_async)
-        trace("agent.stream", input: input, **_build_caller_meta(config)) do |_span|
-          result = stream_async(
-            input,
-            thread_id: thread_id,
-            config: config,
-            on_tool_approval_required: on_tool_approval_required,
-            on_event: listener
-          ).wait_result
-          [result, result[:usage]]
-        end
+        _start_agent_operation(
+          input,
+          config: config,
+          mode: :stream,
+          listener: listener
+        ).wait_result
       end
 
       def stream_async(
         input,
-        thread_id: nil,
         config: {},
         invocation_context: nil,
-        on_tool_approval_required: nil,
-        on_event: nil,
-        &block
+        **removed_options,
+        &removed_block
       )
-        listener = resolve_event_listener(on_event, block)
-        raise ArgumentError, "stream_async requires on_event: or a block" unless listener
-        if invocation_context
-          thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
-        end
-        approval = _approval_configuration_snapshot(on_tool_approval_required)
-        execution_coordinator.start(
+        _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
+        listener = _required_stream_listener!(:stream_async)
+        config = _prepare_invocation_config(config, invocation_context)
+        _start_agent_operation(
           input,
-          thread_id: thread_id,
           config: config,
           mode: :stream,
-          approval_policy: approval[:policy],
-          approval_listener: approval[:listener],
-          on_event: listener
+          listener: listener
         )
       end
 
@@ -118,7 +95,14 @@ module Phronomy
       end
 
       def approve_async(execution_id, approval_request_id:, approved: true, config: {})
-        execution_coordinator.resume(
+        _reject_removed_generic_identity_keys!(config)
+        owner = Phronomy::Runtime.instance.__agent_execution_owner(execution_id)
+        coordinator = if owner&.agent&.equal?(self)
+          owner.coordinator
+        else
+          execution_coordinator_for(config)
+        end
+        coordinator.resume(
           execution_id,
           approval_request_id: approval_request_id,
           approved: approved,
@@ -126,17 +110,123 @@ module Phronomy
         )
       end
 
+      def resolve(
+        execution_id,
+        expected_execution_revision:,
+        subject:,
+        outcome:,
+        result: Phronomy::Recovery::MISSING,
+        error: Phronomy::Recovery::MISSING
+      )
+        _check_event_loop_reentrancy(:resolve, :resolve_async)
+        resolve_async(
+          execution_id,
+          expected_execution_revision: expected_execution_revision,
+          subject: subject,
+          outcome: outcome,
+          result: result,
+          error: error
+        ).wait_result
+      end
+
+      def resolve_async(
+        execution_id,
+        expected_execution_revision:,
+        subject:,
+        outcome:,
+        result: Phronomy::Recovery::MISSING,
+        error: Phronomy::Recovery::MISSING
+      )
+        Phronomy::Agent::RecoveryCoordinator.new(self).resolve(
+          execution_id,
+          expected_execution_revision: expected_execution_revision,
+          subject: subject,
+          outcome: outcome,
+          result: result,
+          error: error
+        )
+      end
+
       private
 
+      # Framework-private execution-local event routing. This is intentionally
+      # not a public compatibility path for invoke_async(..., on_event:).
+      def __invoke_async_with_event_sink(
+        input,
+        on_event:, config: {},
+        invocation_context: nil
+      )
+        raise ArgumentError, "on_event is required" unless on_event
+
+        config = _prepare_invocation_config(config, invocation_context)
+        _start_agent_operation(
+          input,
+          config: config,
+          mode: :invoke,
+          listener: on_event
+        )
+      end
+
+      def _start_agent_operation(input, config:, mode:, listener:)
+        config = _snapshot_durable_context(config)
+        approval = _approval_configuration_snapshot(nil)
+        execution_coordinator_for(config).start(
+          input,
+          config: config.merge(phronomy_recovery_mode: mode.to_sym),
+          mode: mode,
+          approval_policy: approval[:policy],
+          approval_listener: nil,
+          on_event: listener
+        )
+      end
+
+      def _snapshot_durable_context(config)
+        return config unless config.key?(:durable_context)
+
+        value = config[:durable_context]
+        unless value.is_a?(Hash)
+          raise ArgumentError,
+            "config[:durable_context] must be a canonical JSON-compatible Hash"
+        end
+
+        bytes = Phronomy::CanonicalJSON.dump(value)
+        snapshot = Phronomy::Agent::Immutable.copy(
+          Phronomy::CanonicalJSON.load(bytes)
+        )
+        config.merge(durable_context: snapshot)
+      end
+
+      def _required_stream_listener!(method_name)
+        listener = _phronomy_event_listener
+        return listener if listener
+
+        raise ArgumentError,
+          "#{method_name} requires an Agent on_event listener registered at new/create/load"
+      end
+
+      def _reject_removed_invocation_listener_arguments!(options, block)
+        if block
+          raise ArgumentError,
+            "invoke/stream blocks no longer register Agent events; register the listener at new/create/load"
+        end
+        return if options.empty?
+
+        removed = options.keys.map(&:inspect).join(", ")
+        raise ArgumentError,
+          "removed per-invocation Agent option(s): #{removed}; register on_event at new/create/load"
+      end
+
       def execution_coordinator
         @execution_coordinator ||= Agent::ExecutionCoordinator.new(self)
       end
 
-      def resolve_event_listener(keyword_listener, block_listener)
-        if keyword_listener && block_listener
-          raise ArgumentError, "Provide either on_event: or a block, not both"
-        end
-        keyword_listener || block_listener
+      def execution_coordinator_for(config)
+        multi_agent = config.key?(:phronomy_handoff_bindings) ||
+          config.key?(:phronomy_handoff_context)
+        return execution_coordinator unless multi_agent
+
+        @multi_agent_execution_coordinator ||=
+          Phronomy::Agent::HandoffExecutionCoordinator.new(self)
       end
     end
   end