smith-agents 0.8.0 → 0.11.0

data/lib/smith/workflow/run_result.rb

@@ -33,6 +33,16 @@ module Smith
         steps.reverse.map { |step| step[:error] }.compact.first
       end
 
+      # Every verdict an optimize step's loops recorded, in step, attempt and
+      # round order, each a frozen record naming its step's transition. Like
+      # `steps`, they belong to the run that executed the step: a terminal
+      # restore has none.
+      def evaluations
+        steps.flat_map do |step|
+          (step[:evaluations] || []).map { |evaluation| { transition: step[:transition], **evaluation }.freeze }
+        end
+      end
+
       def failed_transition
         failure_detail&.fetch(:transition)
       end

data/lib/smith/workflow/split_step_persistence/composite_branch_execution.rb

@@ -40,7 +40,15 @@ module Smith
         end
 
         def capture_composite_branch(&block)
-          output = within_raw_step_context { with_scoped_artifacts(&block) }
+          output = within_raw_step_context do
+            # Same ambient attribution the in-process step path installs, so
+            # durably executed branches tag usage and traces identically
+            # (execution key from the restored persistence key, the split
+            # step's transition, then the branch overlay downstream).
+            # Restoration is owned by within_raw_step_context's snapshot.
+            install_step_attribution(@split_step_transition) if @split_step_transition
+            with_scoped_artifacts(&block)
+          end
           [output, nil]
         rescue StandardError => e
           [nil, e]

data/lib/smith/workflow/split_step_persistence/state_snapshot.rb

@@ -58,6 +58,7 @@ module Smith
 
         def detach_split_step_results!
           @last_output = snapshot_value(@last_output)
+          @last_agent_execution = snapshot_value(@last_agent_execution)
           @last_failed_step = snapshot_value(@last_failed_step)
           @last_prepared_input = snapshot_value(@last_prepared_input)
         end

data/lib/smith/workflow/step_completion.rb

@@ -7,6 +7,16 @@ module Smith
 
       def complete_step(transition, output)
         step = { transition: transition.name, from: transition.from, to: transition.to, output: output }
+        # Fold in the serial agent attribution captured for this step (if any),
+        # then clear the transient carrier. record_step_snapshot reads these off
+        # the returned step to update the durable @last_agent_execution.
+        if @pending_agent_execution
+          step[:model] = @pending_agent_execution[:model]
+          step[:provider] = @pending_agent_execution[:provider]
+        end
+
+        @pending_agent_execution = nil
+        fold_pending_evaluations(step)
         result = SplitStepPersistence
                  .instance_method(:prepare_split_step_execution_result)
                  .bind_call(self, step)
@@ -14,6 +24,9 @@ module Smith
         SplitStepPersistence
           .instance_method(:commit_split_step_execution_result!)
           .bind_call(self, result)
+        # Cleared only once the record is committed: a completion that fails
+        # before this folds the same verdicts into its failure record.
+        @pending_evaluations = nil
         @state = transition.to
         @next_transition_name = @router_next_transition || transition.success_transition
         @router_next_transition = nil

data/lib/smith/workflow/step_context.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../attribution"
 require_relative "thread_context_snapshot"
 
 module Smith
@@ -10,6 +11,7 @@ module Smith
       def with_step_context(transition, &block)
         ThreadContextSnapshot.new.around do
           setup_step_context
+          install_step_attribution(transition)
           Thread.handle_interrupt(Object => :immediate, &block)
         rescue StandardError => e
           @outcome = nil
@@ -17,6 +19,32 @@ module Smith
         ensure
           teardown_step_context
         end
+      ensure
+        flush_step_failure_emission
+      end
+
+      # Runs after the snapshot's interrupt mask has closed, so host
+      # StepFailed handlers execute interruptible, exactly as StepCompleted
+      # handlers do inside the step. The step context is gone by now, so the
+      # run identity and workflow label are seeded explicitly; the failed
+      # step's own transition facts travel in the staged step hash. Flushes
+      # on every exit of with_step_context, including the re-raise paths.
+      # The read-clear-mark triple is masked so an async interrupt cannot
+      # strand a staged failure between read and clear; the marker lets the
+      # unresolved-transition handler recognize an error this path already
+      # emitted. Only the emission itself stays interruptible.
+      def flush_step_failure_emission
+        step = nil
+        Thread.handle_interrupt(Object => :never) do
+          step = @pending_step_failure
+          @pending_step_failure = nil
+          @emitted_step_failure_error = step[:error] if step
+        end
+        return unless step
+
+        Attribution.with(execution_key: @persistence_key, workflow: self.class.name || "anonymous") do
+          emit_step_failed(step)
+        end
       end
 
       def within_raw_step_context(&block)
@@ -34,6 +62,24 @@ module Smith
         Tool.current_tool_result_collector = tool_result_collector
       end
 
+      # The ambient attribution for this step. Restoration is owned by the
+      # surrounding ThreadContextSnapshot (the attribution thread key is one
+      # of its THREAD_KEYS), so installation is a plain assignment. A nil
+      # persistence key preserves any host-seeded outer execution_key, and
+      # `workflow` is always a string ("anonymous" when the class has no
+      # name) so a nested child always overrides the parent's label. The
+      # per-step facts (transition, from, to) are replaced verbatim, nil
+      # included: a nested child's `from: nil` transition must not inherit
+      # the parent step's `from` through the nil-ignoring merge. branch_key
+      # and round inherit deliberately (a child genuinely runs within them).
+      def install_step_attribution(transition)
+        Attribution.install(
+          Attribution.ambient
+                     .merge(execution_key: @persistence_key, workflow: self.class.name || "anonymous")
+                     .override(transition: transition.name, from: transition.from, to: transition.to)
+        )
+      end
+
       def teardown_step_context
         Tool.current_guardrails = nil
         Tool.current_deadline = nil

data/lib/smith/workflow/thread_context_snapshot.rb

@@ -22,6 +22,7 @@ module Smith
         current_invocation
       ].freeze
       THREAD_KEYS = %i[
+        smith_attribution
         smith_call_deadline
         smith_call_ledger
         smith_failed_agent_results

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

@@ -44,7 +44,7 @@ module Smith
       @step_count = 0
       @next_transition_name = nil
       @ledger = ledger || build_ledger
-      @created_at = created_at || Time.now.utc.iso8601
+      @created_at = created_at || Time.now.utc.iso8601(6)
       @updated_at = @created_at
       @total_cost = 0.0
       @total_tokens = 0
@@ -58,6 +58,16 @@ 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. `@pending_evaluations` is the
+      # optimizer's, carrying a loop's verdicts into its step's record.
+      @last_agent_execution = nil
+      @pending_agent_execution = nil
+      @pending_evaluations = nil
       @last_failed_step = nil
       # Optimistic-locking version. Incremented on each persist!; restored
       # from the persisted payload. Adapters that support store_versioned
@@ -112,7 +122,7 @@ module Smith
                       execute_step(transition)
                     end
       @step_count += 1
-      @updated_at = Time.now.utc.iso8601
+      @updated_at = Time.now.utc.iso8601(6)
       record_step_snapshot(step_result)
       step_result
     rescue UnresolvedTransitionError => e
@@ -157,6 +167,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 +211,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 +366,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
@@ -55,8 +59,8 @@ module Smith
 
   # Persistence TTL in Integer seconds. nil (default) means workflows
   # persist indefinitely. Adapters that natively support TTL (Redis,
-  # CacheStore, Memory) pass this through; ActiveRecordStore TTL is
-  # deferred (would need an `expires_at` column + sweeper).
+  # CacheStore, Memory) pass this through; ActiveRecordStore has no expiry
+  # column and refuses a non-nil TTL.
   # Per-workflow `Workflow.persistence_ttl 1.day.to_i` DSL overrides this.
   setting :persistence_ttl, 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.11.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