smith-agents 0.8.0 → 0.11.0

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/budget/amount_representation.rb

@@ -2,6 +2,7 @@
 
 require "bigdecimal"
 require "dry-initializer"
+require_relative "decimal_context"
 
 module Smith
   module Budget
@@ -26,6 +27,25 @@ module Smith
         finite_float!(amount)
       end
 
+      # Remaining capacity, or one of parts equal shares of it, is reserved as
+      # read, so parts reservations of the external value must never exceed the
+      # exact amount. An Integer keeps floor division; a Float steps down until
+      # its decimal form fits, which takes O(1) steps because Float division
+      # lands within one ulp of the exact share.
+      def externalize_remaining(key, amount, parts = 1)
+        unless parts.is_a?(Integer) && parts.positive?
+          raise ArgumentError, "budget share parts must be a positive Integer"
+        end
+
+        share = externalize_amount(key, amount) / parts
+        return share unless share.is_a?(Float)
+
+        DecimalContext.call do
+          share = share.prev_float while internalize_amount(share) * parts > amount
+        end
+        share
+      end
+
       private
 
       def internalize_amount(amount)

data/lib/smith/budget/ledger.rb

@@ -58,12 +58,16 @@ module Smith
         @mutex.synchronize { release_reservation(token) }
       end
 
-      def remaining(key)
+      def remaining(key) = remaining_share(key, 1)
+
+      # One of parts equal shares of the remaining amount, taken from the exact
+      # internal value so that parts reservations of it always fit.
+      def remaining_share(key, parts)
         dimension = @amount_contract.dimension!(key)
         @amount_contract.known_dimension!(dimension)
         @mutex.synchronize do
           amount = @state_transition.remaining(@publication.state, dimension)
-          @representation.externalize_amount(dimension, amount)
+          @representation.externalize_remaining(dimension, amount, parts)
         end
       end
 

data/lib/smith/context/state_injection.rb

@@ -6,19 +6,29 @@ module Smith
       MARKER = "[smith:injected-state]"
 
       def self.inject(messages, formatter:, persisted:)
-        content = "#{MARKER}\n#{formatter.call(persisted)}"
+        text = formatter.call(persisted).to_s
+        content = "#{MARKER}\n#{text}"
 
         existing_index = messages.index do |message|
           message_content = message[:content] || message["content"]
           message_content.is_a?(String) && message_content.start_with?(MARKER)
         end
 
-        if existing_index
+        if blank?(text)
+          without_marker(messages, existing_index)
+        elsif existing_index
           messages.dup.tap { |msgs| msgs[existing_index] = { role: :system, content: content } }
         else
           messages + [{ role: :system, content: content }]
         end
       end
+
+      def self.blank?(text) = text.valid_encoding? && text.strip.empty?
+
+      def self.without_marker(messages, index)
+        index ? messages.dup.tap { |msgs| msgs.delete_at(index) } : messages
+      end
+      private_class_method :blank?, :without_marker
     end
   end
 end

data/lib/smith/diagnostic_text.rb

@@ -9,7 +9,10 @@ module Smith
     STRING_BYTESIZE = String.instance_method(:bytesize)
     STRING_BYTESLICE = String.instance_method(:byteslice)
     MODULE_MATCH = Module.instance_method(:===)
-    private_constant :TRUNCATION_MARKER, :STRING_BYTESIZE, :STRING_BYTESLICE, :MODULE_MATCH
+    MODULE_NAME = Module.instance_method(:name)
+    OBJECT_CLASS = Object.instance_method(:class)
+    private_constant :TRUNCATION_MARKER, :STRING_BYTESIZE, :STRING_BYTESLICE, :MODULE_MATCH, :MODULE_NAME,
+                     :OBJECT_CLASS
 
     extend Dry::Initializer
 
@@ -18,6 +21,12 @@ module Smith
 
     def self.capture(value, max_bytes: MAX_BYTES) = new(value, max_bytes:).call
 
+    # An error's class name, read through the native lookups so the error
+    # cannot misreport it, and bounded like any diagnostic identifier.
+    def self.error_class_name(error)
+      capture(MODULE_NAME.bind_call(OBJECT_CLASS.bind_call(error)) || "anonymous_error", max_bytes: 512)
+    end
+
     def call
       validate_limit!
       text = utf8_prefix

data/lib/smith/doctor/checks/durability.rb

@@ -31,10 +31,26 @@ module Smith
           )
           return
         else
+          check_ttl_support(report, adapter)
           check_persist_and_restore(report, adapter)
           check_resume_after_restore(report, adapter)
         end
 
+        # ActiveRecordStore refuses every write that carries a TTL, so a
+        # configured global TTL would fail the first persisted run.
+        def self.check_ttl_support(report, adapter)
+          ttl = ::Smith.config.persistence_ttl
+          return if ttl.nil? || !adapter.is_a?(::Smith::PersistenceAdapters::ActiveRecordStore)
+
+          report.add(
+            name: "durability.ttl",
+            status: :fail,
+            message: "ActiveRecordStore cannot expire workflow state; persistence_ttl must be nil",
+            detail: "Smith.config.persistence_ttl is #{ttl.inspect}, so every persisted write refuses it. " \
+                    "Set it to nil, or use an adapter that honours TTL."
+          )
+        end
+
         def self.check_persist_and_restore(report, adapter)
           workflow_class = build_probe_class
           payload = JSON.generate(workflow_class.new.to_state)

data/lib/smith/doctor/checks/persistence_capabilities.rb

@@ -17,7 +17,10 @@ module Smith
         OPTIONAL_CAPABILITIES = Smith::PersistenceAdapters::OPTIONAL_METHODS
 
         def run(report)
-          adapter = resolve_adapter
+          adapter = Smith.persistence_adapter
+        rescue StandardError => e
+          report_invalid_adapter(report, e)
+        else
           return report_missing_adapter(report) if adapter.nil?
 
           missing = OPTIONAL_CAPABILITIES.reject { |cap| capability_available?(adapter, cap) }
@@ -26,12 +29,6 @@ module Smith
           report_missing_capabilities(report, adapter, missing)
         end
 
-        def resolve_adapter
-          Smith.persistence_adapter
-        rescue StandardError
-          nil
-        end
-
         def capability_available?(adapter, capability)
           return false unless Smith::PersistenceAdapters.supports?(adapter, capability)
           return true unless capability == :persistence_identity
@@ -42,6 +39,15 @@ module Smith
           false
         end
 
+        def report_invalid_adapter(report, error)
+          report.add(
+            name: "persistence.capabilities",
+            status: :fail,
+            message: "Persistence adapter configuration is invalid",
+            detail: error.message
+          )
+        end
+
         def report_missing_adapter(report)
           report.add(
             name: "persistence.capabilities",

data/lib/smith/errors.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "diagnostic_text"
 require_relative "error"
 require_relative "persisted_failure_invalid"
 require_relative "pricing_configuration_error"
@@ -88,6 +89,11 @@ module Smith
   class AgentError < Error; end
 
   class BlankAgentOutputError < AgentError
+    DETAIL_NAMES = %i[agent_name model_used].freeze
+    DETAIL_KEYS = DETAIL_NAMES.to_h { |name| [name.to_s.freeze, name] }.freeze
+    MAX_DETAIL_BYTES = 512
+    private_constant :DETAIL_NAMES, :DETAIL_KEYS, :MAX_DETAIL_BYTES
+
     attr_reader :agent_name, :model_used
 
     def initialize(agent_name:, model_used:)
@@ -101,6 +107,46 @@ module Smith
 
       super(detail)
     end
+
+    def details
+      {
+        agent_name: agent_name && DiagnosticText.capture(agent_name.to_s, max_bytes: MAX_DETAIL_BYTES),
+        model_used: model_used && DiagnosticText.capture(model_used.to_s, max_bytes: MAX_DETAIL_BYTES)
+      }.freeze
+    end
+
+    def self.from_details(details)
+      values = normalize_details(details)
+      new(agent_name: values.fetch(:agent_name)&.to_sym, model_used: values.fetch(:model_used))
+    end
+
+    def self.normalize_details(details)
+      raise ArgumentError, "blank agent output details must be a Hash" unless details.is_a?(Hash)
+
+      values = {}
+      Hash.instance_method(:each_pair).bind_call(details) do |key, value|
+        name = key.is_a?(Symbol) ? key : DETAIL_KEYS[key]
+        unless DETAIL_NAMES.include?(name)
+          raise ArgumentError, "blank agent output details contain an unknown attribute"
+        end
+        raise ArgumentError, "blank agent output details contain a duplicate attribute" if values.key?(name)
+
+        values[name] = bounded_detail(name, value)
+      end
+      raise ArgumentError, "blank agent output details are incomplete" unless values.length == DETAIL_NAMES.length
+
+      values
+    end
+
+    def self.bounded_detail(name, value)
+      return value if value.nil?
+
+      bounded = value.is_a?(String) && value.valid_encoding? && value.bytesize <= MAX_DETAIL_BYTES
+      raise ArgumentError, "blank agent output detail #{name} must be bounded text" unless bounded
+
+      value
+    end
+    private_class_method :normalize_details, :bounded_detail
   end
 
   class WorkflowError < Error; end
@@ -185,15 +231,20 @@ module Smith
   # `idempotency_mode :strict`. Signals that a previous worker crashed
   # between `persist!` (before advance) and `persist!` (after advance);
   # the step's effects are unknown, so blindly re-running could
-  # double-execute non-idempotent agent calls or tools.
+  # double-execute non-idempotent agent calls or tools. `state` is the
+  # persisted state the interrupted step started from and `transition` the
+  # next transition the payload records; each is nil when unknown.
   class StepInProgressOnRestore < Error
-    attr_reader :workflow, :persistence_key
+    attr_reader :workflow, :persistence_key, :state, :transition
 
-    def initialize(workflow:, persistence_key:)
+    def initialize(workflow:, persistence_key:, state: nil, transition: nil)
       @workflow = workflow
       @persistence_key = persistence_key
+      @state = state.to_sym if state.is_a?(String) || state.is_a?(Symbol)
+      @transition = transition.to_sym if transition.is_a?(String) || transition.is_a?(Symbol)
       super(
-        "step in progress on restore for #{workflow} key=#{persistence_key.inspect}: " \
+        "step in progress on restore for #{workflow} key=#{persistence_key.inspect}" \
+        "#{" state=#{@state.inspect}" if @state}: " \
         "a previous worker crashed mid-step. Hosts using idempotency_mode :strict must " \
         "decide whether to clear the persisted state (idempotent re-run unsafe) or " \
         "switch to :lax (assume re-run is safe)."

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/persistence_adapters/active_record_exact_store.rb

@@ -5,9 +5,8 @@ module Smith
     module ActiveRecordExactStore
       attr_reader :persistence_identity
 
-      def replace_exact(key, payload, expected_payload:, ttl: nil) # rubocop:disable Lint/UnusedMethodArgument
-        ensure_version_column!
-        ensure_locking_configuration!
+      def replace_exact(key, payload, expected_payload:, ttl: nil)
+        ensure_versioned_write!(ttl)
         model = model_class
         ensure_exact_schema!(model)
         ActiveRecordExactWrite.new(
@@ -25,6 +24,12 @@ module Smith
 
       private
 
+      def ensure_versioned_write!(ttl)
+        PersistenceAdapters.refuse_active_record_ttl!(ttl)
+        ensure_version_column!
+        ensure_locking_configuration!
+      end
+
       def ensure_exact_schema!(model)
         ensure_exact_payload_column!(model)
         ensure_exact_key_uniqueness!(model)

data/lib/smith/persistence_adapters/active_record_store.rb

@@ -16,10 +16,8 @@ module Smith
         @persistence_identity = identity.to_s.dup.freeze if identity
       end
 
-      def store(key, payload, ttl: nil) # rubocop:disable Lint/UnusedMethodArgument
-        # TTL is deferred for ActiveRecordStore — would require an
-        # `expires_at` column + a periodic sweeper job. Ignored here;
-        # documented as a known limitation.
+      def store(key, payload, ttl: nil)
+        PersistenceAdapters.refuse_active_record_ttl!(ttl)
         Retry.with_retries(operation: :store, transient: ActiveRecordConnectionErrors.classes) do
           record = model_class.find_or_initialize_by(@key_column => key)
           record.public_send(:"#{@payload_column}=", payload)
@@ -47,9 +45,8 @@ module Smith
       # `lock_version` column. Requires the AR model to have a
       # `lock_version` (or configured) integer column with default 0.
       # If absent, raises ArgumentError directing the host to migrate.
-      def store_versioned(key, payload, expected_version:, ttl: nil) # rubocop:disable Lint/UnusedMethodArgument
-        ensure_version_column!
-        ensure_locking_configuration!
+      def store_versioned(key, payload, expected_version:, ttl: nil)
+        ensure_versioned_write!(ttl)
 
         write_versioned(key, payload, expected_version)
       rescue *ActiveRecordConnectionErrors.classes => e

data/lib/smith/persistence_adapters.rb

@@ -71,6 +71,16 @@ module Smith
     end
     private_class_method :build
 
+    # ActiveRecordStore's host table has no expiry column, so a TTL could
+    # only be ignored. Its writes fail closed instead of silently keeping
+    # state forever; reads and deletes never take a TTL and keep working.
+    def self.refuse_active_record_ttl!(ttl)
+      return if ttl.nil?
+
+      raise ArgumentError,
+            "ActiveRecordStore cannot expire workflow state; persistence_ttl must be nil, got #{ttl.inspect}"
+    end
+
     # Capability introspection used by Workflow#persist! to decide
     # whether the adapter supports optimistic locking via store_versioned.
     def self.supports?(adapter, capability)