phronomy 0.28.0 → 0.30.0

data/lib/phronomy/llm_adapter/response.rb

@@ -8,13 +8,20 @@ module Phronomy
     # Completed assistant turn. Tool requests do not authorize execution.
     # @api public
     class Response < Message
-      attr_reader :usage
+      attr_reader :usage, :finish_reason, :refusal
 
       # @api public
-      def initialize(content: nil, tool_calls: [], usage: Phronomy::LLMAdapter::TokenUsage.new, metadata: {}, role: :assistant)
+      def initialize(content: nil, tool_calls: [], usage: Phronomy::LLMAdapter::TokenUsage.new, metadata: {}, role: :assistant,
+        finish_reason: :unknown, refusal: nil)
         raise ArgumentError, "LLM response must be an assistant message" unless role == :assistant || role == "assistant"
         raise ArgumentError, "LLM usage must be LLMAdapter::TokenUsage" unless usage.is_a?(Phronomy::LLMAdapter::TokenUsage)
         @usage = usage
+        unless %w[stop tool_calls length content_filter refusal unknown].include?(finish_reason.to_s)
+          raise ArgumentError, "invalid LLM finish reason"
+        end
+        raise ArgumentError, "refusal must be a String or nil" unless refusal.nil? || refusal.is_a?(String)
+        @finish_reason = finish_reason.to_sym
+        @refusal = refusal&.dup&.freeze
         super(role: :assistant, content: content, tool_calls: tool_calls, metadata: metadata)
       end
 
@@ -24,12 +31,12 @@ module Phronomy
         new(role: source.fetch("role", "assistant"), content: source["content"],
           tool_calls: source.fetch("tool_calls", []).map { |call| Phronomy::Tool::CallRequest.from_h(call) },
           usage: Phronomy::LLMAdapter::TokenUsage.new(**source.fetch("usage", {}).transform_keys(&:to_sym)),
-          metadata: source.fetch("metadata", {}))
+          metadata: source.fetch("metadata", {}), finish_reason: source.fetch("finish_reason", "unknown"), refusal: source["refusal"])
       end
 
       # @api public
       def to_h
-        super.merge("usage" => usage.to_h.transform_keys(&:to_s))
+        super.merge("usage" => usage.to_h.transform_keys(&:to_s), "finish_reason" => finish_reason.to_s, "refusal" => refusal)
       end
     end
   end

data/lib/phronomy/llm_adapter/structured_output_unsupported_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module LLMAdapter
+    # The selected native schema path cannot implement the requested contract.
+    # @api public
+    class StructuredOutputUnsupportedError < Phronomy::Error
+      # @api public
+      def initialize(message = "Native structured output is unsupported")
+        super(message, code: "llm.structured_output_unsupported")
+      end
+    end
+  end
+end

data/lib/phronomy/llm_adapter/transport_error.rb

@@ -4,6 +4,10 @@ require_relative "../common/error"
 
 module Phronomy
   module LLMAdapter
+    # A provider communication/generation failure. Optional reason code
+    # "llm.provider_output_parse_failed" means the provider rejected its own
+    # generated output format. It is not application JSON/schema validation,
+    # does not imply a particular HTTP status, and does not authorize replay.
     class TransportError < Phronomy::Error; end
   end
 end

data/lib/phronomy/multi_agent/persistence/team_execution_repository.rb

@@ -12,7 +12,7 @@ module Phronomy
           Phronomy::Persistence::StorageBoundary.call do
             raise Phronomy::Storage::SerializationError, "create_active requires an active TeamExecution" unless execution.active?
             record = Codec.encode_team_execution(execution)
-            admission do
+            admission(execution.team_id) do
               @view.atomic do |bound|
                 entry = bound.records(Phronomy::MultiAgent::Persistence::StorageSchema::EXECUTIONS).insert(key: execution.team_execution_id.to_s,
                   revision: Integer(execution.execution_revision), attributes: attributes(execution), record: record)
@@ -42,7 +42,7 @@ module Phronomy
               raise Phronomy::Storage::SerializationError, "Execution identity mismatch"
             end
             record = Codec.encode_team_execution(execution)
-            admission do
+            admission(execution.team_id) do
               @view.atomic do |bound|
                 entry = bound.records(Phronomy::MultiAgent::Persistence::StorageSchema::EXECUTIONS).replace(key: team_execution_id.to_s,
                   expected_revision: expected, next_revision: revision, attributes: attributes(execution),
@@ -92,7 +92,7 @@ module Phronomy
               conditions: [condition])
           rescue Phronomy::Storage::ConditionFailedError => error
             raise unless error.condition.equal?(condition)
-            raise Phronomy::AgentBusyError, error.message
+            raise Phronomy::MultiAgent::TeamBusyError.new(error.message, team_id: team_id), cause: error
           end
         end
 
@@ -100,11 +100,11 @@ module Phronomy
 
         def attributes(execution) = {owner: execution.team_id.to_s, active: execution.active?}
 
-        def admission
+        def admission(team_id)
           yield
         rescue Phronomy::Storage::UniqueConstraintError => error
           raise unless error.resource == Phronomy::MultiAgent::Persistence::StorageSchema::EXECUTIONS.id && error.constraint == :one_active_owner
-          raise Phronomy::AgentBusyError, error.message
+          raise Phronomy::MultiAgent::TeamBusyError.new(error.message, team_id: team_id), cause: error
         end
 
         def decode(entry, team_execution_id, owner: nil, revision: nil, active: nil)

data/lib/phronomy/multi_agent/shared_state.rb

@@ -179,6 +179,7 @@ module Phronomy
         # instrumentation.
         instrumented_def = instrumented_definition_for(researcher_class)
         Class.new(researcher_class) do
+          model researcher_class.model
           agent_definition(
             id: instrumented_def.fetch(:id),
             version: instrumented_def.fetch(:version)

data/lib/phronomy/multi_agent/team_busy_error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  module MultiAgent
+    # Describes the Team itself, not a child Agent.
+    # @api public
+    class TeamBusyError < Phronomy::Error
+      attr_reader :team_id
+
+      def initialize(message = nil, team_id:)
+        @team_id = team_id.to_s.dup.freeze
+        super(message || "Team #{@team_id}: busy", code: "team.busy")
+      end
+    end
+  end
+end

data/lib/phronomy/multi_agent/team_coordinator.rb

@@ -188,11 +188,22 @@ module Phronomy
           begin
             store.transaction { |tx| tx.teams.create(intended) }
           rescue => error
-            confirmed = store.teams.load(id)
+            begin
+              confirmed = store.teams.load(id)
+            rescue
+              # A failed readback cannot turn an unknown create outcome into
+              # a claim that the Team is absent or safe to create again.
+              raise error, cause: error.cause
+            end
             raise error unless confirmed.to_h == intended.to_h
           end
         end
-        root = store.teams.load(id)
+        begin
+          root = store.teams.load(id)
+        rescue Phronomy::Persistence::NotFoundError => error
+          raise if create || error.is_a?(TeamNotFoundError)
+          raise TeamNotFoundError.new(team_id: id), cause: error
+        end
         unless root.team_definition_id == definition.fetch(:id) && root.team_definition_version == definition.fetch(:version)
           raise Phronomy::ConfigurationError, "Team #{id} definition mismatch"
         end
@@ -238,7 +249,7 @@ module Phronomy
         begin
           persistence.transaction do |tx, scope|
             root = tx.teams.load(team_id)
-            raise Phronomy::AgentBusyError, "Team #{team_id} has an active run; use resume" unless tx.team_executions.list_active(team_id).empty?
+            raise TeamBusyError.new("Team #{team_id} has an active run; use resume", team_id: team_id) unless tx.team_executions.list_active(team_id).empty?
             intended = TeamExecution.new(team_execution_id: id, team_id: team_id,
               execution_revision: 0, status: "active", phase: "coordinator", input_ref: tx.contents.put_text(input),
               coordinator: {"agent_id" => SecureRandom.uuid, "execution_id" => SecureRandom.uuid, "state" => "reserved"},
@@ -341,7 +352,7 @@ module Phronomy
               output = Phronomy::Values::Serializable.convert(aggregate ? aggregate.call(values) : values, unsupported_message: "Team result is not canonically serializable")
               Phronomy::CanonicalJSON.dump(output)
             rescue => error
-              return terminal_value(finish_error(id, {"class" => error.class.name.to_s, "message" => error.message.to_s}))
+              return terminal_value(finish_error(id, Phronomy::Error.diagnostic(error)))
             end
             # Aggregate may be replayed only until the canonical outcome commits.
             completed = update(id) do |fresh, tx, scope|
@@ -465,7 +476,7 @@ module Phronomy
         raise Phronomy::CancellationError, "Team run #{execution.team_execution_id} cancelled" if execution.status == "cancelled"
         if execution.error_ref
           failure = persistence.contents.fetch_json(execution.error_ref)
-          raise Phronomy::Error, "#{failure.fetch("class")}: #{failure.fetch("message")}"
+          raise Phronomy::Error.from_diagnostic(failure)
         end
         persistence.contents.fetch_json(execution.result_ref)
       end
@@ -514,7 +525,7 @@ module Phronomy
             Phronomy::Execution.submit(on_full: :raise) do
               team.send(:apply_operation, run_id, key, operation, arguments)
             rescue OperationRejected => error
-              raise Phronomy::ConfigurationError, error.message
+              raise Phronomy::ConfigurationError.new(error.message, code: error.code)
             rescue Phronomy::CancellationError
               raise
             rescue => error
@@ -551,7 +562,9 @@ module Phronomy
             name = entry.name
             values = entry.arguments
             if name == "enqueue_task"
-              raise OperationRejected, "Cannot enqueue after finalize" if metadata["finalized"]
+              if metadata["finalized"]
+                raise OperationRejected.new("Cannot enqueue after finalize", code: "team.enqueue_after_finalize")
+              end
               task = {"id" => Digest::SHA256.hexdigest(entry_id)[0, 32], "description" => values.fetch("description"), "metadata" => values["metadata"]}
               tasks << task
               output = "Task ##{tasks.length} enqueued: #{task.fetch("description")}"

data/lib/phronomy/multi_agent/team_not_found_error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "../persistence/errors"
+
+module Phronomy
+  module MultiAgent
+    # Describes the Team itself, not a child Agent.
+    # @api public
+    class TeamNotFoundError < Phronomy::Persistence::NotFoundError
+      attr_reader :team_id
+
+      def initialize(message = nil, team_id:)
+        @team_id = team_id.to_s.dup.freeze
+        super(message || "Team #{@team_id}: not_found", code: "team.not_found")
+      end
+    end
+  end
+end

data/lib/phronomy/output_parser/json_schema_parser.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "json"
+require "json_schemer"
+require "uri"
+require_relative "../common/values/immutable"
+
+module Phronomy
+  module OutputParser
+    # Strict JSON decoding and validation, without extraction or value coercion.
+    # @api public
+    class JsonSchemaParser < Base
+      KEYWORDS = %w[$schema $defs $ref title description type enum const anyOf
+        properties required additionalProperties items minItems maxItems minimum
+        maximum exclusiveMinimum exclusiveMaximum multipleOf minLength maxLength pattern].freeze
+      private_constant :KEYWORDS
+
+      # @api public
+      attr_reader :json_schema
+
+      # @api public
+      def initialize(schema:)
+        @json_schema = Phronomy::Values::Immutable.json(schema)
+        unless @json_schema.is_a?(Hash) && @json_schema["type"] == "object"
+          raise ArgumentError, "output schema must declare a root object"
+        end
+        validate_node!(@json_schema, [])
+        options = {ref_resolver: ->(_uri) { raise ArgumentError, "external output schema reference" }}
+        unless JSONSchemer.valid_schema?(@json_schema, **options)
+          raise ArgumentError, "invalid output JSON Schema"
+        end
+        @validator = JSONSchemer.schema(@json_schema, **options)
+        freeze
+      end
+
+      # @api public
+      def parse(text)
+        value = decode(text)
+        violations = @validator.validate(value).map do |error|
+          {"pointer" => error.fetch("data_pointer", ""),
+           "schema_pointer" => error.fetch("schema_pointer", ""),
+           "keyword" => error.fetch("type", "schema")}
+        end
+        unless violations.empty?
+          raise Phronomy::ParseError.new("Output does not satisfy its JSON schema",
+            code: "output_parser.schema_mismatch", details: violations)
+        end
+        value
+      end
+
+      private
+
+      def decode(text)
+        raise JSON::ParserError, "output must be JSON text" unless text.is_a?(String)
+        Phronomy::Values::Immutable.json(JSON.parse(text, allow_duplicate_key: false, allow_nan: false, allow_comments: false, allow_invalid_escape: false, allow_control_characters: false))
+      rescue JSON::ParserError, ArgumentError
+        raise Phronomy::ParseError.new("Output is not strict JSON",
+          code: "output_parser.invalid_json", details: [{"pointer" => "", "keyword" => "json"}]), cause: nil
+      end
+
+      def validate_node!(node, ancestors)
+        return if node == true || node == false
+        raise ArgumentError, "invalid output schema node" unless node.is_a?(Hash)
+        raise ArgumentError, "cyclic output schema reference" if ancestors.include?(node.object_id)
+        ancestors += [node.object_id]
+        unknown = node.keys - KEYWORDS
+        raise ArgumentError, "unsupported output schema keywords: #{unknown.join(", ")}" unless unknown.empty?
+        if node.key?("$schema") && node["$schema"] != "https://json-schema.org/draft/2020-12/schema"
+          raise ArgumentError, "output schemas require JSON Schema 2020-12"
+        end
+        if node.key?("pattern")
+          raise ArgumentError, "pattern must be a String" unless node["pattern"].is_a?(String)
+          begin
+            Regexp.new(node["pattern"])
+          rescue RegexpError
+            raise ArgumentError, "invalid output schema pattern"
+          end
+        end
+        %w[properties $defs].each do |key|
+          next unless node.key?(key)
+          raise ArgumentError, "#{key} must be an object" unless node[key].is_a?(Hash)
+          node[key].each_value { |child| validate_node!(child, ancestors) }
+        end
+        if node.key?("anyOf")
+          raise ArgumentError, "anyOf must be an array" unless node["anyOf"].is_a?(Array)
+          node["anyOf"].each { |child| validate_node!(child, ancestors) }
+        end
+        %w[items additionalProperties].each do |key|
+          validate_node!(node[key], ancestors) if node.key?(key)
+        end
+        validate_node!(resolve_reference(node["$ref"]), ancestors) if node.key?("$ref")
+      end
+
+      def resolve_reference(reference)
+        valid = reference.is_a?(String) && (reference == "#" || reference.start_with?("#/"))
+        unless valid
+          raise ArgumentError, "output schemas support local JSON Pointer references only"
+        end
+        URI::DEFAULT_PARSER.unescape(reference.delete_prefix("#")).split("/", -1).drop(1).reduce(@json_schema) do |node, token|
+          raise ArgumentError, "invalid output schema JSON Pointer" if token.match?(/~(?![01])/)
+          key = token.gsub("~1", "/").gsub("~0", "~")
+          if node.is_a?(Hash) && node.key?(key)
+            node.fetch(key)
+          elsif node.is_a?(Array) && key.match?(/\A(?:0|[1-9][0-9]*)\z/) && key.to_i < node.length
+            node.fetch(key.to_i)
+          else
+            raise ArgumentError, "output schema reference does not exist"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/output_parser/parse_error.rb

@@ -3,5 +3,14 @@
 require_relative "../common/error"
 
 module Phronomy
-  class ParseError < Error; end
+  class ParseError < Error
+    # @api public
+    attr_reader :details
+
+    # @api public
+    def initialize(message = nil, code: nil, details: [])
+      @details = Phronomy::Values::Immutable.json(details)
+      super(message, code: code)
+    end
+  end
 end

data/lib/phronomy/runtime_composition/agent_defaults.rb

@@ -9,3 +9,7 @@ Phronomy::Agent::DefaultPersistence.install_factory(
 )
 
 Phronomy::Agent::ExecutionEnvironment.install_provider(-> { Phronomy::Agent::EngineEnvironment.new })
+
+Phronomy::Agent::OutputContract.install_factory(
+  ->(schema) { Phronomy::OutputParser::JsonSchemaParser.new(schema: schema) }
+)

data/lib/phronomy/storage/condition_failed_error.rb

@@ -7,9 +7,9 @@ module Phronomy
     class ConditionFailedError < ConflictError
       attr_reader :condition
       # @api public
-      def initialize(condition)
+      def initialize(condition, code: nil)
         @condition = condition
-        super("storage condition failed: #{condition.class.name}")
+        super("storage condition failed: #{condition.class.name}", code: code)
       end
     end
   end

data/lib/phronomy/storage/unique_constraint_error.rb

@@ -7,10 +7,10 @@ module Phronomy
     class UniqueConstraintError < ConflictError
       attr_reader :resource, :constraint
       # @api public
-      def initialize(resource:, constraint:)
+      def initialize(resource:, constraint:, code: nil)
         @resource = resource.id
         @constraint = constraint
-        super("unique constraint #{resource.id}.#{constraint} failed")
+        super("unique constraint #{resource.id}.#{constraint} failed", code: code)
       end
     end
   end

data/lib/phronomy/testing/persistence_contract/coordination_repositories.rb

@@ -84,7 +84,7 @@ RSpec.shared_examples "a Team execution repository" do
   it "atomically admits at most one active run per Team" do
     stores.multi_agent.team_executions.create_active(coordination_run)
     other = coordination_run.with(team_execution_id: SecureRandom.uuid, execution_revision: 0)
-    expect { stores.multi_agent.team_executions.create_active(other) }.to raise_error(Phronomy::AgentBusyError)
+    expect { stores.multi_agent.team_executions.create_active(other) }.to raise_error(Phronomy::MultiAgent::TeamBusyError)
     expect(stores.multi_agent.team_executions.list_active(coordination_team.team_id).map(&:team_execution_id)).to eq([coordination_run.team_execution_id])
   end
 

data/lib/phronomy/tool/base.rb

@@ -383,8 +383,9 @@ module Phronomy
         if schema_error
           case self.class.on_schema_error
           when :raise
-            raise Phronomy::ToolError,
-              "#{self.class.name} schema error: #{schema_error}"
+            raise Phronomy::ToolError.new(
+              "#{self.class.name} schema error: #{schema_error}", code: "tool.invalid_arguments"
+            )
           else
             return "Schema validation failed: #{schema_error}"
           end
@@ -399,17 +400,12 @@ module Phronomy
         raise
       rescue => error
         if self.class.on_error == :suppress
-          msg = "[Phronomy] Tool #{self.class.name} suppressed error: " \
-            "#{error.class}: #{error.message}"
-          if Phronomy::RuntimeSettings.current.logger
-            Phronomy::RuntimeSettings.current.logger.warn(msg)
-          else
-            warn msg
-          end
+          report_suppressed_error(error)
           "Tool error suppressed: #{error.message}"
         else
-          raise Phronomy::ToolError,
-            "#{self.class.name} execution failed: #{error.message}"
+          raise Phronomy::ToolError.new(
+            "#{self.class.name} execution failed: #{error.message}", code: "tool.execution_failed"
+          ), cause: error
         end
       end
 
@@ -462,7 +458,9 @@ module Phronomy
         if schema_error
           return Phronomy::AsyncOperation.capture(name: "#{operation_name}-schema") do
             if self.class.on_schema_error == :raise
-              raise Phronomy::ToolError, "#{self.class.name} schema error: #{schema_error}"
+              raise Phronomy::ToolError.new(
+                "#{self.class.name} schema error: #{schema_error}", code: "tool.invalid_arguments"
+              )
             end
             "Schema validation failed: #{schema_error}"
           end
@@ -472,8 +470,9 @@ module Phronomy
           transform: method(:truncate_result_if_needed)) do
           source = yield(validated_args || {})
           unless source.respond_to?(:on_complete)
-            raise Phronomy::ToolError,
-              "#{self.class.name} asynchronous execution must return a completion handle"
+            raise Phronomy::ToolError.new(
+              "#{self.class.name} asynchronous execution must return a completion handle", code: "tool.invalid_async_result"
+            )
           end
           source
         end
@@ -488,23 +487,26 @@ module Phronomy
         end
 
         if self.class.on_error == :suppress
-          message = "[Phronomy] Tool #{self.class.name} suppressed error: " \
-            "#{error.class}: #{error.message}"
-          if Phronomy::RuntimeSettings.current.logger
-            Phronomy::RuntimeSettings.current.logger.warn(message)
-          else
-            warn message
-          end
+          report_suppressed_error(error)
           "Tool error suppressed: #{error.message}"
         else
           wrapped = Phronomy::ToolError.new(
-            "#{self.class.name} execution failed: #{error.message}"
+            "#{self.class.name} execution failed: #{error.message}", code: "tool.execution_failed"
           )
           wrapped.set_backtrace(error.backtrace)
-          raise wrapped
+          raise wrapped, cause: error
         end
       end
 
+      def report_suppressed_error(error)
+        message = "[Phronomy] Tool #{self.class.name} suppressed error: #{error.class}: #{error.message}"
+        logger = Phronomy::RuntimeSettings.current.logger
+        logger ? logger.warn(message) : warn(message)
+      rescue
+        # A diagnostic failure must not change the selected suppression policy.
+        nil
+      end
+
       def execute_accepts_cancellation_token?
         method(:execute).parameters.any? do |type, name|
           name == :cancellation_token && %i[key keyreq].include?(type)

data/lib/phronomy/tracing/automatic.rb

@@ -65,23 +65,23 @@ module Phronomy
         # simplecov:enable
       end
 
-      def observe_task(task, name, input: nil, **metadata)
+      def observe_task(task, name, input: nil, usage: nil, **metadata)
         handle = start(name, input: input, **metadata)
         task.on_complete do |value, error|
           finish(
             handle,
             output: value,
-            usage: task_usage(value),
+            usage: observed_usage(usage, value, handle),
             error: error
           )
         end
         task
       end
 
-      def trace(name, input: nil, **metadata)
+      def trace(name, input: nil, usage: nil, **metadata)
         handle = start(name, input: input, **metadata)
         result = yield
-        finish(handle, output: result, usage: task_usage(result))
+        finish(handle, output: result, usage: observed_usage(usage, result, handle))
         result
       rescue => operation_error
         finish(handle, error: operation_error) if defined?(handle)
@@ -122,12 +122,18 @@ module Phronomy
       end
       private_class_method :traced_error
 
-      def task_usage(value)
-        return nil unless value.is_a?(Hash)
+      # The owner of the observed result supplies its projection. Tracing never
+      # interprets Agent results or LLM value objects. Projection is diagnostic:
+      # its failure must not replace the completed operation's result/error.
+      def observed_usage(project, value, handle)
+        return nil unless handle && project
 
-        value[:usage] || value["usage"]
+        project.call(value)
+      rescue => error
+        report_failure(:usage, handle.name, error, include_message: handle.trace_pii)
+        nil
       end
-      private_class_method :task_usage
+      private_class_method :observed_usage
 
       def submit_finish(handle, attributes)
         Phronomy::Blocking.call_async do

data/lib/phronomy/tracing/base.rb

@@ -34,15 +34,44 @@ module Phronomy
       # @return [Object] the block's return value
       # @api public
       def trace(name, input: nil, **meta)
-        span = start_span(name, input: input, **meta)
-        result, usage = yield span
-        finish_span(span, output: result, usage: usage)
+        Base.trace_with(self, name, attributes: {input: input, **meta}) { |span| yield span }
+      end
+
+      # Use the public start/finish SPI, including duck-typed tracers.
+      # Start failures do not finish; finish is attempted once after execution.
+      # A secondary finish/reporting failure cannot replace the block's error.
+      # Set record_output: false for metadata-only operations.
+      # @api public
+      def self.trace_with(tracer, name, record_output: true, attributes: {})
+        span = tracer.start_span(name, **attributes)
+        begin
+          result, usage = yield span
+        rescue => primary
+          begin
+            tracer.finish_span(span, error: primary)
+          rescue => secondary
+            report_secondary(secondary)
+          end
+          raise
+        end
+        if record_output
+          tracer.finish_span(span, output: result, usage: usage)
+        else
+          tracer.finish_span(span)
+        end
         result
-      rescue => e
-        finish_span(span, error: e)
-        raise
       end
 
+      def self.report_secondary(error)
+        Phronomy::RuntimeSettings.current.logger&.warn(
+          "[Phronomy::Tracing] secondary finish failure: #{error.class}: #{error.message}"
+        )
+      rescue
+        # Diagnostics are best effort; preserve the primary business failure.
+        nil
+      end
+      private_class_method :report_secondary
+
       # Start a new span. Must return an object that will be passed to #finish_span.
       #
       # @param name [String]
@@ -57,7 +86,8 @@ module Phronomy
       #
       # @param span [Object] the span returned by #start_span
       # @param output [Object, nil] successful output value
-      # @param usage [Phronomy::LLMAdapter::TokenUsage, nil] token usage for this span
+      # @param usage [Hash{Symbol => Integer, nil}, nil] observed token counts;
+      #   :input, :output, :cached, :cache_creation. The caller projects its domain value.
       # @param error [Exception, nil] exception if the block raised
       # @api public
       def finish_span(span, output: nil, usage: nil, error: nil)

data/lib/phronomy/tracing/langfuse_tracer.rb

@@ -71,9 +71,9 @@ module Phronomy
         body[:statusMessage] = error.message if error
         if usage
           body[:usage] = {
-            input: usage.input,
-            output: usage.output,
-            total: (usage.input || 0) + (usage.output || 0)
+            input: usage[:input],
+            output: usage[:output],
+            total: (usage[:input] || 0) + (usage[:output] || 0)
           }
         end
         ingest([{type: "span-create", body: body}])

data/lib/phronomy/tracing/observation.rb

@@ -5,7 +5,8 @@ module Phronomy
     module Observation
       # Convenience wrapper that delegates to the global tracer.
       # Yields a span; the block must return [result, usage] where usage is a
-      # Phronomy::LLMAdapter::TokenUsage or nil. Returns only the result value.
+      # Hash of observed token counts or nil. Returns only the result value.
+      # Domain objects must be projected by the caller before entering Tracing.
       #
       # When +trace_pii+ is disabled, both the input and the output (LLM response,
       # tool result) are replaced with the literal string "[REDACTED]" before being