phronomy 0.28.0 → 0.30.0

data/lib/phronomy/agent/api/agent.rb

@@ -3,6 +3,17 @@
 module Phronomy
   module Agent
     StreamEvent = Data.define(:type, :payload)
+
+    # Own Agents acquired by the block, then attempt every release. A returned
+    # TaskResult is awaited and unwrapped; a plain value is returned unchanged.
+    # @yield [scope] the Runtime-bound owner of newly materialized Agents
+    # @yieldparam scope [Phronomy::Agent::Scope]
+    # @return [Object] the block value or resolved TaskResult value
+    # @raise [ScopeCleanupError] successful work whose Agent release failed
+    # @api public
+    def self.open_scope(&block)
+      Scope.send(:open, &block)
+    end
   end
 end
 
@@ -15,3 +26,5 @@ end
 # Durable Agent Recovery and Agent-incarnation event binding.
 require_relative "../recovery/recovery_support"
 require_relative "../recovery/recovery_coordinator"
+
+Phronomy::Agent::Base.prepend(Phronomy::Agent::LifetimeApi)

data/lib/phronomy/agent/async_event_api.rb

@@ -12,32 +12,40 @@ module Phronomy
     # - approval notifications share the Agent listener as :approval_required;
     # - Recovery resolution uses resolve/resolve_async.
     module AsyncEventApi
-      def start_reserved_async(reservation:, input:, config: {})
-        unless reservation.is_a?(ReservedExecution) && reservation.agent_id == agent_id
-          raise ArgumentError, "reservation must belong to this Agent"
+      def start_reserved_async(reservation:, input:, config: {}, output_schema: nil)
+        __with_operation(async: true) do
+          unless reservation.is_a?(ReservedExecution) && reservation.agent_id == agent_id
+            raise ArgumentError, "reservation must belong to this Agent"
+          end
+          config = __invocation_config(_prepare_output_config(config, nil, output_schema))
+          ExactExecution.start(agent: self, execution_id: reservation.execution_id, input: input,
+            config: config.merge(phronomy_reservation: reservation.correlation))
         end
-        config = __invocation_config(_prepare_invocation_config(config, nil))
-        ExactExecution.start(agent: self, execution_id: reservation.execution_id, input: input,
-          config: config.merge(phronomy_reservation: reservation.correlation))
       end
 
       def resume_async(execution_id, config: {})
-        config = __invocation_config(_prepare_invocation_config(config, nil))
-        ExactExecution.start(agent: self, execution_id: execution_id, input: nil, config: config, resume_only: true)
+        __with_operation(async: true) do
+          config = __invocation_config(_prepare_invocation_config(config, nil))
+          ExactExecution.start(agent: self, execution_id: execution_id, input: nil, config: config, resume_only: true)
+        end
       end
 
       def resume(execution_id, config: {})
-        _check_event_loop_reentrancy(:resume, :resume_async)
-        resume_async(execution_id, config: config).wait_result
+        __with_operation do
+          _check_event_loop_reentrancy(:resume, :resume_async)
+          resume_async(execution_id, config: config).wait_result
+        end
       end
 
       def cancel_async(execution_id)
-        __assert_live_agent!
-        environment = __execution_environment
-        environment.submit(on_full: :raise) do
-          requested = persistence.request_cancellation(agent_id: agent_id, execution_id: execution_id)
-          ExecutionCancellation.signal(execution_id, agent_id, environment: environment) if requested
-          persistence.observe_execution(agent_id: agent_id, execution_id: execution_id)
+        __with_operation(async: true) do
+          __assert_live_agent!
+          environment = __execution_environment
+          environment.submit(on_full: :raise) do
+            requested = persistence.request_cancellation(agent_id: agent_id, execution_id: execution_id)
+            ExecutionCancellation.signal(execution_id, agent_id, environment: environment) if requested
+            persistence.observe_execution(agent_id: agent_id, execution_id: execution_id)
+          end
         end
       end
 
@@ -45,98 +53,114 @@ module Phronomy
         input,
         config: {},
         invocation_context: nil,
+        output_schema: nil,
         **removed_options,
         &removed_block
       )
-        _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
-        config = _prepare_invocation_config(config, invocation_context)
-        _check_event_loop_reentrancy(:invoke, :invoke_async)
-        _start_agent_operation(
-          input,
-          config: config,
-          mode: :invoke,
-          listener: _phronomy_event_listener
-        ).wait_result
+        __with_operation do
+          _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
+          config = _prepare_output_config(config, invocation_context, output_schema)
+          _check_event_loop_reentrancy(:invoke, :invoke_async)
+          _start_agent_operation(
+            input,
+            config: config,
+            mode: :invoke,
+            listener: _phronomy_event_listener
+          ).wait_result
+        end
       end
 
       def invoke_async(
         input,
         config: {},
         invocation_context: nil,
+        output_schema: nil,
         **removed_options,
         &removed_block
       )
-        _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
-        config = _prepare_invocation_config(config, invocation_context)
-        _start_agent_operation(
-          input,
-          config: config,
-          mode: :invoke,
-          listener: _phronomy_event_listener
-        )
+        __with_operation(async: true) do
+          _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
+          config = _prepare_output_config(config, invocation_context, output_schema)
+          _start_agent_operation(
+            input,
+            config: config,
+            mode: :invoke,
+            listener: _phronomy_event_listener
+          )
+        end
       end
 
       def stream(
         input,
         config: {},
         invocation_context: nil,
+        output_schema: nil,
         **removed_options,
         &removed_block
       )
-        _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)
-        _start_agent_operation(
-          input,
-          config: config,
-          mode: :stream,
-          listener: listener
-        ).wait_result
+        __with_operation do
+          _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
+          listener = _required_stream_listener!(:stream)
+          config = _prepare_output_config(config, invocation_context, output_schema)
+          _check_event_loop_reentrancy(:stream, :stream_async)
+          _start_agent_operation(
+            input,
+            config: config,
+            mode: :stream,
+            listener: listener
+          ).wait_result
+        end
       end
 
       def stream_async(
         input,
         config: {},
         invocation_context: nil,
+        output_schema: nil,
         **removed_options,
         &removed_block
       )
-        _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,
-          config: config,
-          mode: :stream,
-          listener: listener
-        )
+        __with_operation(async: true) do
+          _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
+          listener = _required_stream_listener!(:stream_async)
+          config = _prepare_output_config(config, invocation_context, output_schema)
+          _start_agent_operation(
+            input,
+            config: config,
+            mode: :stream,
+            listener: listener
+          )
+        end
       end
 
       def approve(execution_id, approval_request_id:, approved: true, config: {})
-        _check_event_loop_reentrancy(:approve, :approve_async)
-        approve_async(
-          execution_id,
-          approval_request_id: approval_request_id,
-          approved: approved,
-          config: config
-        ).wait_result
+        __with_operation do
+          _check_event_loop_reentrancy(:approve, :approve_async)
+          approve_async(
+            execution_id,
+            approval_request_id: approval_request_id,
+            approved: approved,
+            config: config
+          ).wait_result
+        end
       end
 
       def approve_async(execution_id, approval_request_id:, approved: true, config: {})
-        _reject_removed_generic_identity_keys!(config)
-        owner = Phronomy::Agent::ExecutionRegistry.existing_current&.agent_execution_owner(execution_id)
-        coordinator = if owner&.agent&.equal?(self)
-          owner.coordinator
-        else
-          execution_coordinator_for(config)
+        __with_operation(async: true) do
+          config = _prepare_invocation_config(config, nil)
+          owner = __execution_environment.existing_registry&.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,
+            config: config
+          )
         end
-        coordinator.resume(
-          execution_id,
-          approval_request_id: approval_request_id,
-          approved: approved,
-          config: config
-        )
       end
 
       def resolve(
@@ -147,15 +171,17 @@ module Phronomy
         result: Phronomy::Agent::RecoveryRules::MISSING,
         error: Phronomy::Agent::RecoveryRules::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
+        __with_operation do
+          _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
       end
 
       def resolve_async(
@@ -166,18 +192,25 @@ module Phronomy
         result: Phronomy::Agent::RecoveryRules::MISSING,
         error: Phronomy::Agent::RecoveryRules::MISSING
       )
-        Phronomy::Agent::RecoveryCoordinator.new(self).resolve(
-          execution_id,
-          expected_execution_revision: expected_execution_revision,
-          subject: subject,
-          outcome: outcome,
-          result: result,
-          error: error
-        )
+        __with_operation(async: true) do
+          Phronomy::Agent::RecoveryCoordinator.new(self).resolve(
+            execution_id,
+            expected_execution_revision: expected_execution_revision,
+            subject: subject,
+            outcome: outcome,
+            result: result,
+            error: error
+          )
+        end
       end
 
       private
 
+      def _prepare_output_config(config, invocation_context, schema)
+        config = _prepare_invocation_config(config, invocation_context)
+        schema.nil? ? config : config.merge(phronomy_output_contract: OutputContract.new(schema))
+      end
+
       def _start_agent_operation(input, config:, mode:, listener:)
         config = __invocation_config(_snapshot_durable_context(config))
         @_phronomy_execution_wiring = config.dup.freeze

data/lib/phronomy/agent/base.rb

@@ -101,6 +101,9 @@ module Phronomy
           end
         end
 
+        # Maximum logical LLM calls per execution, including the first call.
+        # Tool calls and SDK transport retries do not consume extra iterations.
+        # The limit is captured at admission; zero admits no LLM call.
         def max_iterations(val = nil)
           if val
             @max_iterations = val
@@ -292,10 +295,14 @@ module Phronomy
       # @api private
       def __invocation_config(config) = config
 
-      def knowledge_snapshot = persistence.knowledge_snapshot(agent_id: agent_id)
+      def knowledge_snapshot
+        __with_operation { persistence.knowledge_snapshot(agent_id: agent_id) }
+      end
 
       # Listener inheritance is an explicit orchestration choice, not a private getter.
-      def event_listener = _phronomy_event_listener
+      def event_listener
+        __with_operation(read_only: true) { _phronomy_event_listener }
+      end
 
       attr_reader :agent_id, :persistence
 
@@ -371,65 +378,81 @@ module Phronomy
       end
 
       def agent_root
-        __assert_agent_accessible!
-        @root
+        __with_operation(read_only: true) do
+          __assert_agent_accessible!
+          @root
+        end
       end
 
       def journal_projection
-        __assert_agent_accessible!
-        Agent::JournalProjection.new(
-          agent_root: @root,
-          records: _journal_records_snapshot
-        )
+        __with_operation(read_only: true) do
+          __assert_agent_accessible!
+          Agent::JournalProjection.new(
+            agent_root: @root,
+            records: _journal_records_snapshot
+          )
+        end
       end
 
       def transcript
-        journal_projection.transcript_records
+        __with_operation(read_only: true) do
+          journal_projection.transcript_records
+        end
       end
 
       def clear_transcript!
-        mutate_context!(:transcript_cleared) do |root|
-          root.with(
-            agent_revision: root.agent_revision + 1,
-            context_revision: root.context_revision + 1,
-            transcript_generation: root.transcript_generation + 1
-          )
+        __with_operation do
+          mutate_context!(:transcript_cleared) do |root|
+            root.with(
+              agent_revision: root.agent_revision + 1,
+              context_revision: root.context_revision + 1,
+              transcript_generation: root.transcript_generation + 1
+            )
+          end
         end
       end
 
       def clear_knowledge!
-        mutate_context!(:knowledge_cleared) do |root|
-          root.with(
-            agent_revision: root.agent_revision + 1,
-            context_revision: root.context_revision + 1
-          )
+        __with_operation do
+          mutate_context!(:knowledge_cleared) do |root|
+            root.with(
+              agent_revision: root.agent_revision + 1,
+              context_revision: root.context_revision + 1
+            )
+          end
         end
       end
 
       def add_knowledge(content, metadata: {})
-        __assert_live_agent!
-        current = agent_root
-        update = state_writer.add_knowledge(root: current, content: content, metadata: metadata)
-        apply_state_update(update)
-        self
+        __with_operation do
+          __assert_live_agent!
+          current = agent_root
+          update = state_writer.add_knowledge(root: current, content: content, metadata: metadata)
+          apply_state_update(update)
+          self
+        end
       end
 
       def reset_context!
-        mutate_context!(:context_reset) do |root|
-          root.with(
-            agent_revision: root.agent_revision + 1,
-            context_revision: root.context_revision + 1,
-            transcript_generation: root.transcript_generation + 1
-          )
+        __with_operation do
+          mutate_context!(:context_reset) do |root|
+            root.with(
+              agent_revision: root.agent_revision + 1,
+              context_revision: root.context_revision + 1,
+              transcript_generation: root.transcript_generation + 1
+            )
+          end
         end
       end
 
       def close!
-        mutate_context!(:agent_closed, context_affecting: false) do |root|
-          root.with(
-            agent_revision: root.agent_revision + 1,
-            lifecycle_status: :closed
-          )
+        __with_operation do
+          mutate_context!(:agent_closed, context_affecting: false) do |root|
+            root.with(
+              agent_revision: root.agent_revision + 1,
+              lifecycle_status: :closed
+            )
+          end
         end
       end
 
@@ -544,7 +567,7 @@ module Phronomy
 
       # @api private
       def __release_runtime_owner!(runtime)
-        return self if @_phronomy_runtime_owner_state == :purged
+        return self if %i[purged unloaded].include?(@_phronomy_runtime_owner_state)
         return self unless @_phronomy_runtime_owner.equal?(runtime)
 
         @_phronomy_runtime_owner_state = :released
@@ -579,7 +602,12 @@ module Phronomy
         if load_existing
           root = records = nil
           @persistence.transaction do |tx|
-            root = tx.agents.load(@agent_id)
+            begin
+              root = tx.agents.load(@agent_id)
+            rescue Phronomy::Persistence::NotFoundError => error
+              raise if error.is_a?(Phronomy::AgentNotFoundError)
+              raise Phronomy::AgentNotFoundError.new(agent_id: @agent_id), cause: error
+            end
             records = tx.journals.read(
               @agent_id,
               limit: root.journal_position
@@ -656,11 +684,13 @@ module Phronomy
       public
 
       def tool_approval_policy(&block)
-        __assert_live_agent!
-        raise ArgumentError, "tool_approval_policy requires a block" unless block
+        __with_operation do
+          __assert_live_agent!
+          raise ArgumentError, "tool_approval_policy requires a block" unless block
 
-        _approval_configuration_mutex.synchronize { @tool_approval_policy = block }
-        self
+          _approval_configuration_mutex.synchronize { @tool_approval_policy = block }
+          self
+        end
       end
 
       private
@@ -671,6 +701,8 @@ module Phronomy
           true
         when :purged
           raise Phronomy::AgentPurgedError, "Agent #{agent_id.inspect} has been purged"
+        when :unloaded
+          raise Phronomy::AgentUnloadedError.new(agent_id: agent_id)
         when :purging
           raise Phronomy::Error, "Agent #{agent_id.inspect} is being purged"
         when :recovery_required
@@ -698,6 +730,9 @@ module Phronomy
       def _prepare_invocation_config(config, invocation_context)
         __assert_live_agent!
         _reject_removed_generic_identity_keys!(config)
+        if config.keys.any? { |key| %w[output_schema response_schema phronomy_output_contract].include?(key.to_s) }
+          raise ArgumentError, "Use the output_schema keyword on a new Agent execution"
+        end
         invocation_context ?
           config.merge(invocation_context: invocation_context) : config
 
@@ -728,10 +763,12 @@ module Phronomy
       end
 
       def _complete_result_task(task, result)
+        task.finish_operation! if task.respond_to?(:finish_operation!)
         task.complete(result)
       end
 
       def _fail_result_task(task, error)
+        task.finish_operation! if task.respond_to?(:finish_operation!)
         task.fail(error)
       end
 
@@ -840,7 +877,8 @@ module Phronomy
         definitions = Phronomy::Tool::DefinitionSet.build(tools: invocation.tools.values).definitions
         Phronomy::LLMAdapter::Request.new(
           model_config: projection.model_config, system: projection.system,
-          messages: invocation.messages, tools: definitions, message: projection.ask_message
+          messages: invocation.messages, tools: definitions, message: projection.ask_message,
+          response_schema: projection.response_schema
         )
       end
 

data/lib/phronomy/agent/before_llm_input.rb

@@ -19,7 +19,13 @@ module Phronomy
         def _before_llm_input = @before_llm_input
       end
 
-      attr_accessor :before_llm_input
+      def before_llm_input
+        __with_operation(read_only: true) { @before_llm_input }
+      end
+
+      def before_llm_input=(value)
+        __with_operation { @before_llm_input = value }
+      end
 
       private
 

data/lib/phronomy/agent/context_importer.rb

@@ -116,6 +116,10 @@ module Phronomy
             "content" => normalize(content),
             "tool_calls" => calls
           }
+          metadata = read_optional(message, :metadata) || {}
+          raise ArgumentError, "imported assistant metadata must be a Hash" unless metadata.is_a?(Hash)
+          Phronomy::Values::Immutable.validate_canonical_json!(metadata, label: "imported assistant metadata")
+          payload["metadata"] = Phronomy::Values::Immutable.copy(metadata) unless metadata.empty?
           model_id = read_optional(message, :model_id)
           payload["model_id"] = model_id.to_s if model_id
 

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

@@ -46,7 +46,8 @@ module Phronomy
         :rejected,
         :error
 
-      attr_reader :execution_id,
+      attr_reader :final_response,
+        :execution_id,
         :agent,
         :config,
         :approval_policy,
@@ -73,7 +74,9 @@ module Phronomy
         @agent = agent
         @input = input
         # The caller's Hash must not become a shared mutable Runtime object.
-        @config = config.dup
+        # OutputContract is admission-only; the durable Manifest owns subsequent
+        # schema projection. Never forward the parent promise to an Agent Tool.
+        @config = config.except(:phronomy_output_contract)
         resolved_execution_id = execution_id || @config[:execution_id]
         @execution_id = resolved_execution_id&.to_s&.freeze
         invocation_context = @config[:invocation_context]
@@ -269,6 +272,7 @@ module Phronomy
         raise Phronomy::Error, "LLM operation completed without a response" unless response
 
         @user_message_sent = true
+        @final_response = response
         @output = response.content
         @usage = response.usage
         @pending_tool_calls = []

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

@@ -34,6 +34,7 @@ module Phronomy
       def prepare_provider(operation)
         staged = stage_provider_call(operation)
         recorded = encode_provider_records(operation, staged)
+        IterationBudget.check!(recorded, default: @agent.class.max_iterations)
         assembler, prepared = prepare_provider_context(operation, recorded)
         committed, manifest, manifest_ref = commit_provider_preparation(
           operation, recorded, assembler, prepared
@@ -56,6 +57,9 @@ module Phronomy
 
       def stage_provider_call(operation)
         metadata = operation.execution.metadata.dup
+        metadata[IterationBudget::LIMIT_KEY] = IterationBudget.limit_for(
+          operation.execution, default: @agent.class.max_iterations
+        )
         metadata.delete(ExecutionMetadata::TOOL_BATCH_METADATA_KEY)
         metadata.delete(ExecutionMetadata::RECOVERY_METADATA_KEY)
         metadata[ExecutionMetadata::PENDING_LLM_ID_KEY] = operation.pending_llm_call_id
@@ -118,7 +122,8 @@ module Phronomy
       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)
+          Phronomy::Context::Assembly.new.store(prepared, contents: tx.contents,
+            response_schema_ref: recorded.metadata.dig("output_contract", "schema_ref"))
         end
         updated = execution_with_provider_manifest(recorded, manifest_ref)
         change = ExecutionChange.new(agent: @agent, current: operation.execution,