phronomy 0.28.0 → 0.30.0

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

@@ -18,7 +18,7 @@ module Phronomy
         @agent, @id, @input, @config = agent, execution_id.to_s.freeze, input, config.freeze
         @resume_only = resume_only
         @environment = @agent.__execution_environment
-        @completion = Phronomy::TaskResult.deferred(name: "exact-execution:#{@id}")
+        @completion = OperationResult.new(agent: @agent, name: "exact-execution:#{@id}")
       end
 
       def start
@@ -43,13 +43,14 @@ module Phronomy
             [:absent, nil]
           end
         end
+        @completion.track(preparation)
         preparation.on_complete do |prepared, error|
           if error
-            @completion.fail(error)
+            @completion.settle(error: error)
           else
             disposition, result = prepared
             case disposition
-            when :terminal then @completion.complete(result)
+            when :terminal then @completion.settle(result)
             when :absent
               source = @agent.send(:_start_agent_operation, @input,
                 config: @config.merge(phronomy_reserved_execution_id: @id, phronomy_exact_observers: [@completion].freeze),
@@ -58,15 +59,15 @@ module Phronomy
             when :active
               command = Wait.new(coordinator: self, agent: @agent, execution_id: @id)
               posted = @environment.registry.post(command, completion: @completion)
-              @completion.fail(Phronomy::RuntimeShutdownError.new("Exact execution observer rejected")) unless posted
+              @completion.settle(error: Phronomy::RuntimeShutdownError.new("Exact execution observer rejected")) unless posted
             end
           end
         rescue => failure
-          @completion.fail(failure)
+          @completion.settle(error: failure)
         end
         @completion
       rescue => failure
-        @completion.fail(failure)
+        @completion.settle(error: failure)
         @completion
       end
 
@@ -101,7 +102,7 @@ module Phronomy
         waiter.on_complete { |_result, failure| reconcile(failure) }
         @environment.registry.register_agent_completion_waiter(@id, waiter)
       rescue => failure
-        @completion.fail(failure)
+        @completion.settle(error: failure)
       end
 
       private
@@ -120,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
@@ -157,15 +164,19 @@ module Phronomy
             ))
           end
         end
+        @completion.track(task)
         task.on_complete do |result, error|
-          error ? @completion.fail(error) : @completion.complete(result)
+          error ? @completion.settle(error: error) : @completion.settle(result)
         end
       rescue => error
-        @completion.fail(error)
+        @completion.settle(error: error)
       end
 
       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
@@ -93,7 +95,7 @@ module Phronomy
       )
         @agent.send(:__assert_live_agent!)
         @agent.send(:_reject_removed_generic_identity_keys!, config)
-        result_task = Phronomy::TaskResult.deferred(name: "agent-#{@agent.agent_id}-#{mode}")
+        result_task = OperationResult.new(agent: @agent, name: "agent-#{@agent.agent_id}-#{mode}")
         controls = Phronomy::InvocationControls.attach(result_task,
           invocation_context: config[:invocation_context],
           cancellation_token: config[:cancellation_token])
@@ -127,9 +129,8 @@ module Phronomy
       )
         @agent.send(:__assert_live_agent!)
         @agent.send(:_reject_removed_generic_identity_keys!, config)
-        result_task = Phronomy::TaskResult.deferred(
-          name: "agent-approval-resume:#{execution_id}"
-        )
+        result_task = OperationResult.new(agent: @agent,
+          name: "agent-approval-resume:#{execution_id}")
         command = ResumeCommand.new(
           coordinator: self,
           execution_id: execution_id.to_s.freeze,
@@ -255,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
@@ -269,7 +272,7 @@ module Phronomy
       def begin_start_on_event_loop(request)
         environment = @agent.__execution_environment
         request.controls.check_start!
-        root = @agent.agent_root
+        root = @agent.send(:__root_for_operation)
         if root.lifecycle_status == :closed
           deliver_start_failure_on_event_loop(
             request,
@@ -298,6 +301,7 @@ module Phronomy
           @initial_preparation.prepare(operation)
         end
         submitted = true
+        request.result_task.track(task) if request.result_task.respond_to?(:track)
         task.on_complete do |result, error|
           ready = InitialPreparationReady.new(
             coordinator: self,
@@ -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,
@@ -519,7 +524,7 @@ module Phronomy
 
         operation = InitialPreparation::RecoveryCommand.new(
           execution: execution,
-          root: @agent.agent_root,
+          root: @agent.send(:__root_for_operation),
           journal_records: @agent.send(:_journal_records_snapshot)
         )
         task = environment.submit(on_full: :raise) do
@@ -717,7 +722,7 @@ module Phronomy
           execution_id: state.execution_id,
           fsm_session_id: fsm_session_id.to_s.freeze,
           expected_execution_revision: state.execution.execution_revision,
-          root: @agent.agent_root,
+          root: @agent.send(:__root_for_operation),
           journal_records: @agent.send(:_journal_records_snapshot),
           execution: state.execution,
           base_manifest: state.base_manifest,
@@ -739,7 +744,7 @@ module Phronomy
           execution_id: state.execution_id,
           fsm_session_id: fsm_session_id.to_s.freeze,
           expected_execution_revision: state.execution.execution_revision,
-          root: @agent.agent_root,
+          root: @agent.send(:__root_for_operation),
           execution: state.execution,
           runtime_snapshot: invocation.runtime_snapshot,
           tool_batch_snapshot: tool_batch_snapshot,
@@ -911,16 +916,23 @@ 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)
         end
         submitted = true
+        request.result_task.track(task) if request.result_task.respond_to?(:track)
         task.on_complete do |result, error|
           ready = ResumeCommitReady.new(
             coordinator: self,
@@ -939,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
@@ -953,7 +968,7 @@ module Phronomy
         ResumeCommitCommand.new(
           execution_id: state.execution_id,
           expected_execution_revision: state.execution.execution_revision,
-          root: @agent.agent_root,
+          root: @agent.send(:__root_for_operation),
           execution: state.execution,
           approval_request_id: request.approval_request_id,
           approved: request.approved,
@@ -1042,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,
@@ -1254,7 +1270,7 @@ module Phronomy
 
         operation = build_terminal_operation(
           execution: state.execution,
-          root: @agent.agent_root,
+          root: @agent.send(:__root_for_operation),
           journal_records: @agent.send(:_journal_records_snapshot),
           invocation: invocation,
           source_error: source_error,
@@ -1338,6 +1354,7 @@ module Phronomy
           # worker boundary. TaskResult/listener delivery state stays outside it.
           @outcome_committer.commit_outcome(operation)
         end
+        delivery.result_task.track(task) if delivery.result_task.respond_to?(:track)
         task.on_complete do |outcome, error|
           ready = TerminalCommitReady.new(
             coordinator: self,
@@ -1371,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,
@@ -1440,7 +1458,7 @@ module Phronomy
         if operation.execution.metadata["reservation"] || operation.execution.metadata["execution_extension"]
           release_terminal_ownership(environment, operation.execution_id, state)
           environment.registry.take_agent_completion_waiters(operation.execution_id, fallback: delivery.result_task).each do |task|
-            task.fail(ready.error)
+            fail_task(task, ready.error)
           end
           return
         end
@@ -1477,7 +1495,7 @@ module Phronomy
         delivery = ready.delivery
         outcome = ready.outcome
         release_terminal_ownership(environment, operation.execution_id, state)
-        environment.registry.take_agent_completion_waiters(operation.execution_id, fallback: delivery.result_task).each { |task| task.fail(outcome.error) }
+        environment.registry.take_agent_completion_waiters(operation.execution_id, fallback: delivery.result_task).each { |task| fail_task(task, outcome.error) }
       end
 
       def suspend_execution_on_event_loop(ready, state, environment)
@@ -1489,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,
@@ -1501,10 +1520,50 @@ module Phronomy
           outcome.result
         )
         Array(state&.invocation&.config&.fetch(:phronomy_exact_observers, [])).each do |task|
-          task.fail(Phronomy::ExecutionRehydrationRequiredError.new("Execution #{operation.execution_id} requires approval"))
+          fail_task(task, Phronomy::ExecutionRehydrationRequiredError.new("Execution #{operation.execution_id} requires approval"))
+        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
@@ -1552,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
@@ -1695,6 +1755,7 @@ module Phronomy
         end
         if execution_error
           if execution_error.is_a?(Phronomy::CancellationError)
+            result_task.finish_operation! if result_task.respond_to?(:finish_operation!)
             result_task.cancel!(execution_error)
           else
             fail_task(result_task, execution_error)

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("class" => error.class.name, "message" => error.message)
+        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,
@@ -262,10 +271,7 @@ module Phronomy
         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
-          )
+          error_ref = tx.contents.put_json(Phronomy::Error.diagnostic(translated_error))
           status = ExecutionFailure.status_for(translated_error)
           records = preparation_failure_records(execution, root, status, error_ref)
           appended = tx.journals.append(

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

@@ -29,10 +29,7 @@ module Phronomy
           output_ref = assistant_output_ref(tx, outcome)
           assistant_ref = assistant_message_ref(tx, outcome)
           error_ref = if call_error
-            tx.contents.put_json(
-              "class" => call_error.class.name,
-              "message" => call_error.message
-            )
+            tx.contents.put_json(Phronomy::Error.diagnostic(call_error))
           end
           usage_ref = if outcome && outcome.usage.to_h.values.any? { |value| !value.nil? }
             tx.contents.put_json(json_value(outcome.usage.to_h))
@@ -172,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)

data/lib/phronomy/agent/execution_observation.rb

@@ -5,14 +5,14 @@ module Phronomy
     # Stable domain observation; does not expose repositories or FSM phases.
     # @api public
     ExecutionObservation = Data.define(:agent_id, :execution_id, :status, :result,
-      :error, :reservation, :transfer_receipt, :cancellation_requested) do
-      def initialize(**values)
-        super(**values.transform_values { |value| Phronomy::Values::Immutable.copy(value) })
+      :error, :reservation, :transfer_receipt, :cancellation_requested, :raw_output) do
+      def initialize(raw_output: nil, **values)
+        super(raw_output: Phronomy::Values::Immutable.copy(raw_output), **values.transform_values { |value| Phronomy::Values::Immutable.copy(value) })
       end
 
       def self.from_result(value)
         new(agent_id: value.fetch(:agent_id), execution_id: value.fetch(:execution_id), status: value.fetch(:status),
-          result: value[:result], error: value[:error], reservation: nil, transfer_receipt: nil, cancellation_requested: false)
+          result: value[:result], raw_output: value[:raw_output], error: value[:error], reservation: nil, transfer_receipt: nil, cancellation_requested: false)
       end
 
       def absent? = status == :absent
@@ -28,7 +28,7 @@ module Phronomy
 
       def to_result
         Phronomy::Values::Immutable.copy(execution_id: execution_id, agent_id: agent_id,
-          status: status, result: result, output: result, error: error)
+          status: status, result: result, output: result, raw_output: raw_output, error: error)
       end
     end
   end