phronomy 0.29.0 → 0.30.1

data/docs/features.md

@@ -32,6 +32,13 @@ for production deployments.
 | **Error Taxonomy** — Provider errors translated to Phronomy transport/authentication/rate-limit/context errors | Beta |
 | **Optional failure reason codes** — `Phronomy::Error#code` and `code:` retain domain-supplied reasons in saved Agent/Team diagnostics; [meaning and compatibility](failure-reason-codes.md) | Beta |
 
+The RubyLLM backends also translate identified Faraday timeout and connection
+failures to the owning `LLMAdapter::TransportError` or
+`Embeddings::TransportError`, retaining the original cause chain. A stream may
+have delivered partial output before failure; this classification does not imply
+that retry is safe. Callback failures and execution cancellation/deadlines keep
+their identity. See [transport error boundaries](architecture/transport-error-boundaries.md).
+
 Agent definition lineage is separate from Agent instance identity. A named
 concrete Agent may declare `agent_definition version: N`; when `id:` is omitted,
 its fully-qualified Ruby class name is the stable `agent_definition_id`.
@@ -97,7 +104,7 @@ See the [migration guide](migrations/parallel-tool-chat-removal.md).
 |---|---|
 | **Workflow asynchronous pattern** — `task_state` starts a `TaskResult`, applies its successful value once to the current state entry, and then evaluates ordinary transitions; `Workflow#signal` remains the application event API | Beta |
 | **Durable Handoff** — `MultiAgent::Handoff` and `MultiAgent::HandoffRunner` persist responsibility, immutable Context and exact Target reservation in one Persistence domain; current graph wiring is required for continuation | Beta |
-| **GeneratorVerifier** — Generator-Verifier loop with injectable prompts/parsers | Beta |
+| **GeneratorVerifier** — Generator-Verifier loop with application prompts, Agent-validated output schemas and explicit output failures | Beta |
 | **`Phronomy::MultiAgent::Orchestrator`** — Parallel subagent dispatch, fan-out, and `subagent` DSL | Beta |
 | **`Phronomy::MultiAgent::TeamCoordinator`** — LLM coordinator with stateful worker Agents | Beta |
 | **`Phronomy::MultiAgent::SharedState`** — Sequential peer-agent coordination through an invocation-local findings store; see the [namespace migration](migrations/shared-state-multi-agent.md) | Experimental |
@@ -193,3 +200,5 @@ claim. See [the migration](migrations/durable-semantic-coordination-v2.md).
 turn read-only, including a current absent-but-reserved Target, without graph or
 Agent hydration. Purging an idle main Agent removes its Handoff anchor; pending
 coordination rejects purge rather than discarding its reservation.
+
+Structured output and symmetric lifetime details: [contract and migration](architecture/structured-output-and-scope.md).

data/docs/migrations/r8-unit15.md

@@ -1,5 +1,8 @@
 # r8 unit15 migration
 
+> Historical contract: parser injection/fallback is superseded by
+> [structured output and scope](../architecture/structured-output-and-scope.md).
+
 ## Application impact
 
 No public API, data migration or configuration changes are required.

data/gemfiles/http_minimum.gemfile

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
 eval_gemfile "mcp_1_0.gemfile"
-gem "faraday", "= 2.1.0"
+gem "faraday", "= 2.14.4"
+gem "faraday-net_http", "= 3.4.4"
 gem "webmock", require: false
+
+# Strict JSON decoding and schema transport use these verified minimum versions.
+gem "json", "= 2.21.2"
+gem "ruby_llm", "= 2.0.0"

data/lib/phronomy/agent/admission.rb

@@ -47,7 +47,7 @@ module Phronomy
               "reservation" => correlation, "current_input_ref" => input_ref,
               "durable_context_ref" => context_ref,
               "execution_extension" => @config[:phronomy_execution_participant]&.binding&.to_h
-            }.merge(@preparation_metadata).compact)
+            }.merge(@preparation_metadata).merge(@config[:phronomy_output_contract]&.metadata(records.contents) || {}).compact)
           input_record = JournalRecord.from_h(input_record.to_h.merge("execution_id" => execution_id))
           execution = execution.with(execution_revision: 0, working_records: [input_record])
           records.executions.create_active(execution)

data/lib/phronomy/agent/async_event_api.rb

@@ -12,12 +12,12 @@ 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: {})
+      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_invocation_config(config, nil))
+          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
@@ -53,12 +53,13 @@ module Phronomy
         input,
         config: {},
         invocation_context: nil,
+        output_schema: nil,
         **removed_options,
         &removed_block
       )
         __with_operation do
           _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
-          config = _prepare_invocation_config(config, invocation_context)
+          config = _prepare_output_config(config, invocation_context, output_schema)
           _check_event_loop_reentrancy(:invoke, :invoke_async)
           _start_agent_operation(
             input,
@@ -73,12 +74,13 @@ module Phronomy
         input,
         config: {},
         invocation_context: nil,
+        output_schema: nil,
         **removed_options,
         &removed_block
       )
         __with_operation(async: true) do
           _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
-          config = _prepare_invocation_config(config, invocation_context)
+          config = _prepare_output_config(config, invocation_context, output_schema)
           _start_agent_operation(
             input,
             config: config,
@@ -92,13 +94,14 @@ module Phronomy
         input,
         config: {},
         invocation_context: nil,
+        output_schema: nil,
         **removed_options,
         &removed_block
       )
         __with_operation do
           _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
           listener = _required_stream_listener!(:stream)
-          config = _prepare_invocation_config(config, invocation_context)
+          config = _prepare_output_config(config, invocation_context, output_schema)
           _check_event_loop_reentrancy(:stream, :stream_async)
           _start_agent_operation(
             input,
@@ -113,13 +116,14 @@ module Phronomy
         input,
         config: {},
         invocation_context: nil,
+        output_schema: nil,
         **removed_options,
         &removed_block
       )
         __with_operation(async: true) do
           _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
           listener = _required_stream_listener!(:stream_async)
-          config = _prepare_invocation_config(config, invocation_context)
+          config = _prepare_output_config(config, invocation_context, output_schema)
           _start_agent_operation(
             input,
             config: config,
@@ -143,7 +147,7 @@ module Phronomy
 
       def approve_async(execution_id, approval_request_id:, approved: true, config: {})
         __with_operation(async: true) do
-          _reject_removed_generic_identity_keys!(config)
+          config = _prepare_invocation_config(config, nil)
           owner = __execution_environment.existing_registry&.agent_execution_owner(execution_id)
           coordinator = if owner&.agent&.equal?(self)
             owner.coordinator
@@ -202,6 +206,11 @@ module Phronomy
 
       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
@@ -727,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
 
@@ -871,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/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,

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

@@ -121,6 +121,12 @@ module Phronomy
         if expected && stored != expected
           raise Phronomy::Persistence::StateConflictError, "Reserved execution #{@id} correlation mismatch"
         end
+        unless @resume_only
+          expected_digest = @config[:phronomy_output_contract]&.digest
+          if expected_digest != execution.metadata.dig("output_contract", "schema_digest")
+            raise Phronomy::Persistence::StateConflictError, "Reserved execution output schema mismatch"
+          end
+        end
         ref = execution.metadata["current_input_ref"]
         @input = @agent.persistence.contents.fetch_text(ref) if @resume_only && ref
         if ref && @agent.persistence.contents.fetch_text(ref) != @input
@@ -168,6 +174,9 @@ module Phronomy
 
       def materialize(execution)
         result = @agent.persistence.result(execution.execution_id)
+        if result[:error].is_a?(Hash) && result[:error]["class"] == "Phronomy::Agent::OutputError"
+          raise RecoverySupport.error_from_failure(result[:error])
+        end
         result.merge(output: result[:result]).freeze
       end
     end

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

@@ -7,7 +7,6 @@ module Phronomy
     # @api private
     class ExecutionCancellation
       Command = Data.define(:coordinator, :execution_id, :agent_id)
-      private_constant :Command
 
       def self.signal(execution_id, agent_id, environment:)
         command = Command.new(coordinator: new(environment), execution_id: execution_id, agent_id: agent_id)
@@ -22,6 +21,7 @@ module Phronomy
         state = @environment.registry.agent_execution_state(command.execution_id)
         return unless state && state.agent.agent_id == command.agent_id
         state.invocation&.config&.fetch(:cancellation_token, nil)&.cancel!
+        state.coordinator.deliver_on_event_loop(command)
       end
     end
   end

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

@@ -74,6 +74,8 @@ module Phronomy
       TerminalCommitReady = Data.define(
         :coordinator, :operation, :delivery, :outcome, :error
       )
+      SuspensionCancelledCommand = Data.define(:coordinator, :execution_id)
+
       DeferredTerminalCommand = Data.define(
         :coordinator, :execution_id, :result_task, :invocation,
         :source_error, :fsm_session_id
@@ -254,6 +256,8 @@ module Phronomy
           apply_terminal_commit_on_event_loop(command)
         when DeferredTerminalCommand
           resume_deferred_terminal_on_event_loop(command)
+        when ExecutionCancellation::Command, SuspensionCancelledCommand
+          cancel_suspended_on_event_loop(command.execution_id)
         else
           raise Phronomy::Error, "unknown Agent control command: #{command.class}"
         end
@@ -428,6 +432,7 @@ module Phronomy
         Phronomy::Tracing::Automatic.observe_task(
           request.result_task,
           "agent.execution",
+          usage: ->(value) { value.is_a?(Hash) ? value[:usage]&.to_h&.freeze : nil },
           input: request.input,
           agent_id: @agent.agent_id,
           execution_id: prepared.execution.execution_id,
@@ -911,11 +916,17 @@ module Phronomy
         operation = capture_approval_resume(state, request)
         resume_transition_started = false
         submitted = false
-        environment.registry.mark_agent_execution_admission(
-          @agent.agent_id,
-          execution_id: state.execution_id,
-          state: :resuming
-        )
+        begin
+          environment.registry.mark_agent_execution_admission(
+            @agent.agent_id,
+            execution_id: state.execution_id,
+            state: :resuming,
+            expected_state: :suspended
+          )
+        rescue Phronomy::AgentBusyError => error
+          return fail_task(request.result_task, error)
+        end
+        suspended_cancellation = clear_suspended_cancellation
         resume_transition_started = true
         task = environment.submit(on_full: :raise) do
           @approval_resume_commit.commit(operation)
@@ -940,6 +951,9 @@ module Phronomy
             execution_id: state.execution_id,
             state: submitted ? :recovery_required : :suspended
           )
+          if !submitted && suspended_cancellation
+            bind_suspended_cancellation(*suspended_cancellation.first(3))
+          end
         end
         fail_task(request.result_task, error)
         raise unless resume_transition_started
@@ -1043,6 +1057,7 @@ module Phronomy
         Phronomy::Tracing::Automatic.observe_task(
           request.result_task,
           "agent.execution",
+          usage: ->(value) { value.is_a?(Hash) ? value[:usage]&.to_h&.freeze : nil },
           agent_id: @agent.agent_id,
           execution_id: operation.execution_id,
           mode: trace_mode,
@@ -1373,6 +1388,7 @@ module Phronomy
         TerminalView.new(
           phase: invocation&.phase,
           output: invocation&.output,
+          response: invocation&.final_response,
           usage: invocation&.usage,
           approval_request: invocation&.approval_request,
           rejected: invocation ? !!invocation.rejected : false,
@@ -1491,6 +1507,7 @@ module Phronomy
           execution_id: operation.execution_id,
           state: :suspended
         )
+        bind_suspended_cancellation(operation.execution_id, state.invocation, delivery.result_task)
         dispatch_approval_listener(delivery.approval_listener, outcome.approval_request)
         callback_error = deliver_terminal(
           delivery.application_listener,
@@ -1507,6 +1524,46 @@ module Phronomy
         end
       end
 
+      # Suspension closes the FSM session, but not the logical execution.
+      # Keep cancellation connected until approval resumes or the owner terminates.
+      def bind_suspended_cancellation(execution_id, invocation, result_task)
+        clear_suspended_cancellation
+        subscriptions = Phronomy::Concurrency::Subscriptions.new
+        @suspended_cancellation = [execution_id, invocation, result_task, subscriptions]
+        subscriptions.result(result_task) { subscriptions.close }
+        environment = @agent.__execution_environment
+        subscriptions.cancellation(invocation.config[:cancellation_token]) do
+          post_control(environment, SuspensionCancelledCommand.new(coordinator: self, execution_id: execution_id))
+        end
+      end
+
+      def clear_suspended_cancellation
+        record = @suspended_cancellation
+        @suspended_cancellation = nil
+        record&.last&.close
+        record
+      end
+
+      def cancel_suspended_on_event_loop(execution_id)
+        record = @suspended_cancellation
+        return unless record && record.first == execution_id
+        state = @agent.__execution_environment.registry.agent_execution_state(execution_id)
+        return unless state && state.execution.status == :suspended &&
+          state.invocation.equal?(record[1]) && state.fsm_session_id.nil?
+
+        @agent.__execution_environment.registry.mark_agent_execution_admission(
+          @agent.agent_id, execution_id: execution_id, state: :cancelling,
+          expected_state: :suspended
+        )
+        clear_suspended_cancellation
+        finish_on_event_loop(execution_id, record[2], state.invocation,
+          Phronomy::CancellationError.new("Agent execution cancelled during approval"),
+          fsm_session_id: nil)
+      rescue Phronomy::AgentBusyError
+        # A resume/terminal transition already owns this suspended boundary.
+        nil
+      end
+
       def deliver_completed_execution_on_event_loop(ready, state, environment)
         operation = ready.operation
         delivery = ready.delivery
@@ -1554,6 +1611,7 @@ module Phronomy
 
       def release_terminal_ownership(environment, execution_id, state)
         registry = environment.registry
+        clear_suspended_cancellation if @suspended_cancellation&.first == execution_id
         registry.release_agent_execution(execution_id) if state
         registry.release_agent_execution_admission(@agent.agent_id, execution_id: execution_id)
       end

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

@@ -13,8 +13,12 @@ module Phronomy
       TerminalView = Data.define(
         :phase, :output, :usage, :approval_request, :rejected,
         :input_blocked, :output_blocked, :block_error,
-        :invocation_error, :handoff, :callback_failure, :source_error, :cancel_requested
-      )
+        :invocation_error, :handoff, :callback_failure, :source_error, :cancel_requested, :response
+      ) do
+        def initialize(response: nil, **values)
+          super(**values, response: response)
+        end
+      end
       Command = Data.define(
         :execution_id, :fsm_session_id, :expected_execution_revision,
         :root, :journal_records, :execution, :runtime_snapshot,
@@ -36,6 +40,18 @@ module Phronomy
         view = operation.terminal_view
         error = view.callback_failure&.to_stream_callback_error || view.source_error ||
           view.block_error || view.invocation_error
+        if !error && !view.rejected && !view.handoff && view.phase != :suspended
+          begin
+            contract = OutputContract.restore(operation.execution, @persistence.contents)
+            if contract
+              output = contract.validate(view.output, response: view.response, execution_id: operation.execution_id)
+              view = view.with(output: output)
+              operation = operation.with(terminal_view: view)
+            end
+          rescue => validation_error
+            error = validation_error
+          end
+        end
         change = ExecutionChange.new(agent: @agent, current: operation.execution,
           root: operation.root, kind: :terminal, terminal: view, config: operation.wiring) do |tx, state, receipt, pending|
           if pending
@@ -147,7 +163,9 @@ module Phronomy
         current = operation.execution
         view = operation.terminal_view
         encoded_records, call_records = encode_runtime_records(tx, operation, context_candidate: true)
-        output_ref = tx.contents.put_text(view.output.to_s)
+        structured = current.metadata.key?("output_contract") && !view.rejected
+        output_ref = tx.contents.put_text(structured ? JSON.generate(view.output) : view.output.to_s)
+        output_metadata = structured ? {"result_format" => "json", "raw_output_ref" => tx.contents.put_text(view.response.content)} : {}
         records = current.working_records + encoded_records + completion_records(operation, output_ref)
         completed = current.with(
           status: view.rejected ? :rejected : :completed,
@@ -156,6 +174,7 @@ module Phronomy
           llm_calls: current.llm_calls + call_records,
           approval_request: nil,
           result_ref: output_ref,
+          metadata: current.metadata.merge(output_metadata),
           terminal_reason: view.rejected ? "rejected" : "completed"
         )
         [records, completed]
@@ -187,7 +206,7 @@ module Phronomy
       def encode_failure(tx, operation, error)
         current = operation.execution
         encoded_records, call_records = encode_runtime_records(tx, operation, context_candidate: false)
-        error_ref = tx.contents.put_json(Phronomy::Error.diagnostic(error))
+        error_ref = tx.contents.put_json(error.is_a?(OutputError) ? error.diagnostic : Phronomy::Error.diagnostic(error))
         terminal_status = ExecutionFailure.status_for(error)
         records = failure_records(operation, encoded_records, terminal_status, error_ref)
         failed = current.with(
@@ -252,6 +271,7 @@ module Phronomy
       def completed_outcome(view, execution, root, appended, messages)
         result = result_base(execution, root).merge(
           output: view.output,
+          raw_output: (execution.metadata["result_format"] == "json") ? view.response.content : nil,
           rejected: view.rejected || nil,
           usage: view.usage,
           messages: messages

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

@@ -145,7 +145,7 @@ module Phronomy
       end
 
       # @api private
-      def mark_agent_execution_admission(agent_id, execution_id:, state:)
+      def mark_agent_execution_admission(agent_id, execution_id:, state:, expected_state: nil)
         assert_event_loop_thread!
         key = agent_id.to_s
         execution_key = execution_id.to_s
@@ -161,6 +161,10 @@ module Phronomy
           unless current.execution_id.to_s == execution_key
             raise Phronomy::Error, "stale Agent admission state update for #{key.inspect}"
           end
+          if expected_state && current.state != expected_state
+            raise Phronomy::AgentBusyError,
+              "Agent #{key.inspect} is #{current.state}, expected #{expected_state}"
+          end
           @agent_admissions[key] = AgentAdmission.new(
             agent_id: current.agent_id,
             owner_token: current.owner_token,

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

@@ -105,6 +105,13 @@ module Phronomy
       def prepare_admitted(input:, config:, execution:, active_root:, journal_records:)
         current_execution = execution
         begin
+          # Legacy executions acquire a limit at their first resumed preparation.
+          current_execution = execution.with(
+            execution_revision: execution.execution_revision,
+            metadata: execution.metadata.merge(IterationBudget::LIMIT_KEY =>
+              IterationBudget.limit_for(execution, default: @agent.class.max_iterations))
+          )
+          IterationBudget.check!(current_execution, default: @agent.class.max_iterations)
           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)
@@ -184,7 +191,8 @@ module Phronomy
         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)
+          manifest, manifest_ref = Phronomy::Context::Assembly.new.store(prepared, contents: tx.contents,
+            response_schema_ref: staged.metadata.dig("output_contract", "schema_ref"))
           active = execution_with_initial_manifest(staged, manifest_ref)
           tx.executions.save(
             staged.execution_id,
@@ -222,6 +230,7 @@ module Phronomy
       def initial_preparation_metadata(mode, replayable)
         {
           "preparation_replayable" => !!replayable,
+          IterationBudget::LIMIT_KEY => IterationBudget.validate_limit(@agent.class.max_iterations),
           ExecutionMetadata::CONTRACT_VERSION_KEY => ExecutionMetadata::CONTRACT_VERSION,
           ExecutionMetadata::INVOCATION_MODE_KEY => mode.to_s,
           ExecutionMetadata::PENDING_LLM_ID_KEY => SecureRandom.uuid.to_s.freeze,

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

@@ -197,7 +197,7 @@ module Phronomy
 
       def self.finish_provider_trace(trace_handle, response, error)
         Phronomy::Tracing::Automatic.finish(trace_handle,
-          output: response, usage: response&.usage, error: error)
+          output: response, usage: response&.usage&.to_h&.freeze, error: error)
       end
       private_class_method :finish_provider_trace
 

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

@@ -25,6 +25,10 @@ module Phronomy
         recording_tool_results suspended output_filtering handed_off completed blocked failed
       ].freeze
 
+      # An automatic chain cannot visit more phases than an acyclic traversal.
+      # Logical LLM turns are bounded independently by IterationBudget.
+      AUTOMATIC_RECURSION_LIMIT = DECLARED_STATES.length
+
       WAIT_STATES = %i[suspended].freeze
 
       TOOL_EVENTS = %i[
@@ -115,10 +119,6 @@ module Phronomy
         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/iteration_budget.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Agent policy over existing execution facts. No Engine steps, provider
+    # retries, Tool events or context-selected messages contribute to this count.
+    # @api private
+    module IterationBudget
+      LIMIT_KEY = "agent_max_iterations"
+
+      module_function
+
+      def validate_limit(value)
+        unless value.is_a?(Integer) && value >= 0
+          raise ArgumentError, "Agent max_iterations must be a non-negative Integer"
+        end
+        value
+      end
+
+      def limit_for(execution, default:)
+        validate_limit(execution.metadata.fetch(LIMIT_KEY) { default })
+      end
+
+      def check!(execution, default:)
+        limit = limit_for(execution, default: default)
+        completed = execution.llm_calls.length
+        if completed >= limit
+          raise Phronomy::RecursionLimitError,
+            "Agent max_iterations (#{limit}) exceeded after #{completed} LLM calls"
+        end
+        limit
+      end
+    end
+  end
+end

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

@@ -169,6 +169,9 @@ module Phronomy
           "role" => "assistant",
           "content" => json_value(outcome.content),
           "tool_calls" => json_value(Array(outcome.tool_calls)),
+          "finish_reason" => outcome.finish_reason.to_s,
+          "refusal" => outcome.refusal,
+          "metadata" => outcome.metadata,
           "model_id" => outcome.metadata["model_id"]
         }.compact
         tx.contents.put_json(payload)