smith-agents 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1fe948e343baa2573448f7a95a964729e96a71b0b2e6ef16226694400ba0fb97
-  data.tar.gz: 8f3d35e4ee6998ca41a4be0e19dcce0b5e843b44c0f28167aff3d5326d1be573
+  metadata.gz: 06665b52b660baf1f846ebd104caec677044595bd4aaf71ecf6ac3120e18d478
+  data.tar.gz: '09dd67e047e0f2a3dc6afd0f6b320ab7d5b7f2f23460ddae9576860e7b2e1329'
 SHA512:
-  metadata.gz: 85bc7336ef0cb273979c4c7df1a4c0c724eb74cb34c4b49c1b23768e9454c700a1f33827ac9a1b33ff9680efd55b302b282db0fc553c5e20c52b4d13970044fa
-  data.tar.gz: afe1281c6ef7967292c1c43b7370ca5ab3795abcc98722aa8e10c03266347dcd2411d9c44878f1c0d4aa41df5f88ffd636d46084ff996f2008f60baa650ce5fc
+  metadata.gz: 76771bcb4d58d45f110b16a590579a34f698f1e9e2b75cca7806a5c5864f50c8209afc4a258a587069c6dd97f6ae87c1d0a62d434afd4b415f04e199561e79a6
+  data.tar.gz: 5160511ae311634881c774fa8040d3b69f93171e20e76aca595821c9eb7a767c76d0165ffe562190b16f624a4ba2e3e272822b3a1cf6b852ae2d2af7d7521994

data/CHANGELOG.md

@@ -4,6 +4,236 @@ All notable changes to Smith are documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Smith is pre-1.0 and under active development; expect occasional contract tightening between minor versions until 1.0.
 
+## [0.10.0] - 2026-08-24
+
+### Added
+
+- Last-serial-agent-execution attribution. A deterministic (`compute`) step can
+  now read the model and provider that actually served the most recent serial
+  `execute :agent` step via `DeterministicStep#last_agent_model` /
+  `#last_agent_provider` (symmetric with `#last_output`, which returns that
+  step's content). The value is the resolved model/provider after fallback
+  resolution, so a step that failed its primary and completed on a
+  `fallback_models` entry reports the model that actually ran, never the
+  configured primary. It is durable lifecycle state (persisted in `to_state` as
+  `last_agent_execution`, restored across crash/resume), not a trace scrape, and
+  is `nil` until a serial agent step runs. Backward compatible: pre-upgrade
+  states have no `last_agent_execution` key and restore to `nil`; old readers
+  slice off the unknown key.
+
+### Fixed
+
+- Structured agent outputs recorded as session messages (Hash or Array
+  content) are now serialized to JSON at the RubyLLM provider boundary when
+  replayed to a later agent step. RubyLLM treats a Hash message content as
+  attachments and opens each value as a file, so replaying a prior structured
+  output to the next agent in a workflow session raised `Errno::ENOENT`. The
+  session store is unaffected: `last_output` and persisted `session_messages`
+  keep the raw structured value; only the provider-facing copy is serialized.
+
+## [0.9.0] - 2026-08-03
+
+### Upgrade notes
+
+- Rollback after running fan-out branches under this version is a one-way
+  door for those runs: composite branch effects written with attribution
+  values (usage entries) or batch-correlated `tool_call_id` capture entries
+  fail an older gem's exact-key validation at reduction or recovery.
+  Drain in-flight composite runs before rolling the gem back; plain
+  checkpoint payloads are unaffected (restored pre-attribution documents
+  re-serialize byte-identically, and old readers slice off unknown keys).
+- Hosts with a configured trace adapter see new output on upgrade without
+  any host change: one `:provider_call` line per provider attempt, one
+  `:cost` line per priced completed invocation, failed `:transition` lines
+  marked `outcome: :failed`, and ambient attribution keys (including
+  `execution_key`, the Smith persistence key) merged into every payload.
+  Identifier-only, but plan for the volume and shape change, especially
+  with `Smith::Trace::Logger` in production.
+- Hosts with a `trace_fields` allowlist for `:transition` must add
+  `:outcome` (and the error keys they want) or failed transitions render
+  indistinguishable from successes under the allowlist.
+- `Smith::Trace::Memory` is now bounded (default 10,000 entries, silent
+  drop with `dropped_count`); previously it accumulated without limit.
+
+### Added
+
+- Add `Smith::Attribution`, an immutable thread-local execution attribution
+  context (`execution_key`, `transition`, `from`, `to`, `branch_key`,
+  `round`). Workflow execution installs it per step (the `execution_key`
+  defaults to the persistence key of a persisted run), fan-out carries it
+  into branch threads and overlays the branch key, and evaluator-optimizer
+  rounds overlay the round index. Hosts can seed an outer scope with
+  `Smith::Attribution.with(execution_key: ...)` around non-persisted runs.
+  Restoration inside workflow execution rides `ThreadContextSnapshot`, which
+  now tracks the attribution thread key. Scope overlays are nil-ignoring
+  (`Context#merge`), but the per-step facts (`transition`, `from`, `to`)
+  are replaced verbatim, nil included (`Context#override`): a nested
+  child's `from`-less transition never inherits the parent step's `from`,
+  and the failed `:transition` trace keeps `from`/`to` present even when
+  nil for the same reason.
+- Merge ambient attribution fields into every `Smith::Trace.record` payload.
+  Attribution keys are identifiers, not content: caller-supplied keys win on
+  conflict, the content policy is unaffected, and a configured
+  `trace_fields` allowlist stays authoritative (add attribution keys to an
+  allowlist to receive them). Disable with `Smith.config.trace_attribution =
+  false` (default true).
+- Bound `Smith::Trace::Memory` (default 10,000 entries) with a
+  `dropped_count` reader and a `snapshot` method for readers racing
+  concurrent recording.
+- Tag `Workflow::UsageEntry` with the ambient attribution at recording time:
+  new optional members `transition`, `branch_key`, `round`, and `attempt_id`.
+  All four are nil on entries restored from checkpoints written by earlier
+  Smith versions and are omitted from serialization when nil, so restored
+  pre-attribution documents re-serialize byte-identically (hosts that digest
+  whole persisted documents in exact-mutation proofs depend on this). A
+  rolled-back gem drops the new keys from plain checkpoint payloads
+  (`from_h` slices to known members). Composite branch effects are the
+  exception: effects written by this version from a fan-out branch carry
+  real attribution values, and an older gem's exact-key effects validation
+  rejects them, so see the upgrade notes below before rolling back.
+  `recorded_at` now carries microsecond precision (`iso8601(6)`) on new
+  entries. Recording symbolizes `transition`/`branch_key` Strings exactly
+  as `from_h` does on restore, so a host seeding String attribution through
+  `Smith::Attribution.with` gets entries equal to their restored form.
+- Measure each provider attempt with a monotonic clock around the whole chat
+  completion (including any provider tool loop) and emit one
+  `:provider_call` trace per attempt (success or failure) carrying `model`,
+  `provider`, `duration_ms`, `attempt_id`, `attempt_index`, and `outcome`.
+  Every usage entry the attempt produced shares its `attempt_id` (an attempt
+  with an N-round tool loop records N entries): join there for the attempt's
+  single duration, never sum across entries. Gate with
+  `Smith.config.trace_provider_calls` (default true). `ProviderAttempt`
+  gains optional `attempt_id` and `duration_ms`.
+- Add a public read-only `Workflow#usage_entries` (frozen copy under the
+  recording mutex) so hosts can diff usage across a step boundary without a
+  full `to_state` serialization; `to_state` and `snapshot_usage_entries` now
+  read the ledger under the same mutex, so a state written mid-fan-out never
+  captures a torn array.
+- Thread real correlation identity through events: `Smith::Event#execution_id`
+  and `#trace_id` default to the ambient attribution execution key (the
+  persistence key during persisted runs) instead of a fresh random UUID per
+  event; the random fallback remains for events built outside any execution
+  scope. The `:tool_call` trace gains a nullable `tool_call_id` when the
+  invocation came from a provider batch (the tool-results capture entry
+  gains the same key under a later bullet in this release; composite
+  effects accept the extended shape with bounded value validation).
+
+- Emit from the step-failure paths, closing the success-only observation
+  gap: both `handle_step_failure` and the unresolved-transition handler now
+  record a `:transition` trace with `outcome: :failed` plus bounded
+  classification (`error_class`, `error_family` from FailureRecord's
+  taxonomy, `retryable`) and emit a new `Smith::Events::StepFailed` event.
+  Raw error messages never ride either; an emission failure is logged and
+  can never mask the original step error. The marker key is `outcome`
+  because `result` is a reserved content key in the trace pipeline. An
+  unresolved transition with no `:fail` transition still re-raises without
+  emitting: that path was never treated as a step. The unresolved handler
+  runs outside any step context, so it seeds the run identity explicitly;
+  both failure paths stamp persisted-run events with the persistence key.
+  Emission is terminal-per-step: a step that retries internally and then
+  succeeds emits only its `StepCompleted`; intermediate step-body retry
+  attempts stay dark at the step layer (provider-level failures remain
+  visible as `:provider_call` failure traces). `StepFailed` handlers run
+  outside the step snapshot's interrupt-masked region (emission is staged
+  in the failure rescue and flushed after the mask closes), interruptible
+  exactly like `StepCompleted` handlers. A step body that surfaces Smith's
+  own `UnresolvedTransitionError` emits exactly one `StepFailed` under the
+  real step identity; the unresolved handler recognizes the already-emitted
+  error instead of emitting a second event under the requested (never
+  executed) name.
+- Emit the long-advertised `:cost` trace: one per completed agent
+  invocation, whose value is the sum of that invocation's per-response
+  usage-entry costs. Summing per response is what tiered catalogs actually
+  bill; pricing the aggregate token totals as one call would resolve the
+  wrong tier for multi-response tool loops. Emitted only for fully metered,
+  fully priced invocations (a partially priced or partially metered
+  invocation emits nothing rather than presenting an incomplete figure);
+  gated by the existing `trace_cost` setting (the per-type gates live in
+  the built-in adapters; a custom adapter receives every type). `:cost`
+  traces are not a spend total: billed failed and partial attempts appear
+  only in usage entries. The same per-response sum now becomes
+  `agent_result.cost`, so budget settlement, result surfaces, recorded
+  entries, and the trace all agree on one invocation cost.
+- The OpenTelemetry adapter now creates retroactive spans with real
+  durations (span start backdated by `:tool_call` seconds or
+  `:provider_call` milliseconds; instant spans otherwise), preserves
+  numeric attribute types instead of stringifying everything, and uses only
+  the documented opentelemetry-api surface (`Tracer#start_span` with
+  `start_timestamp`, `Span#finish` with `end_timestamp`).
+
+- Add a `workflow` discriminator to the ambient attribution, every trace
+  payload, usage entries, and the `StepCompleted`/`StepFailed` events: the
+  emitting workflow's class name ("anonymous" when unnamed), so
+  nested-child graph facts are distinguishable from parent facts under the
+  shared root execution identity. Nil-omitted from serialized entries like
+  the other attribution members.
+- Every provider attempt now emits its `:provider_call` trace: `outcome` is
+  `:success`, `:failure` (provider failure, fallback may continue), or
+  `:aborted` (a non-provider error that re-raises), so prefix-accounted
+  usage entries always have their attempt join target.
+- The tool-results capture entry gains `tool_call_id` when the invocation
+  came from a provider batch (omitted otherwise, so direct-invocation and
+  pre-existing payloads keep their exact two-key shape); composite effects
+  accept the extended shape while still rejecting unknown keys.
+- `StepFailed` handlers now run outside the step snapshot's
+  interrupt-masked region: emission is staged in the failure rescue and
+  flushed after the mask closes with explicitly seeded run identity, so a
+  slow host handler can no longer make the workflow thread unkillable and
+  handlers match `StepCompleted`'s interruptibility.
+
+### Fixed
+
+- A user-declared `:fail` transition no longer inherits the early order
+  position of the auto-generated placeholder created by `state :failed`:
+  redeclaring a generated transition takes a fresh declaration position, so
+  it can no longer shadow a same-origin primary transition at run time.
+  Genuine user redefinitions keep their original position, and subclasses
+  inherit the bookkeeping.
+- Budget cost settlement now consumes the per-response priced sum instead
+  of pricing the invocation's aggregate token totals. Under linear pricing
+  the figures are identical; under tiered pricing the aggregate resolved
+  the wrong tier (or missed every tier and settled zero), so a
+  cost-budgeted workflow could keep spending after its real billed cost
+  exceeded the budget.
+
+### Removed
+
+- Remove the never-read `trace_retention` and `trace_tenant_isolation`
+  settings. Both were silent no-ops since introduction; reading or writing
+  them now raises, so a host relying on the illusion fails loudly instead
+  of silently.
+
+### Changed
+
+- Workflow step failure is now observable: subscribers to the events bus
+  receive `StepFailed` where previously failures emitted nothing (the
+  success-only scope is gone), and trace consumers see failed `:transition`
+  payloads distinguished by `outcome: :failed`.
+- `Workflow::Composite::Effects` validates usage-entry keys as
+  required-plus-allowed instead of exact: entries from an older producer
+  (missing the optional attribution keys) stay valid, current entries with
+  attribution pass, and unknown keys still reject. The optional keys are
+  bounded values, not just bounded keys: `transition`, `branch_key`, and
+  `workflow` must be non-empty Strings up to 256 characters, `round` a
+  non-negative Integer, and `attempt_id` a UUID when present. Tool results
+  accept the extended capture shape: `tool_call_id`, when present, must be
+  a non-empty String up to 1024 characters (`tool` keeps its exact prior
+  validation).
+
+
+- `Smith::Events` subscriptions now live in per-class buckets guarded by a
+  mutex: emit touches only the buckets for the event's ancestors instead of
+  scanning every subscription, dispatch order remains registration order,
+  and `is_a?` matching semantics are unchanged (instance-extended modules
+  dispatch through the singleton class; immediate values, which have no
+  singleton class and cannot be extended, dispatch through their class
+  ancestors). `Subscription#cancel` now
+  detaches from the registry, so cancelled subscriptions (including
+  `Events.within` scopes) no longer leak. Handlers run outside the registry
+  lock, so a handler may subscribe or cancel without deadlocking.
+- `Smith::Trace::Memory#record` and `#clear!` are mutex-guarded and safe
+  under parallel fan-out branches.
+
 ## [0.8.0] - 2026-07-25
 
 ### Added

data/docs/CONFIGURATION.md

@@ -83,8 +83,8 @@ Smith.configure do |config|
     tool_call: %i[tool duration]
   }
   config.trace_content = false
-  config.trace_retention = 86_400
-  config.trace_tenant_isolation = false
+  config.trace_provider_calls = true
+  config.trace_attribution = true
 
   config.pricing = {
     %w[openai gpt-4.1-nano] => {
@@ -115,11 +115,11 @@ observes a provider but finds only a model-only rate, it raises
 | `trace_transitions` | Emit transition traces | Usually leave on |
 | `trace_tool_calls` | Emit tool call traces | Usually leave on |
 | `trace_token_usage` | Emit usage traces | Useful for budget visibility |
-| `trace_cost` | Emit cost traces | Useful once pricing is configured |
+| `trace_provider_calls` | Emit one timed `:provider_call` trace per provider attempt | Usually leave on |
+| `trace_cost` | Emit one `:cost` trace per completed agent invocation | Emits only once pricing is configured |
 | `trace_fields` | Allowlist structural trace fields | Use when you want tighter trace output |
 | `trace_content` | Whether content appears in traces | Leave `false` first |
-| `trace_retention` | Trace retention policy hook | Useful when traces leave memory |
-| `trace_tenant_isolation` | Trace multi-tenant isolation flag | Enable in multi-tenant systems |
+| `trace_attribution` | Merge ambient execution attribution into trace payloads | Usually leave on |
 | `pricing` | Best-known model-call cost catalog | Add once you care about `total_cost` |
 | `logger` | Smith's runtime logger | Usually the first setting to add |
 | `persistence_adapter` | Adapter for durable workflow state | `:redis`, `:rails_cache`, `:active_record`, `:memory`, or a custom object |

data/lib/smith/agent/completion_usage_recording.rb

@@ -5,9 +5,18 @@ module Smith
     module CompletionUsageRecording
       private
 
-      def record_completion_usage(agent_class, completion, attempt_kind, model_reference)
+      # Returns [invocation_cost, fully_priced]. The cost is the sum of the
+      # recorded entries' costs (nil when nothing was priced): per-response
+      # pricing is what tiered catalogs bill, so the invocation cost comes
+      # from this sum, never from pricing the aggregate token totals (which
+      # would resolve the wrong tier for multi-response tool loops).
+      # fully_priced is true only when every provider response carried usage
+      # and every usage priced; a partial sum is still returned (it is what
+      # was verifiably billed) but callers must not present it as the
+      # complete invocation cost.
+      def record_completion_usage(agent_class, completion, attempt_kind, model_reference, attempt_id: nil)
         model_reference = coerce_model_reference(model_reference)
-        completion.provider_usages.each do |usage|
+        costs = completion.provider_usages.map do |usage|
           result = Workflow::AgentResult.new(
             content: nil,
             input_tokens: usage.input_tokens,
@@ -17,8 +26,17 @@ module Smith
             provider_used: model_reference.provider
           )
           compute_agent_cost(result)
-          record_usage(agent_class, result, attempt_kind, model_reference)
+          record_usage(agent_class, result, attempt_kind, model_reference, attempt_id:)
+          result.cost
         end
+        summarize_invocation_costs(costs, completion)
+      end
+
+      def summarize_invocation_costs(costs, completion)
+        priced = costs.compact
+        invocation_cost = priced.empty? ? nil : priced.sum
+        fully_priced = completion.usage_complete && !costs.empty? && priced.length == costs.length
+        [invocation_cost, fully_priced]
       end
     end
   end

data/lib/smith/agent/invocation_preparation.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 module Smith
   class Agent
     module InvocationPreparation
@@ -82,9 +84,31 @@ module Smith
                      else
                        message
                      end
+        attributes = provider_safe_message(attributes) if attributes.is_a?(Hash)
         chat.add_message(attributes)
       end
 
+      # A structured agent output recorded as a session message (StepCompletion#append_accepted_output)
+      # carries a Hash/Array content. RubyLLM's Message#normalize_content treats a Hash content as
+      # { text:, ...attachments } and opens each value as a file, so replaying a prior structured
+      # output to the next agent in a workflow session raises Errno::ENOENT. Serialize non-string
+      # content to JSON so the provider sees the prior output as text; the session store keeps the raw
+      # value (last_output stays structured), only this provider-facing copy is serialized. Genuine
+      # multimodal attachments are supplied through the provider's own with: mechanism, never as a bare
+      # Hash message content in a workflow session.
+      def provider_safe_message(attributes)
+        content = attributes[:content]
+        return attributes if content.nil? || content.is_a?(String)
+
+        attributes.merge(content: json_message_content(content))
+      end
+
+      def json_message_content(content)
+        JSON.generate(content)
+      rescue StandardError
+        content.to_s
+      end
+
       def message_role(message)
         message_attribute(message, :role)&.to_sym
       end

data/lib/smith/agent/lifecycle.rb

@@ -20,8 +20,10 @@ module Smith
 
       def invoke_agent(agent_class, prepared_input, output_schema: agent_class.output_schema)
         check_deadline!
-        completion, model_used = complete_with_provider(agent_class, prepared_input, output_schema:)
-        snapshot_and_finalize(agent_class, completion, model_used)
+        attempt = complete_with_provider(agent_class, prepared_input, output_schema:)
+        snapshot_and_finalize(
+          agent_class, attempt.completion, attempt.model_reference, attempt_id: attempt.attempt_id
+        )
       end
     end
   end

data/lib/smith/agent/provider_attempt.rb

@@ -11,13 +11,19 @@ module Smith
       attribute :completion, Types::Any.optional
       attribute :model_reference, Types.Instance(ModelReference)
       attribute :error, Types.Instance(StandardError).optional
+      # One attempt = one chat completion (including any provider tool loop).
+      # `attempt_id` joins the attempt's usage entries to its single measured
+      # duration; `duration_ms` is nil when the attempt failed before the
+      # completion call started.
+      attribute :attempt_id, Types::String.optional.default(nil)
+      attribute :duration_ms, Types::Integer.optional.default(nil)
 
-      def self.success(completion:, model_reference:)
-        new(completion:, model_reference:, error: nil)
+      def self.success(completion:, model_reference:, attempt_id: nil, duration_ms: nil)
+        new(completion:, model_reference:, error: nil, attempt_id:, duration_ms:)
       end
 
-      def self.failure(error:, model_reference:)
-        new(completion: nil, model_reference:, error:)
+      def self.failure(error:, model_reference:, attempt_id: nil, duration_ms: nil)
+        new(completion: nil, model_reference:, error:, attempt_id:, duration_ms:)
       end
 
       def success?

data/lib/smith/agent/provider_call_timing.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Smith
+  class Agent
+    # Monotonic timing and trace emission for one provider attempt: the
+    # attempt's single measured duration wraps the whole chat completion
+    # (including any provider-side tool loop). Per-network-round timing
+    # belongs to the host's RubyLLM notification subscriptions, not Smith.
+    module ProviderCallTiming
+      class Timer
+        def self.start
+          new
+        end
+
+        def initialize
+          @started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          @stopped_at = nil
+        end
+
+        # Idempotent: the first stop wins, so a rescue-path stop after a
+        # success-path stop cannot stretch the measurement.
+        def stop
+          @stopped_at ||= Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          self
+        end
+
+        def elapsed_ms
+          ending = @stopped_at || Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          ((ending - @started_at) * 1000).round
+        end
+      end
+
+      private
+
+      # One `:provider_call` trace per attempt: success, provider failure, or
+      # aborted (a non-provider error that re-raises). Usage entries from the
+      # same attempt share its attempt_id; join there instead of summing
+      # durations across entries. duration_ms is present only when the timed
+      # provider call actually started: a failure before dispatch (model
+      # resolution, chat construction) emits its attempt without a duration.
+      def record_provider_call_trace(attempt, attempt_index, aborted: false)
+        Smith::Trace.record(
+          type: :provider_call,
+          data: {
+            model: attempt.model_reference.model_id,
+            provider: attempt.model_reference.provider,
+            duration_ms: attempt.duration_ms,
+            attempt_id: attempt.attempt_id,
+            attempt_index: attempt_index,
+            outcome: provider_call_outcome(attempt, aborted)
+          }.compact
+        )
+      end
+
+      def provider_call_outcome(attempt, aborted)
+        return :aborted if aborted
+        return :success if attempt.success?
+
+        :failure
+      end
+
+      # Aborted (non-provider) attempts emit a :provider_call too, so the
+      # prefix-accounted usage entries stamped with this attempt_id always
+      # have their join target; the error then propagates unchanged.
+      def failed_provider_attempt(error, observed_reference, attempt_id, timer, attempt_index)
+        attempt = ProviderAttempt.failure(
+          error: error, model_reference: observed_reference, attempt_id:, duration_ms: timer&.elapsed_ms
+        )
+        record_provider_call_trace(attempt, attempt_index, aborted: !provider_failure?(error))
+        attempt
+      end
+    end
+  end
+end

data/lib/smith/agent/provider_completion.rb

@@ -3,6 +3,7 @@
 require_relative "provider_failure_handling"
 require_relative "invocation_preparation"
 require_relative "provider_attempt"
+require_relative "provider_call_timing"
 require_relative "provider_candidate_sequence"
 
 module Smith
@@ -10,6 +11,7 @@ module Smith
     module ProviderCompletion
       include ProviderFailureHandling
       include InvocationPreparation
+      include ProviderCallTiming
 
       private
 
@@ -17,13 +19,14 @@ module Smith
         candidates = ProviderCandidateSequence.new(build_model_chain(agent_class))
         candidates.each do |model_reference, index|
           check_deadline! if index.positive?
-          attempt = attempt_model(agent_class, prepared_input, model_reference, output_schema:)
-          return [attempt.completion, attempt.model_reference] if attempt.success?
+          attempt = attempt_model(agent_class, prepared_input, model_reference, output_schema:, attempt_index: index)
+          return attempt if attempt.success?
 
           candidates.suppress(account_failed_provider(attempt, model_reference))
           handle_provider_failure!(
             attempt.error, attempt.model_reference, agent_class,
-            fallback_available: candidates.fallback_available?
+            fallback_available: candidates.fallback_available?,
+            attempt_id: attempt.attempt_id
           )
         end
 
@@ -79,20 +82,35 @@ module Smith
         raise Smith::AgentError, "invalid model block result for #{agent_class}: #{e.message}"
       end
 
-      def attempt_model(agent_class, prepared_input, model_reference, output_schema:)
+      # rubocop:disable Metrics/AbcSize -- one provider attempt is a single
+      # cohesive lifecycle (identity, prepared chat, observed model, timed
+      # completion, prefix accounting on failure); splitting it would scatter
+      # the rescue-path accounting away from what it accounts for.
+      def attempt_model(agent_class, prepared_input, model_reference, output_schema:, attempt_index:)
+        attempt_id = SecureRandom.uuid
         chat = prepared_attempt_chat(agent_class, prepared_input, model_reference, output_schema:)
         message_count = chat_message_count(chat)
         observed_reference = observed_model_reference(chat, fallback: model_reference)
-        completion = Completion.from_messages(response: chat.complete, messages: new_chat_messages(chat, message_count))
-
-        ProviderAttempt.success(completion:, model_reference: observed_reference)
+        timer = ProviderCallTiming::Timer.start
+        response = chat.complete
+        timer.stop
+        completion = Completion.from_messages(response: response, messages: new_chat_messages(chat, message_count))
+
+        attempt = ProviderAttempt.success(
+          completion:, model_reference: observed_reference, attempt_id:, duration_ms: timer.elapsed_ms
+        )
+        record_provider_call_trace(attempt, attempt_index)
+        attempt
       rescue StandardError => e
+        timer&.stop
         observed_reference ||= observed_model_reference(chat, fallback: model_reference)
-        account_completed_prefix(agent_class, observed_reference, new_chat_messages(chat, message_count))
+        account_completed_prefix(agent_class, observed_reference, new_chat_messages(chat, message_count), attempt_id:)
+        attempt = failed_provider_attempt(e, observed_reference, attempt_id, timer, attempt_index)
         raise unless provider_failure?(e)
 
-        ProviderAttempt.failure(error: e, model_reference: observed_reference)
+        attempt
       end
+      # rubocop:enable Metrics/AbcSize
 
       def observed_model_reference(chat, fallback:)
         model = observable_model(chat)

data/lib/smith/agent/provider_failure_handling.rb

@@ -21,8 +21,8 @@ module Smith
 
       private
 
-      def handle_provider_failure!(error, model_reference, agent_class, fallback_available:)
-        account_failed_attempt(error, model_reference, agent_class)
+      def handle_provider_failure!(error, model_reference, agent_class, fallback_available:, attempt_id: nil)
+        account_failed_attempt(error, model_reference, agent_class, attempt_id:)
         if completed_tool_calls?
           raise Smith::ToolOutcomeUncertain.new(
             "provider failed after tool execution began; retry or fallback could replay an uncertain outcome"

data/lib/smith/agent/usage_entry_recording.rb

@@ -5,15 +5,22 @@ module Smith
     module UsageEntryRecording
       private
 
-      def record_usage(agent_class, agent_result, attempt_kind, model_reference)
+      def record_usage(agent_class, agent_result, attempt_kind, model_reference, attempt_id: nil)
         return unless agent_result.usage_known?
 
         model_reference = coerce_model_reference(model_reference)
-        entry = build_usage_entry(agent_class, agent_result, attempt_kind, model_reference)
+        entry = build_usage_entry(agent_class, agent_result, attempt_kind, model_reference, attempt_id:)
         accumulate_usage(agent_result, entry)
       end
 
-      def build_usage_entry(agent_class, agent_result, attempt_kind, model_reference)
+      # Attribution (transition, branch key, optimizer round) is read from the
+      # ambient context of the recording thread, which is the thread that ran
+      # the provider call: a fan-out branch records under its own overlay.
+      # transition and branch_key are recorded as Symbols even when a host
+      # seeded Strings through Attribution.with, because from_h symbolizes
+      # them on restore: recording the same way keeps a restored entry equal
+      # to the recorded one.
+      def build_usage_entry(agent_class, agent_result, attempt_kind, model_reference, attempt_id: nil)
         Workflow::UsageEntry.new(
           usage_id: SecureRandom.uuid,
           agent_name: agent_class.register_as,
@@ -23,10 +30,26 @@ module Smith
           output_tokens: agent_result.output_tokens,
           cost: agent_result.cost,
           attempt_kind: attempt_kind,
-          recorded_at: Time.now.utc.iso8601
+          recorded_at: Time.now.utc.iso8601(6),
+          attempt_id: attempt_id,
+          **ambient_attribution_fields
         )
       end
 
+      def ambient_attribution_fields
+        attribution = Smith::Attribution.ambient
+        {
+          transition: symbolized_attribution(attribution.transition),
+          branch_key: symbolized_attribution(attribution.branch_key),
+          round: attribution.round,
+          workflow: attribution.workflow
+        }
+      end
+
+      def symbolized_attribution(value)
+        value.is_a?(String) ? value.to_sym : value
+      end
+
       def accumulate_usage(agent_result, entry)
         @usage_mutex.synchronize do
           @total_tokens = (@total_tokens || 0) + agent_result.input_tokens + agent_result.output_tokens

data/lib/smith/agent/usage_traces.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Smith
+  class Agent
+    # Trace emission for a completed agent invocation's usage facts, kept
+    # apart from the accounting itself (UsageTracking) so recording rows and
+    # emitting observability stay separate concerns.
+    module UsageTraces
+      private
+
+      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
+        )
+      end
+
+      # One :cost trace per completed agent invocation. The cost is the sum
+      # of the invocation's per-response entry costs (what tiered catalogs
+      # actually bill), never the aggregate token totals priced as one call.
+      # Token counts remain the invocation aggregates. Billed failed and
+      # partial attempts appear only in usage entries, so summing :cost
+      # traces is not a spend total. Unpriced usage emits nothing, and the
+      # caller gates out partially metered or partially priced invocations
+      # so an incomplete figure is never presented as the invocation cost.
+      def emit_cost_trace(agent_result, invocation_cost)
+        return if invocation_cost.nil?
+
+        Smith::Trace.record(
+          type: :cost,
+          data: {
+            cost: invocation_cost,
+            model: agent_result.model_used,
+            provider: agent_result.provider_used,
+            input_tokens: agent_result.input_tokens,
+            output_tokens: agent_result.output_tokens
+          }.compact
+        )
+      end
+    end
+  end
+end