smith-agents 0.8.0 → 0.10.0

data/lib/smith/agent/usage_tracking.rb

@@ -2,31 +2,33 @@
 
 require_relative "completion_usage_recording"
 require_relative "usage_entry_recording"
+require_relative "usage_traces"
 
 module Smith
   class Agent
     module UsageTracking
       include CompletionUsageRecording
       include UsageEntryRecording
+      include UsageTraces
 
       private
 
-      def account_failed_attempt(error, model_reference, agent_class)
+      def account_failed_attempt(error, model_reference, agent_class, attempt_id: nil)
         return unless error.respond_to?(:input_tokens) && error.respond_to?(:output_tokens)
 
         input = error.input_tokens
         output = error.output_tokens
         return unless input.is_a?(Integer) && output.is_a?(Integer)
 
-        record_failed_usage(agent_class, model_reference, input, output, :failed_attempt)
+        record_failed_usage(agent_class, model_reference, input, output, attempt_id:)
       end
 
-      def account_completed_prefix(agent_class, model_reference, messages)
+      def account_completed_prefix(agent_class, model_reference, messages, attempt_id: nil)
         completion = Completion.from_messages(response: nil, messages: messages)
-        record_completion_usage(agent_class, completion, :partial_attempt, model_reference)
+        record_completion_usage(agent_class, completion, :partial_attempt, model_reference, attempt_id:)
       end
 
-      def record_failed_usage(agent_class, model_reference, input_tokens, output_tokens, attempt_kind)
+      def record_failed_usage(agent_class, model_reference, input_tokens, output_tokens, attempt_id: nil)
         model_reference = coerce_model_reference(model_reference)
         cost = Smith::Pricing.compute_cost(
           model: model_reference.model_id,
@@ -44,10 +46,10 @@ module Smith
         )
         Thread.current[:smith_failed_agent_results] ||= []
         Thread.current[:smith_failed_agent_results] << agent_result
-        record_usage(agent_class, agent_result, attempt_kind, model_reference)
+        record_usage(agent_class, agent_result, :failed_attempt, model_reference, attempt_id:)
       end
 
-      def snapshot_and_finalize(agent_class, completion, model_reference)
+      def snapshot_and_finalize(agent_class, completion, model_reference, attempt_id: nil)
         model_reference = coerce_model_reference(model_reference)
         agent_result = Workflow::AgentResult.new(
           content: completion.content,
@@ -59,8 +61,7 @@ module Smith
         )
         Thread.current[:smith_last_agent_result] = agent_result
         emit_token_usage(agent_result)
-        compute_agent_cost(agent_result)
-        record_completion_usage(agent_class, completion, :completed_attempt, model_reference)
+        account_completion!(agent_class, completion, model_reference, agent_result, attempt_id)
 
         agent_result.content = run_after_completion(agent_class, agent_result.content, @context)
         raise_blank_output!(agent_class, agent_result)
@@ -83,18 +84,20 @@ module Smith
         false
       end
 
-      def emit_token_usage(agent_result)
-        return unless agent_result.usage_known?
-
-        Smith::Trace.record(
-          type: :token_usage,
-          data: {
-            input_tokens: agent_result.input_tokens,
-            output_tokens: agent_result.output_tokens,
-            model: agent_result.model_used,
-            provider: agent_result.provider_used
-          }.compact
+      # Records one usage entry per provider response and settles the
+      # invocation's cost from the recorded per-response sum: that sum is
+      # what tiered catalogs bill, so it becomes agent_result.cost (which
+      # budget settlement and result surfaces read) and the recorded entries,
+      # the budget ledger, and the :cost trace all agree. The trace emits
+      # only for fully metered, fully priced invocations, so a partial
+      # figure is never presented as the invocation cost; the partial sum
+      # still settles the budget because it is what was verifiably billed.
+      def account_completion!(agent_class, completion, model_reference, agent_result, attempt_id)
+        invocation_cost, fully_priced = record_completion_usage(
+          agent_class, completion, :completed_attempt, model_reference, attempt_id:
         )
+        agent_result.cost = invocation_cost
+        emit_cost_trace(agent_result, invocation_cost) if fully_priced
       end
 
       def compute_agent_cost(agent_result)

data/lib/smith/attribution.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Smith
+  # Ambient execution attribution: an immutable, thread-local description of
+  # where execution currently is (run identity, transition, fan-out branch,
+  # optimizer round). Workflow execution scopes install it; observability
+  # consumers (traces, events, usage recording) read it, so emitted facts
+  # carry correlation without any consumer knowing about the workflow.
+  #
+  # Attribution values are opaque identifiers, never content: the trace
+  # content policy does not treat them as payload. `execution_key` defaults
+  # to the workflow's persistence key during persisted runs; hosts running
+  # non-persisted workflows can seed an outer scope explicitly:
+  #
+  #   Smith::Attribution.with(execution_key: "host-run-42") { workflow.run! }
+  #
+  # Installation inside workflow internals is a plain assignment
+  # (Attribution.install) because restoration there is owned by the
+  # surrounding ThreadContextSnapshot, which tracks the attribution thread
+  # key alongside the other per-step thread state.
+  module Attribution
+    THREAD_KEY = :smith_attribution
+
+    Context = Data.define(:execution_key, :transition, :from, :to, :branch_key, :round, :workflow) do
+      # Overlay semantics: nil overrides are ignored so an inner scope can
+      # only add or replace attribution, never blank an outer value.
+      def merge(**overrides)
+        filtered = overrides.compact
+        return self if filtered.empty?
+
+        override(**filtered)
+      end
+
+      # Replacement semantics: sets the given fields verbatim, nil included,
+      # so a scope that owns a field can reset it (a step whose transition
+      # declares no `from` must not inherit an enclosing step's `from`).
+      # Built on to_h, not Data#with, which requires Ruby 3.3 while the gem
+      # supports 3.2.
+      def override(**fields)
+        self.class.new(**to_h, **fields)
+      end
+
+      def to_fields
+        {
+          execution_key: execution_key,
+          transition: transition,
+          from: from,
+          to: to,
+          branch_key: branch_key,
+          round: round,
+          workflow: workflow
+        }.compact
+      end
+    end
+
+    EMPTY = Context.new(
+      execution_key: nil, transition: nil, from: nil, to: nil, branch_key: nil, round: nil, workflow: nil
+    )
+
+    class << self
+      def current
+        Thread.current[THREAD_KEY]
+      end
+
+      def ambient
+        current || EMPTY
+      end
+
+      # The compacted attribution fields, for merging into emitted payloads.
+      def current_fields
+        context = current
+        context ? context.to_fields : {}
+      end
+
+      # Plain installation with no restoration: callers own restoration,
+      # either through ThreadContextSnapshot (workflow internals) or an
+      # enclosing #with / #carrying block.
+      def install(context)
+        Thread.current[THREAD_KEY] = context
+      end
+
+      # Host-facing scope: overlays the ambient attribution for the block.
+      def with(**overrides, &block)
+        raise ArgumentError, "block required" unless block
+
+        swap(ambient.merge(**overrides), &block)
+      end
+
+      # Cross-thread propagation: installs a context captured on another
+      # thread (or nil, clearing any stale value on a pooled thread) for the
+      # duration of the block.
+      def carrying(context, &block)
+        raise ArgumentError, "block required" unless block
+
+        swap(context, &block)
+      end
+
+      private
+
+      # Matches the gem's scoped thread-state idiom: install and restore run
+      # interrupt-deferred, the block itself runs interruptible.
+      def swap(context, &block)
+        previous = Thread.current[THREAD_KEY]
+        Thread.handle_interrupt(Object => :never) do
+          Thread.current[THREAD_KEY] = context
+          begin
+            Thread.handle_interrupt(Object => :immediate, &block)
+          ensure
+            Thread.current[THREAD_KEY] = previous
+          end
+        end
+      end
+    end
+  end
+end

data/lib/smith/event.rb

@@ -3,9 +3,17 @@
 require "dry-struct"
 require "securerandom"
 
+require_relative "attribution"
+
 module Smith
   class Event < Dry::Struct
-    attribute(:execution_id, Types::String.default { SecureRandom.uuid })
-    attribute(:trace_id, Types::String.default { SecureRandom.uuid })
+    # Both ids default to the ambient Smith::Attribution execution key, so
+    # events emitted under one persisted run (or one host-seeded
+    # Attribution scope) share one identity a host can group by. Outside
+    # any scope, each event falls back to its own random UUID, so
+    # non-persisted, unseeded runs have no shared event identity. Callers
+    # may always pass explicit values.
+    attribute(:execution_id, Types::String.default { Smith::Attribution.ambient.execution_key || SecureRandom.uuid })
+    attribute(:trace_id, Types::String.default { Smith::Attribution.ambient.execution_key || SecureRandom.uuid })
   end
 end

data/lib/smith/events/bus.rb

@@ -18,19 +18,43 @@ module Smith
       end
     end
 
+    REGISTRY_MUTEX = Mutex.new
+    private_constant :REGISTRY_MUTEX
+
     class << self
+      # Registration-ordered snapshot of the live subscriptions. Cancelled
+      # subscriptions are detached from the registry, so this reflects only
+      # what will actually receive events.
       def subscriptions
-        @subscriptions ||= []
+        snapshot = REGISTRY_MUTEX.synchronize { registry.values.flatten }
+        snapshot.sort_by!(&:sequence_number)
       end
 
       def on(event_class, **opts, &block)
         sub = Subscription.new(event_class, handler: block, predicate: opts[:if])
-        subscriptions << sub
+        REGISTRY_MUTEX.synchronize do
+          @sequence = (@sequence || 0) + 1
+          sub.sequence_number = @sequence
+          (registry[event_class] ||= []) << sub
+        end
         sub
       end
 
+      # Removes a subscription from the registry. Called by
+      # Subscription#cancel; safe to call more than once.
+      def detach(subscription)
+        REGISTRY_MUTEX.synchronize do
+          bucket = registry[subscription.event_class]
+          next unless bucket
+
+          bucket.delete(subscription)
+          registry.delete(subscription.event_class) if bucket.empty?
+        end
+        nil
+      end
+
       def emit(event)
-        subscriptions.each { |sub| dispatch_to(sub, event) }
+        matching_subscriptions(event).each { |sub| dispatch_to(sub, event) }
       end
 
       def within
@@ -41,14 +65,48 @@ module Smith
       end
 
       def reset!
-        @subscriptions = []
+        REGISTRY_MUTEX.synchronize do
+          @registry = {}
+          @sequence = 0
+        end
       end
 
       private
 
+      def registry
+        @registry ||= {}
+      end
+
+      # Subscriptions live in per-class buckets so one emit touches only the
+      # buckets for the event's ancestors instead of scanning every
+      # subscription; `is_a?` dispatch semantics are preserved exactly
+      # because a subscription matches iff its registered class or module is
+      # among the event class's ancestors. The merged candidates are ordered
+      # by registration sequence, keeping subscription-order dispatch.
+      # Handlers run outside the registry lock so a handler may subscribe or
+      # cancel without deadlocking.
+      def matching_subscriptions(event)
+        # singleton_class.ancestors, not class.ancestors: it additionally
+        # covers modules mixed into the event instance via extend, which
+        # `is_a?` matched before the bucketed registry existed. Immediates
+        # (Integer, Symbol, Float) have no singleton class; they also cannot
+        # be extended, so their class ancestors are the complete `is_a?` set.
+        ancestors = begin
+          event.singleton_class.ancestors
+        rescue TypeError
+          event.class.ancestors
+        end
+        candidates = REGISTRY_MUTEX.synchronize do
+          ancestors.each_with_object([]) do |ancestor, found|
+            bucket = registry[ancestor]
+            found.concat(bucket) if bucket
+          end
+        end
+        candidates.sort_by!(&:sequence_number)
+      end
+
       def dispatch_to(sub, event)
         return if sub.cancelled?
-        return unless event.is_a?(sub.event_class)
         return if sub.predicate && !sub.predicate.call(event)
 
         sub.handler.call(event)

data/lib/smith/events/step_completed.rb

@@ -6,6 +6,9 @@ module Smith
       attribute :transition, Types::Strict::Symbol
       attribute :from, Types::Strict::Symbol.optional
       attribute :to, Types::Strict::Symbol
+      # The emitting workflow's class name; distinguishes nested-child steps
+      # from parent steps under the shared root execution identity.
+      attribute :workflow, Types::Strict::String.optional.default(nil)
     end
   end
 end

data/lib/smith/events/step_failed.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Smith
+  module Events
+    # Emitted from both step-failure paths (step-body failure and an
+    # unresolved transition routed to :fail), closing the success-only
+    # observation gap for failures that reach step handling. Terminal errors
+    # raised outside it (an unresolved transition with no :fail transition,
+    # transition-budget exhaustion, origin validation) still re-raise
+    # without a StepFailed. Carries bounded classification only, never raw
+    # error messages; `error_family` uses FailureRecord's taxonomy
+    # ("agent_error", "deadline_exceeded", ..., "other") and `retryable` is
+    # nil when the error does not declare retryability.
+    class StepFailed < Smith::Event
+      attribute :transition, Types::Strict::Symbol
+      attribute :from, Types::Strict::Symbol.optional
+      attribute :to, Types::Strict::Symbol.optional
+      attribute :error_class, Types::Strict::String
+      attribute :error_family, Types::Strict::String
+      attribute :retryable, Types::Strict::Bool.optional
+      # See StepCompleted#workflow.
+      attribute :workflow, Types::Strict::String.optional.default(nil)
+    end
+  end
+end

data/lib/smith/events/subscription.rb

@@ -4,6 +4,9 @@ module Smith
   module Events
     class Subscription
       attr_reader :event_class, :handler, :predicate
+      # Internal registration order, assigned by Events.on; dispatch and the
+      # subscriptions snapshot sort by it.
+      attr_accessor :sequence_number
 
       def initialize(event_class, handler:, predicate: nil)
         @event_class = event_class
@@ -12,8 +15,13 @@ module Smith
         @cancelled = false
       end
 
+      # Cancelling flags the subscription and detaches it from the registry
+      # (so it cannot leak). The flag check against an in-flight emit
+      # snapshot is best-effort: a dispatch already past the check may still
+      # deliver once after cancel returns.
       def cancel
         @cancelled = true
+        Events.detach(self)
       end
 
       def cancelled?

data/lib/smith/tool/capture.rb

@@ -54,8 +54,16 @@ module Smith
         capture_failure(e, strict, reason: :capture_block_failed)
       end
 
+      # tool_call_id is additive only when present (a provider-batch
+      # invocation is ambient), so captures from direct invocations and
+      # pre-existing persisted payloads keep their exact two-key shape.
       def append_capture(collector, captured, strict)
-        collector.call({ tool: name.to_s, captured: captured }) if strict || captured
+        return unless strict || captured
+
+        entry = { tool: name.to_s, captured: captured }
+        tool_call_id = self.class.current_invocation&.tool_call_id
+        entry[:tool_call_id] = tool_call_id if tool_call_id
+        collector.call(entry)
       rescue StandardError => e
         capture_failure(e, strict, reason: :collector_failed)
       end

data/lib/smith/tool.rb

@@ -165,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

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.8.0"
+  VERSION = "0.10.0"
   EXECUTION_SEMANTICS_VERSION = "5"
 end