smith-agents 0.7.0 → 0.10.0

data/lib/smith/tool.rb

@@ -4,23 +4,68 @@ require "ruby_llm"
 
 require_relative "tool/capability_builder"
 require_relative "tool/policy"
+require_relative "tool/call_budget"
+require_relative "tool/call_batch"
+require_relative "tool/legacy_call_allowance"
+require_relative "tool/call_allowance_counter"
 require_relative "tool/call_allowance"
+require_relative "tool/call_reservation"
+require_relative "tool/call_admission"
+require_relative "tool/execution_authority"
+require_relative "tool/execution_authorization"
+require_relative "tool/execution_tracker"
+require_relative "tool/execution_lifecycle"
+require_relative "tool/invocation"
+require_relative "tool/argument_snapshot_result"
+require_relative "tool/argument_scalar_snapshot"
+require_relative "tool/argument_container_reader"
+require_relative "tool/argument_snapshot_accounting"
+require_relative "tool/argument_snapshot_traversal"
+require_relative "tool/argument_snapshot"
+require_relative "tool/invocation_request"
+require_relative "tool/invocation_sequence"
+require_relative "tool/execution_batch_collection"
+require_relative "tool/execution_batch_invocations"
+require_relative "tool/execution_batch_source_metadata"
+require_relative "tool/execution_batch_source_call"
+require_relative "tool/execution_batch_sources"
+require_relative "tool/execution_batch_state"
+require_relative "tool/execution_batch"
+require_relative "tool/execution_batch_admission"
+require_relative "tool/execution_batch_requests"
+require_relative "tool/execution_batch_builder"
+require_relative "tool/execution_batch_registry"
 require_relative "tool/budget_enforcement"
 require_relative "tool_capture_failed"
 require_relative "tool/capture"
 require_relative "tool/capture_configuration"
 require_relative "tool/compatibility"
 require_relative "tool/scoped_context"
+require_relative "tool/bounded_completion_state"
+require_relative "tool/bounded_completion_guard"
+require_relative "tool/bounded_completion_controls"
+require_relative "tool/fail_fast_completion"
+require_relative "tool/graceful_completion"
+require_relative "tool/bounded_completion_context"
+require_relative "tool/bounded_completion_installation"
+require_relative "tool/execution_failure_handling"
+require_relative "tool/execution_dispatch"
+require_relative "tool/chat_execution_callbacks"
+require_relative "tool/execution_batch_lifecycle"
 require_relative "tool/chat_execution_context"
 
 module Smith
   class Tool < RubyLLM::Tool
     include Policy
+    include ExecutionAuthorization
+    include ExecutionLifecycle
     include BudgetEnforcement
     include Capture
     extend CaptureConfiguration
     extend ScopedContext
 
+    private_constant :ExecutionAuthority
+
     class << self
       # Tool subclasses inherit the parent's compatible_with spec by
       # reference (the spec is a frozen Hash; immutability makes shared
@@ -75,24 +120,32 @@ module Smith
     end
 
     def execute(**kwargs)
-      ensure_capture_ready!
-      run_before_execute_hook!(kwargs)
-      check_tool_deadline!
-      check_privilege!(kwargs)
-      check_authorization!(kwargs)
-      run_tool_guardrails!(kwargs)
-      check_tool_deadline!
-      charge_tool_call!
-
-      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      result = perform(**kwargs)
-      duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+      authorize_tool_execution!
+      kwargs.freeze
+      prepare_tool_execution!(kwargs)
+      result, duration = perform_with_duration(kwargs)
 
       emit_tool_trace(kwargs, result, duration)
       capture_result_if_configured(kwargs, result)
       result
     end
 
+    protected
+
+    def invocation_argument_error(arguments) = validate_keyword_arguments(normalize_args(arguments))
+
+    def execute_keyword_signature
+      parameters = method(:perform).parameters
+      required_keywords = parameters.filter_map { |kind, name| name if kind == :keyreq }
+      optional_keywords = parameters.filter_map { |kind, name| name if kind == :key }
+      accepts_extra_keywords = parameters.any? { |kind, _| kind == :keyrest }
+      accepts_positional_arguments = parameters.any? do |kind, _|
+        RubyLLM::Tool::POSITIONAL_PARAMETER_KINDS.include?(kind)
+      end
+
+      [required_keywords, optional_keywords, accepts_extra_keywords, accepts_positional_arguments]
+    end
+
     private
 
     def run_before_execute_hook!(kwargs)
@@ -112,9 +165,18 @@ module Smith
     end
 
     def emit_tool_trace(kwargs, result, duration)
+      # tool_call_id is the provider's correlation id for this invocation
+      # (present only when the call came from a provider batch); it lets a
+      # host join this trace to its own per-invocation records.
       Smith::Trace.record(
         type: :tool_call,
-        data: { tool: name, args: kwargs, result: result, duration: duration },
+        data: {
+          tool: name,
+          args: kwargs,
+          result: result,
+          duration: duration,
+          tool_call_id: self.class.current_invocation&.tool_call_id
+        }.compact,
         sensitivity: self.class.capabilities&.dig(:sensitivity) || :low
       )
     end
@@ -126,6 +188,12 @@ module Smith
       raise DeadlineExceeded, "wall_clock deadline exceeded during tool execution" if Time.now.utc >= deadline
     end
 
+    def check_dispatch_deadline!
+      check_tool_deadline!
+    rescue DeadlineExceeded
+      raise ToolDispatchRejected, "tool deadline expired before dispatch"
+    end
+
     def perform(**kwargs)
       raise NotImplementedError, "#{self.class} must implement #perform"
     end

data/lib/smith/tool_execution_not_admitted.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module Smith
+  class ToolExecutionNotAdmitted < Error; end
+end

data/lib/smith/tool_failure_notification_failed.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative "error"
+require_relative "diagnostic_text"
+
+module Smith
+  class ToolFailureNotificationFailed < Error
+    DETAIL_NAMES = %i[
+      dispatch_error_class dispatch_error_message notification_error_class notification_error_message
+    ].freeze
+    DETAIL_KEYS = DETAIL_NAMES.to_h { |name| [name.to_s.freeze, name] }.freeze
+    EXCEPTION_MESSAGE = Exception.instance_method(:message)
+    MODULE_NAME = Module.instance_method(:name)
+    OBJECT_CLASS = Object.instance_method(:class)
+    private_constant :DETAIL_NAMES, :DETAIL_KEYS, :EXCEPTION_MESSAGE, :MODULE_NAME, :OBJECT_CLASS
+
+    attr_reader :details, :dispatch_error, :notification_error
+
+    def initialize(dispatch_error:, notification_error:)
+      @dispatch_error = dispatch_error
+      @notification_error = notification_error
+      @details = build_details
+      super(
+        "host failed to record a terminal tool outcome: " \
+        "#{@details.fetch(:notification_error_class)}: #{@details.fetch(:notification_error_message)}"
+      )
+    end
+
+    def build_details
+      {
+        dispatch_error_class: DiagnosticText.capture(error_class_name(dispatch_error), max_bytes: 512),
+        dispatch_error_message: DiagnosticText.capture(error_message(dispatch_error)),
+        notification_error_class: DiagnosticText.capture(error_class_name(notification_error), max_bytes: 512),
+        notification_error_message: DiagnosticText.capture(error_message(notification_error))
+      }.freeze
+    end
+    private :build_details
+
+    def self.from_details(details)
+      values = normalize_details(details)
+      new(
+        dispatch_error: restored_error(values, :dispatch_error),
+        notification_error: restored_error(values, :notification_error)
+      )
+    end
+
+    def self.normalize_details(details)
+      raise ArgumentError, "tool failure notification details must be a Hash" unless details.is_a?(Hash)
+
+      values = details.each_with_object({}) do |(key, value), normalized|
+        append_detail!(normalized, key, value)
+      end
+      validate_complete!(values)
+      values.freeze
+    end
+
+    def self.append_detail!(normalized, key, value)
+      name = normalize_detail_name(key)
+      raise ArgumentError, "tool failure notification details contain an unknown attribute" unless name
+      raise ArgumentError, "tool failure notification details contain a duplicate attribute" if normalized.key?(name)
+      raise ArgumentError, "tool failure notification detail values must be strings" unless value.is_a?(String)
+
+      normalized[name] = value
+    end
+
+    def self.validate_complete!(values)
+      missing = DETAIL_NAMES - values.keys
+      raise ArgumentError, "tool failure notification details are missing required attributes" if missing.any?
+    end
+
+    def self.normalize_detail_name(key)
+      return key if key.is_a?(Symbol) && DETAIL_NAMES.include?(key)
+
+      DETAIL_KEYS[key] if key.is_a?(String)
+    end
+
+    def self.restored_error(values, prefix)
+      RuntimeError.new(
+        "#{values.fetch(:"#{prefix}_class")}: #{values.fetch(:"#{prefix}_message")}"
+      )
+    end
+
+    def error_class_name(error)
+      error_class = OBJECT_CLASS.bind_call(error)
+      MODULE_NAME.bind_call(error_class) || MODULE_NAME.bind_call(error_class.superclass) || "StandardError"
+    end
+
+    def error_message(error) = EXCEPTION_MESSAGE.bind_call(error)
+    private :error_class_name, :error_message
+
+    private_class_method :normalize_details, :append_detail!, :validate_complete!, :normalize_detail_name,
+                         :restored_error
+  end
+end

data/lib/smith/trace/logger.rb

@@ -7,6 +7,7 @@ module Smith
         transition: :trace_transitions,
         tool_call: :trace_tool_calls,
         token_usage: :trace_token_usage,
+        provider_call: :trace_provider_calls,
         cost: :trace_cost,
         normalizer_decision: :trace_normalizer
       }.freeze

data/lib/smith/trace/memory.rb

@@ -7,26 +7,62 @@ module Smith
         transition: :trace_transitions,
         tool_call: :trace_tool_calls,
         token_usage: :trace_token_usage,
+        provider_call: :trace_provider_calls,
         cost: :trace_cost,
         normalizer_decision: :trace_normalizer
       }.freeze
 
       CONTENT_KEYS = %i[content prompt response args result].freeze
 
-      attr_reader :traces
+      # Generous enough that test and development runs never hit it; a bound
+      # exists at all so a long-lived process with parallel branches cannot
+      # grow this adapter without limit.
+      DEFAULT_LIMIT = 10_000
 
-      def initialize
+      attr_reader :traces, :limit
+
+      def initialize(limit: DEFAULT_LIMIT)
+        unless limit.is_a?(Integer) && limit.positive?
+          raise ArgumentError, "Smith::Trace::Memory limit must be a positive integer, got #{limit.inspect}"
+        end
+
+        @limit = limit
         @traces = []
+        @dropped_count = 0
+        @mutex = Mutex.new
       end
 
       def record(type:, data:)
         return unless type_enabled?(type)
 
-        @traces << { type: type, data: filter_content(data) }
+        entry = { type: type, data: filter_content(data) }
+        @mutex.synchronize do
+          if @traces.length >= @limit
+            @dropped_count += 1
+          else
+            @traces << entry
+          end
+        end
+      end
+
+      # Entries rejected because the adapter was full. Zero in any healthy
+      # test run; a growing value means the limit needs raising or the
+      # process needs a clear!.
+      def dropped_count
+        @mutex.synchronize { @dropped_count }
+      end
+
+      # A consistent copy for readers that may race concurrent recording;
+      # #traces stays the live array for compatibility.
+      def snapshot
+        @mutex.synchronize { @traces.dup }
       end
 
       def clear!
-        @traces = []
+        @mutex.synchronize do
+          @traces = []
+          @dropped_count = 0
+        end
       end
 
       private

data/lib/smith/trace/open_telemetry.rb

@@ -7,7 +7,9 @@ module Smith
         transition: :trace_transitions,
         tool_call: :trace_tool_calls,
         token_usage: :trace_token_usage,
-        cost: :trace_cost
+        provider_call: :trace_provider_calls,
+        cost: :trace_cost,
+        normalizer_decision: :trace_normalizer
       }.freeze
 
       CONTENT_KEYS = %i[content prompt response args result].freeze
@@ -23,18 +25,60 @@ module Smith
         )
       end
 
+      # Smith trace events describe operations that already finished, so the
+      # span is created retroactively: when the event carries a duration
+      # (:tool_call seconds, :provider_call milliseconds) the span's start is
+      # backdated by it and the span duration is real; otherwise the span is
+      # an instant. Uses only the documented opentelemetry-api surface
+      # (Tracer#start_span with start_timestamp, Span#finish with
+      # end_timestamp) so any SDK the host installs applies.
       def record(type:, data:)
         return unless @tracer
         return unless type_enabled?(type)
 
         filtered = filter_content(data)
-        @tracer.in_span("smith.#{type}") do |span|
-          filtered.each { |key, value| span.set_attribute("smith.#{key}", value.to_s) }
+        finished_at = Time.now
+        span = @tracer.start_span("smith.#{type}", start_timestamp: span_start(filtered, finished_at))
+        begin
+          apply_attributes(span, filtered)
+        ensure
+          span.finish(end_timestamp: finished_at)
         end
       end
 
       private
 
+      def span_start(data, finished_at)
+        seconds = duration_seconds(data)
+        seconds ? finished_at - seconds : finished_at
+      end
+
+      def duration_seconds(data)
+        return data[:duration].to_f if data[:duration].is_a?(Numeric)
+        return data[:duration_ms] / 1000.0 if data[:duration_ms].is_a?(Numeric)
+
+        nil
+      end
+
+      def apply_attributes(span, data)
+        data.each do |key, value|
+          coerced = attribute_value(value)
+          span.set_attribute("smith.#{key}", coerced) unless coerced.nil?
+        end
+      end
+
+      # OpenTelemetry attributes accept strings, integers, floats, and
+      # booleans; numeric values keep their type instead of arriving as
+      # strings, everything else (symbols included) becomes a string, nil
+      # drops.
+      def attribute_value(value)
+        case value
+        when String, Integer, Float, true, false then value
+        when nil then nil
+        else value.to_s
+        end
+      end
+
       def type_enabled?(type)
         config_key = CONFIG_MAP[type]
         return true unless config_key

data/lib/smith/trace.rb

@@ -1,34 +1,53 @@
 # frozen_string_literal: true
 
+require_relative "attribution"
+
 module Smith
   module Trace
     SENSITIVITY_CONTENT_KEYS = %i[args result].freeze
+    ADAPTER_MUTEX = Mutex.new
+    private_constant :ADAPTER_MUTEX
 
     def self.record(type:, data:, sensitivity: :low)
       adapter = resolve_adapter
       return unless adapter
 
-      filtered = apply_content_policy(data, sensitivity)
+      filtered = apply_content_policy(attributed(data), sensitivity)
       filtered = filter_fields(type, filtered)
       adapter.record(type: type, data: filtered)
     rescue StandardError => e
       Smith.config.logger&.error("Smith::Trace adapter error: #{e.message}")
     end
 
+    # Ambient attribution keys are identifiers, not content: they merge in
+    # under the caller's own keys (the caller wins on conflict) and then pass
+    # through the same content policy and field allowlist as everything else,
+    # so a host's configured trace_fields contract keeps holding.
+    def self.attributed(data)
+      return data unless Smith.config.trace_attribution
+
+      fields = Attribution.current_fields
+      return data if fields.empty?
+
+      fields.merge(data)
+    end
+
+    # Class-configured adapters memoize one instance under a mutex so
+    # concurrent first records (every fan-out branch emits) share a single
+    # adapter instead of racing separate instances and losing entries.
     def self.resolve_adapter
       configured = Smith.config.trace_adapter
       return nil unless configured
+      return configured unless configured.is_a?(Class)
 
-      if configured.is_a?(Class)
+      ADAPTER_MUTEX.synchronize do
         @adapter_instances ||= {}
         @adapter_instances[configured] ||= configured.new
-      else
-        configured
       end
     end
 
     def self.reset!
-      @adapter_instances = nil
+      ADAPTER_MUTEX.synchronize { @adapter_instances = nil }
     end
 
     def self.apply_content_policy(data, sensitivity)

data/lib/smith/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Smith
-  VERSION = "0.7.0"
-  EXECUTION_SEMANTICS_VERSION = "3"
+  VERSION = "0.10.0"
+  EXECUTION_SEMANTICS_VERSION = "5"
 end

data/lib/smith/workflow/agent_result.rb

@@ -4,16 +4,17 @@ module Smith
   class Workflow
     # rubocop:disable Style/RedundantStructKeywordInit
     AgentResult = Struct.new(
-      :content, :input_tokens, :output_tokens, :cost, :model_used,
+      :content, :input_tokens, :output_tokens, :cost, :model_used, :provider_used,
       keyword_init: true
     ) do
-      def self.from_response(response, content, model_used: nil)
+      def self.from_response(response, content, model_used: nil, provider_used: nil)
         new(
           content: content,
           input_tokens: response.respond_to?(:input_tokens) ? response.input_tokens : nil,
           output_tokens: response.respond_to?(:output_tokens) ? response.output_tokens : nil,
           cost: nil,
-          model_used: model_used
+          model_used: model_used,
+          provider_used: provider_used
         )
       end
 

data/lib/smith/workflow/artifact_integration.rb

@@ -33,7 +33,8 @@ module Smith
         Context::Session.new(
           messages: messages,
           context_manager: manager,
-          persisted_context: @context
+          persisted_context: @context,
+          seed_message_count: @seed_message_count || 0
         )
       end
     end

data/lib/smith/workflow/composite/effects.rb

@@ -4,19 +4,32 @@ require_relative "../../types"
 require_relative "../../budget/decimal_context"
 require_relative "../message_value_normalizer"
 require_relative "../prepared_step"
+require_relative "../usage_entry"
 require_relative "payload"
 
 module Smith
   class Workflow
     module Composite
-      class Effects < Payload
+      # Length is fail-closed value validation, not logic: every key the
+      # contract admits gets a bounded value check beside the contract that
+      # admits it. Splitting the checks away from the payload they guard
+      # would trade cohesion for a metric.
+      class Effects < Payload # rubocop:disable Metrics/ClassLength
         attr_reader :total_tokens, :total_cost
 
-        USAGE_ATTRIBUTES = %w[
-          usage_id agent_name model input_tokens output_tokens cost attempt_kind recorded_at
-        ].freeze
-        TOOL_ATTRIBUTES = %w[tool captured].freeze
-        private_constant :USAGE_ATTRIBUTES, :TOOL_ATTRIBUTES
+        # Required keys are the pre-attribution UsageEntry shape, so effects
+        # produced by an older Smith (a mid-deploy branch worker or a
+        # restored checkpoint) stay valid; allowed keys are the current
+        # member set, so unknown keys still reject. The attribution members
+        # (transition, branch_key, round, attempt_id) are optional by
+        # construction.
+        USAGE_ALLOWED_ATTRIBUTES = Workflow::UsageEntry.members.map(&:to_s).freeze
+        USAGE_REQUIRED_ATTRIBUTES =
+          (USAGE_ALLOWED_ATTRIBUTES - %w[transition branch_key round attempt_id workflow]).freeze
+        TOOL_REQUIRED_ATTRIBUTES = %w[tool captured].freeze
+        TOOL_ALLOWED_ATTRIBUTES = (TOOL_REQUIRED_ATTRIBUTES + %w[tool_call_id]).freeze
+        private_constant :USAGE_ALLOWED_ATTRIBUTES, :USAGE_REQUIRED_ATTRIBUTES,
+                         :TOOL_REQUIRED_ATTRIBUTES, :TOOL_ALLOWED_ATTRIBUTES
 
         attribute :usage_entries, Types::Array
         attribute :tool_results, Types::Array
@@ -25,17 +38,12 @@ module Smith
         def initialize(attributes)
           owned = self.class.normalize_attributes(attributes)
           normalized = MessageValueNormalizer.new(owned, label: "composite effects").call
-          usage_entries = normalized.fetch("usage_entries")
-          tool_results = normalized.fetch("tool_results")
-          budget_consumed = normalized.fetch("budget_consumed")
+          usage_entries, tool_results, budget_consumed =
+            normalized.values_at("usage_entries", "tool_results", "budget_consumed")
           @total_tokens, @total_cost = validate_usage_entries!(usage_entries)
           validate_tool_results!(tool_results)
           validate_budget!(budget_consumed)
-          super(
-            usage_entries:,
-            tool_results:,
-            budget_consumed:
-          )
+          super(usage_entries:, tool_results:, budget_consumed:)
         end
 
         private
@@ -44,8 +52,9 @@ module Smith
           raise ArgumentError, "composite usage entries must be an Array" unless entries.is_a?(Array)
 
           entries.each do |entry|
-            validate_exact_keys!(entry, USAGE_ATTRIBUTES, "composite usage entry")
+            validate_bounded_keys!(entry, USAGE_REQUIRED_ATTRIBUTES, USAGE_ALLOWED_ATTRIBUTES, "composite usage entry")
             validate_usage_identity!(entry)
+            validate_usage_attribution!(entry)
             validate_usage_amount!(entry.fetch("input_tokens"), "input_tokens")
             validate_usage_amount!(entry.fetch("output_tokens"), "output_tokens")
             validate_cost!(entry.fetch("cost"))
@@ -68,23 +77,40 @@ module Smith
         end
 
         def validate_usage_identity!(entry)
-          validate_usage_id!(entry.fetch("usage_id"))
-          validate_agent_name!(entry.fetch("agent_name"))
+          validate_uuid!(entry.fetch("usage_id"), "composite usage entry usage_id")
+          # agent_name and provider are nil-allowed; any other value
+          # (false included) must be a non-empty String.
+          %w[agent_name provider].each do |key|
+            value = entry.fetch(key)
+            validate_nonempty_string!(value, "composite usage entry #{key}") unless value.nil?
+          end
           %w[model attempt_kind recorded_at].each do |key|
             validate_nonempty_string!(entry.fetch(key), "composite usage entry #{key}")
           end
         end
 
-        def validate_usage_id!(usage_id)
-          return if usage_id.is_a?(String) && PreparedStep::UUID_PATTERN.match?(usage_id)
+        # The optional attribution keys are bounded values, not just bounded
+        # keys: a present key with a wrong-typed, empty, or oversized value
+        # rejects exactly like the identity fields do. Absent keys (older
+        # producers, or nil-omitting serialization) stay valid.
+        def validate_usage_attribution!(entry)
+          %w[transition branch_key workflow].each do |key|
+            validate_bounded_string!(entry.fetch(key), "composite usage entry #{key}", 256) if entry.key?(key)
+          end
+          validate_usage_amount!(entry.fetch("round"), "round") if entry.key?("round")
+          validate_uuid!(entry.fetch("attempt_id"), "composite usage entry attempt_id") if entry.key?("attempt_id")
+        end
+
+        def validate_uuid!(value, label)
+          return if value.is_a?(String) && PreparedStep::UUID_PATTERN.match?(value)
 
-          raise ArgumentError, "composite usage entry usage_id must be a UUID"
+          raise ArgumentError, "#{label} must be a UUID"
         end
 
-        def validate_agent_name!(agent_name)
-          return if agent_name.nil?
+        def validate_bounded_string!(value, label, max_length)
+          return if value.is_a?(String) && value.length.between?(1, max_length)
 
-          validate_nonempty_string!(agent_name, "composite usage entry agent_name")
+          raise ArgumentError, "#{label} must be a bounded non-empty String"
         end
 
         def validate_nonempty_string!(value, label)
@@ -100,8 +126,7 @@ module Smith
         end
 
         def validate_cost!(cost)
-          return if cost.nil?
-          return if cost.is_a?(Numeric) && cost.finite? && cost >= 0
+          return if cost.nil? || (cost.is_a?(Numeric) && cost.finite? && cost >= 0)
 
           raise ArgumentError, "composite usage entry cost must be a finite non-negative number or nil"
         end
@@ -110,10 +135,15 @@ module Smith
           raise ArgumentError, "composite tool results must be an Array" unless entries.is_a?(Array)
 
           entries.each do |entry|
-            validate_exact_keys!(entry, TOOL_ATTRIBUTES, "composite tool result")
-            tool = entry.fetch("tool")
-            unless tool.is_a?(String) && tool.length.between?(1, 256)
-              raise ArgumentError, "composite tool result tool must be a bounded non-empty String"
+            validate_bounded_keys!(entry, TOOL_REQUIRED_ATTRIBUTES, TOOL_ALLOWED_ATTRIBUTES, "composite tool result")
+            validate_bounded_string!(entry.fetch("tool"), "composite tool result tool", 256)
+
+            # Present only for provider-batch invocations; the producer never
+            # writes a nil, so a present key must carry a real id. Provider
+            # tool-call ids are short strings; 1024 is far above any observed
+            # provider format while still bounding the payload.
+            if entry.key?("tool_call_id")
+              validate_bounded_string!(entry.fetch("tool_call_id"), "composite tool result tool_call_id", 1024)
             end
           end
         end
@@ -128,9 +158,12 @@ module Smith
           end
         end
 
-        def validate_exact_keys!(value, expected, label)
+        # Every required key present, no key outside the allowed set: older
+        # producers (missing optional keys) pass, unknown keys still reject.
+        # Passing the same set for both is an exact-keys check.
+        def validate_bounded_keys!(value, required, allowed, label)
           raise ArgumentError, "#{label} must be a Hash" unless value.is_a?(Hash)
-          return if value.keys.sort == expected.sort
+          return if (required - value.keys).empty? && (value.keys - allowed).empty?
 
           raise ArgumentError, "#{label} attributes are invalid"
         end