smith-agents 0.8.0 → 0.10.0

data/lib/smith/workflow/usage_entry.rb

@@ -2,9 +2,24 @@
 
 module Smith
   class Workflow
-    # One row per agent provider call. `usage_id` is a UUID generated at
-    # recording time and stable across persist/restore so hosts can use it as an
-    # idempotency anchor.
+    # One row per provider RESPONSE within an agent provider attempt.
+    # `usage_id` is a UUID generated at recording time and stable across
+    # persist/restore so hosts can use it as an idempotency anchor.
+    #
+    # `transition`, `branch_key`, `round`, and `workflow` come from the
+    # ambient Smith::Attribution at recording time, so hosts can attribute
+    # usage to the exact step, fan-out branch, optimizer round, and (for
+    # nested workflows) the exact graph that spent it.
+    # `attempt_id` is shared by every entry the same provider attempt
+    # produced (an attempt with an N-round tool loop records N entries):
+    # join on it against the `:provider_call` trace event for the attempt's
+    # single measured duration; never sum a duration across entries. Every
+    # attempt emits its `:provider_call` (an attempt aborted by a
+    # non-provider error emits with `outcome: :aborted` before re-raising),
+    # so prefix-accounted entries always have their join target.
+    # All optional members are nil on entries restored from checkpoints written by
+    # earlier Smith versions, and nil attribution members are omitted from
+    # serialization so those documents re-serialize byte-identically.
     # rubocop:disable Style/RedundantStructKeywordInit
     UsageEntry = Struct.new(
       :usage_id,
@@ -16,6 +31,11 @@ module Smith
       :cost,
       :attempt_kind,
       :recorded_at,
+      :transition,
+      :branch_key,
+      :round,
+      :attempt_id,
+      :workflow,
       keyword_init: true
     ) do
       def initialize(**attributes)
@@ -26,10 +46,18 @@ module Smith
         freeze
       end
 
+      # Serialization is additive only when present: nil attribution members
+      # are omitted so an entry restored from a pre-attribution checkpoint
+      # re-serializes byte-identically. Hosts that digest whole persisted
+      # documents (exact-mutation proofs) depend on this stability.
+      def to_h
+        super.reject { |key, value| value.nil? && %i[transition branch_key round attempt_id workflow].include?(key) }
+      end
+
       def self.from_h(hash)
         sym = hash.transform_keys(&:to_sym)
         filtered = sym.slice(*members)
-        %i[agent_name provider attempt_kind].each do |attribute|
+        %i[agent_name provider attempt_kind transition branch_key].each do |attribute|
           filtered[attribute] = filtered[attribute].to_sym if filtered[attribute].is_a?(String)
         end
         new(**filtered)

data/lib/smith/workflow.rb

@@ -58,6 +58,14 @@ module Smith
       @usage_entries = []
       @usage_mutex = Mutex.new
       @last_output = nil
+      # Durable attribution of the most recent serial `execute :agent` step:
+      # { model:, provider: } of the model that actually served it (post
+      # fallback resolution), exposed to the following deterministic step as
+      # `last_agent_model` / `last_agent_provider`. `@pending_agent_execution`
+      # is the transient per-step carrier from `execute_serial_step` to
+      # `complete_step`; it is never persisted.
+      @last_agent_execution = nil
+      @pending_agent_execution = nil
       @last_failed_step = nil
       # Optimistic-locking version. Incremented on each persist!; restored
       # from the persisted payload. Adapters that support store_versioned
@@ -157,6 +165,18 @@ module Smith
       end
     end
 
+    # Public, read-only view of the per-provider-call usage ledger, so hosts
+    # can diff usage across a step boundary without paying a full to_state
+    # serialization. The entries themselves are frozen; the returned array is
+    # a frozen copy taken under the recording mutex. Tolerates allocated but
+    # unrestored instances (no mutex yet), which have no entries.
+    def usage_entries
+      mutex = @usage_mutex
+      return [].freeze unless mutex
+
+      mutex.synchronize { @usage_entries.dup.freeze }
+    end
+
     private
 
     def initial_persist_auto_seed
@@ -189,6 +209,10 @@ module Smith
         # matches `RunResult#output`'s `.compact.first` semantics).
         @last_failed_step = nil
         @last_output = step_result[:output] if step_result.key?(:output) && !step_result[:output].nil?
+        # Capture serial agent attribution only on steps that carried it (an
+        # `execute :agent` step); deterministic steps have no :model key, so
+        # the last agent execution persists across intervening compute steps.
+        @last_agent_execution = { model: step_result[:model], provider: step_result[:provider] } if step_result.key?(:model)
       end
     end
 
@@ -340,7 +364,8 @@ module Smith
     # Same rule applies to nested-workflow rollup (see
     # `nested_execution.rb`).
     def snapshot_usage_entries
-      @usage_entries.map { |entry| Workflow::UsageEntry.from_h(snapshot_value(entry.to_h)) }
+      entries = @usage_mutex.synchronize { @usage_entries.dup }
+      entries.map { |entry| Workflow::UsageEntry.from_h(snapshot_value(entry.to_h)) }
     end
 
     def tool_result_collector

data/lib/smith.rb

@@ -40,11 +40,15 @@ module Smith
   setting :trace_transitions, default: true
   setting :trace_tool_calls, default: true
   setting :trace_token_usage, default: true
+  setting :trace_provider_calls, default: true
   setting :trace_cost, default: true
   setting :trace_fields
   setting :trace_content, default: false
-  setting :trace_retention
-  setting :trace_tenant_isolation, default: false
+  # Merge the ambient Smith::Attribution fields (execution_key, transition,
+  # branch_key, round, ...) into every trace payload. Attribution keys are
+  # identifiers, not content; they still pass through any configured
+  # trace_fields allowlist, and caller-supplied keys win on conflict.
+  setting :trace_attribution, default: true
 
   # Pricing (§4.5 — model-call cost computation)
   setting :pricing, default: nil
@@ -187,6 +191,7 @@ require_relative "smith/events"
 require_relative "smith/events/subscription"
 require_relative "smith/events/bus"
 require_relative "smith/events/step_completed"
+require_relative "smith/events/step_failed"
 
 # Budget (depends on Errors)
 require_relative "smith/budget"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smith-agents
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Samuel Ralak
@@ -162,6 +162,7 @@ files:
 - lib/smith/agent/lifecycle.rb
 - lib/smith/agent/model_reference.rb
 - lib/smith/agent/provider_attempt.rb
+- lib/smith/agent/provider_call_timing.rb
 - lib/smith/agent/provider_candidate_sequence.rb
 - lib/smith/agent/provider_completion.rb
 - lib/smith/agent/provider_failure_handling.rb
@@ -173,11 +174,13 @@ files:
 - lib/smith/agent/registry_binding.rb
 - lib/smith/agent/reserved_input_bridge.rb
 - lib/smith/agent/usage_entry_recording.rb
+- lib/smith/agent/usage_traces.rb
 - lib/smith/agent/usage_tracking.rb
 - lib/smith/artifacts.rb
 - lib/smith/artifacts/file.rb
 - lib/smith/artifacts/memory.rb
 - lib/smith/artifacts/scoped_store.rb
+- lib/smith/attribution.rb
 - lib/smith/budget.rb
 - lib/smith/budget/amount_contract.rb
 - lib/smith/budget/amount_representation.rb
@@ -218,6 +221,7 @@ files:
 - lib/smith/events/.keep
 - lib/smith/events/bus.rb
 - lib/smith/events/step_completed.rb
+- lib/smith/events/step_failed.rb
 - lib/smith/events/subscription.rb
 - lib/smith/exponential_backoff.rb
 - lib/smith/guardrails.rb