smith-agents 0.4.0

data/lib/smith/trace.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Smith
+  module Trace
+    SENSITIVITY_CONTENT_KEYS = %i[args result].freeze
+
+    def self.record(type:, data:, sensitivity: :low)
+      adapter = resolve_adapter
+      return unless adapter
+
+      filtered = apply_content_policy(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
+
+    def self.resolve_adapter
+      configured = Smith.config.trace_adapter
+      return nil unless configured
+
+      if configured.is_a?(Class)
+        @adapter_instances ||= {}
+        @adapter_instances[configured] ||= configured.new
+      else
+        configured
+      end
+    end
+
+    def self.reset!
+      @adapter_instances = nil
+    end
+
+    def self.apply_content_policy(data, sensitivity)
+      case Smith.config.trace_content
+      when true
+        apply_sensitivity(data, sensitivity)
+      when :redacted
+        apply_sensitivity(redact_sensitive_keys(data), sensitivity)
+      else
+        data.except(*SENSITIVITY_CONTENT_KEYS)
+      end
+    end
+
+    def self.apply_sensitivity(data, sensitivity)
+      case sensitivity
+      when :high
+        data.except(*SENSITIVITY_CONTENT_KEYS)
+      when :medium
+        redact_sensitive_keys(data)
+      else
+        data
+      end
+    end
+
+    def self.redact_sensitive_keys(data)
+      data.each_with_object({}) do |(key, value), filtered|
+        filtered[key] = if SENSITIVITY_CONTENT_KEYS.include?(key)
+                          redact_value(value)
+                        else
+                          value
+                        end
+      end
+    end
+
+    def self.redact_value(value)
+      case value
+      when String
+        "[REDACTED]"
+      when Hash
+        value.transform_values { |v| v.is_a?(String) ? "[REDACTED]" : v }
+      else
+        value
+      end
+    end
+
+    def self.filter_fields(type, data)
+      configured_fields = Smith.config.trace_fields
+      return data unless configured_fields.is_a?(Hash)
+
+      allowed = configured_fields[type]
+      return data unless allowed.respond_to?(:include?)
+
+      data.each_with_object({}) do |(key, value), filtered|
+        filtered[key] = value if allowed.include?(key)
+      end
+    end
+  end
+end

data/lib/smith/types.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "dry-types"
+
+module Smith
+  module Types
+    include Dry.Types()
+
+    # Dry.Types() resolves constants via const_missing, which means
+    # const_defined?(:String, false) returns false. Contract specs use
+    # strict const_defined?(name, false) lookups, so we materialize
+    # the constants we need as direct module constants.
+    const_set(:String, const_get(:String))
+    const_set(:Integer, const_get(:Integer))
+  end
+end

data/lib/smith/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Smith
+  VERSION = "0.4.0"
+end

data/lib/smith/workflow/artifact_integration.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Smith
+  class Workflow
+    module ArtifactIntegration
+      private
+
+      def with_scoped_artifacts
+        if @inherited_scoped_artifacts
+          Smith.scoped_artifacts = @inherited_scoped_artifacts
+        else
+          backend = Smith.config.artifact_store || Smith.artifacts
+          Smith.scoped_artifacts = Artifacts::ScopedStore.new(backend: backend, namespace: execution_namespace)
+        end
+        yield
+      end
+
+      def execution_namespace
+        @execution_namespace ||= SecureRandom.uuid
+      end
+
+      def propagate_scoped_artifacts
+        Smith.scoped_artifacts
+      end
+
+      def build_session
+        manager = self.class.context_manager
+        messages = @session_messages ||= []
+        return nil if manager.nil? && messages.empty?
+
+        Context::Session.new(
+          messages: messages,
+          context_manager: manager,
+          persisted_context: @context
+        )
+      end
+    end
+  end
+end

data/lib/smith/workflow/budget_integration.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module BudgetIntegration
+      TOKEN_DIMENSIONS = %i[total_tokens token_limit].freeze
+      COST_DIMENSIONS = %i[total_cost].freeze
+      BUDGET_DIMENSIONS = (TOKEN_DIMENSIONS + COST_DIMENSIONS).freeze
+      AGENT_DIM_MAP = { token_limit: TOKEN_DIMENSIONS, cost: COST_DIMENSIONS }.freeze
+
+      private
+
+      def reserve_branch_budget(ledger, branch_estimates:)
+        return nil unless ledger && branch_estimates
+
+        branch_estimates.each { |dim, amount| ledger.reserve!(dim, amount) }
+        branch_estimates
+      end
+
+      def compute_branch_estimates(ledger, branch_count:, agent_budget: nil)
+        return nil unless ledger
+
+        ledger.limits.each_with_object({}) do |(dim, _limit), est|
+          per_branch = estimate_for_dimension(dim, ledger.remaining(dim), branch_count)
+          cap = agent_cap_for_dimension(dim, agent_budget)
+          est[dim] = cap ? [per_branch, cap].min : per_branch
+        end
+      end
+
+      def reconcile_branch_budget(ledger, estimates, agent_result: nil)
+        return unless ledger && estimates
+
+        actuals = extract_actuals(agent_result)
+        estimates.each do |dim, amt|
+          ledger.reconcile!(dim, amt, actual_for_dimension(dim, actuals[:tokens], actuals[:cost]))
+        end
+      end
+
+      def extract_actuals(agent_result)
+        {
+          tokens: (agent_result&.input_tokens || 0) + (agent_result&.output_tokens || 0),
+          cost: agent_result&.cost || 0
+        }
+      end
+
+      def actual_for_dimension(dim, actual_tokens, actual_cost = 0)
+        return actual_tokens if TOKEN_DIMENSIONS.include?(dim)
+        return actual_cost if COST_DIMENSIONS.include?(dim)
+
+        0
+      end
+
+      def release_branch_budget(ledger, estimates)
+        return unless ledger && estimates
+
+        estimates.each { |dim, amount| ledger.release!(dim, amount) }
+      end
+
+      def settle_budget_on_failure(ledger, estimates, agent_result)
+        return unless ledger && estimates
+
+        if agent_result
+          reconcile_branch_budget(ledger, estimates, agent_result: agent_result)
+        else
+          release_branch_budget(ledger, estimates)
+        end
+      end
+
+      def reserve_serial_budget(ledger, agent_budget: nil)
+        return nil unless ledger
+
+        estimates = ledger.limits.each_with_object({}) do |(dim, _limit), est|
+          remaining = BUDGET_DIMENSIONS.include?(dim) ? ledger.remaining(dim) : 0
+          cap = agent_cap_for_dimension(dim, agent_budget)
+          est[dim] = cap ? [remaining, cap].min : remaining
+        end
+
+        estimates.each { |dim, amount| ledger.reserve!(dim, amount) }
+        estimates
+      end
+
+      def finalize_branch(transition, index, result, ledger, reserved)
+        agent_result = result.is_a?(Workflow::AgentResult) ? result : nil
+        reconcile_branch_budget(ledger, reserved, agent_result: agent_result)
+        { branch: index, agent: transition.agent_name, output: agent_result ? agent_result.content : result }
+      end
+
+      def estimate_for_dimension(dim, limit, branch_count)
+        return 0 unless BUDGET_DIMENSIONS.include?(dim)
+
+        TOKEN_DIMENSIONS.include?(dim) ? [limit / branch_count, 1].max : limit / branch_count
+      end
+
+      def agent_cap_for_dimension(dim, agent_budget)
+        return nil unless agent_budget
+        return agent_budget[dim] if agent_budget.key?(dim)
+
+        AGENT_DIM_MAP.each do |agent_dim, workflow_dims|
+          return agent_budget[agent_dim] if workflow_dims.include?(dim) && agent_budget.key?(agent_dim)
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/smith/workflow/claim.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    # ActiveRecord-aware atomic claim helper. Two strategies:
+    #
+    # .atomic — AASM-event path. SELECT FOR UPDATE + record.public_send(transition_via)
+    #           inside transaction_owner.transaction. AASM callbacks fire.
+    # .cas    — single-statement CAS via update_all + where(status: from_statuses).
+    #           Does NOT invoke AASM events; intended for non-AASM claim sites
+    #           that already use update_all today.
+    #
+    # ActiveRecord is loaded lazily — this file does NOT const-reference
+    # ::ActiveRecord at module load. Both methods raise AdapterUnavailable
+    # before any other work when ::ActiveRecord is not defined.
+    module Claim
+      class AdapterUnavailable < Smith::Error; end
+      class UnexpectedStatus < Smith::Error
+        attr_reader :model, :id, :observed_status
+
+        def initialize(model:, id:, observed_status:)
+          @model = model
+          @id = id
+          @observed_status = observed_status
+          super("unexpected status #{observed_status.inspect} for #{model.name}##{id}")
+        end
+      end
+
+      def self.atomic(model_class, id:, from_statuses:, transition_via:,
+                      terminal_statuses: [], on_unexpected_status: :raise,
+                      transaction_owner: nil)
+        ensure_active_record!
+        validate_atomic_args!(model_class, transition_via)
+
+        owner = transaction_owner || model_class
+        from = Array(from_statuses).map(&:to_s)
+        terminal = Array(terminal_statuses).map(&:to_s)
+
+        claimed = false
+
+        owner.transaction do
+          locked = model_class.lock.find(id)
+          status = locked.public_send(:status).to_s
+
+          if from.include?(status)
+            locked.public_send(transition_via)
+            claimed = true
+          elsif terminal.include?(status)
+            claimed = false
+          else
+            handle_unexpected_status!(model_class, id, status, on_unexpected_status)
+            claimed = false
+          end
+        end
+
+        claimed ? model_class.find(id) : nil
+      end
+
+      def self.cas(model_class, id:, from_statuses:, to_status:,
+                   status_column: :status, updated_at_column: :updated_at,
+                   now: -> { Time.now.utc })
+        ensure_active_record!
+        from = Array(from_statuses).map(&:to_s)
+
+        updates = { status_column => to_status.to_s }
+        updates[updated_at_column] = now.call if updated_at_column
+
+        rows = model_class
+          .where(:id => id, status_column => from)
+          .update_all(updates)
+
+        rows.zero? ? nil : model_class.find(id)
+      end
+
+      def self.ensure_active_record!
+        return if defined?(::ActiveRecord::Base)
+
+        raise AdapterUnavailable,
+              "Smith::Workflow::Claim requires ActiveRecord (::ActiveRecord::Base is not defined). " \
+              "Add activerecord to your bundle. See docs/workflow_claim.md."
+      end
+      private_class_method :ensure_active_record!
+
+      def self.validate_atomic_args!(model_class, transition_via)
+        if transition_via.nil?
+          if model_class.respond_to?(:aasm)
+            raise ArgumentError,
+                  "Smith::Workflow::Claim.atomic requires transition_via: when the model uses AASM " \
+                  "(#{model_class.name} responds to .aasm). Use .cas for non-AASM CAS claims."
+          end
+          raise ArgumentError, "Smith::Workflow::Claim.atomic requires transition_via: (Symbol naming the event method)"
+        end
+
+        return if transition_via.is_a?(Symbol) || transition_via.is_a?(String)
+
+        raise ArgumentError, "transition_via must be a Symbol or String; got #{transition_via.inspect}"
+      end
+      private_class_method :validate_atomic_args!
+
+      def self.handle_unexpected_status!(model_class, id, status, mode)
+        case mode
+        when :raise
+          raise UnexpectedStatus.new(model: model_class, id: id, observed_status: status)
+        when :ignore
+          nil
+        when :log
+          Smith.config.logger&.warn(
+            "Smith::Workflow::Claim.atomic: unexpected status #{status.inspect} for #{model_class.name}##{id}"
+          )
+          nil
+        else
+          raise ArgumentError, "on_unexpected_status must be :raise, :ignore, or :log; got #{mode.inspect}"
+        end
+      end
+      private_class_method :handle_unexpected_status!
+    end
+  end
+end

data/lib/smith/workflow/data_volume_policy.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module DataVolumePolicy
+      LIGHTWEIGHT_SCALARS = [String, Integer, Float, Symbol, TrueClass, FalseClass, NilClass].freeze
+
+      private
+
+      def validate_data_volume!(output, agent_class)
+        return unless agent_class.respond_to?(:data_volume)
+        return unless agent_class.data_volume == :unbounded
+        return unless output.is_a?(Hash)
+
+        require_ref_key!(output)
+        require_scalar_values!(output)
+      end
+
+      def require_ref_key!(output)
+        return if output.keys.any? { |k| k.to_s.end_with?("_ref") }
+
+        raise GuardrailFailed, "data_volume :unbounded requires at least one *_ref key"
+      end
+
+      def require_scalar_values!(output)
+        output.each do |key, value|
+          next if key.to_s.end_with?("_ref")
+          next if LIGHTWEIGHT_SCALARS.any? { |type| value.is_a?(type) }
+
+          raise GuardrailFailed,
+                "data_volume :unbounded requires lightweight scalar values, got #{value.class} for :#{key}"
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/deadline_enforcement.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Smith
+  class Workflow
+    module DeadlineEnforcement
+      private
+
+      def check_deadline!
+        deadline = effective_deadline
+        return unless deadline
+
+        raise DeadlineExceeded, "wall_clock deadline exceeded" if Time.now.utc >= deadline
+      end
+
+      def effective_deadline
+        call_dl = Thread.current[:smith_call_deadline]
+        [wall_clock_deadline, call_dl].compact.min
+      end
+
+      def with_agent_context(agent_class)
+        saved_deadline = Tool.current_deadline
+        saved_call_ledger = Thread.current[:smith_call_ledger]
+        apply_agent_deadline(agent_class)
+        narrow_tool_deadline!
+        apply_agent_tool_calls(agent_class)
+        apply_agent_call_ledger(agent_class)
+        yield
+      ensure
+        Tool.current_deadline = saved_deadline
+        Thread.current[:smith_call_ledger] = saved_call_ledger
+        clear_agent_deadline
+        clear_agent_tool_calls
+      end
+
+      def effective_call_ledger
+        @ledger || Thread.current[:smith_call_ledger]
+      end
+
+      def apply_agent_deadline(agent_class)
+        agent_wc = agent_class&.budget&.dig(:wall_clock)
+        Thread.current[:smith_call_deadline] = agent_wc ? Time.now.utc + agent_wc : nil
+      end
+
+      def clear_agent_deadline
+        Thread.current[:smith_call_deadline] = nil
+      end
+
+      def narrow_tool_deadline!
+        call_dl = Thread.current[:smith_call_deadline]
+        return unless call_dl
+
+        current = Tool.current_deadline
+        Tool.current_deadline = current ? [current, call_dl].min : call_dl
+      end
+
+      def apply_agent_tool_calls(agent_class)
+        agent_tc = agent_class&.budget&.dig(:tool_calls)
+        Tool.current_tool_call_allowance = agent_tc ? { remaining: agent_tc } : nil
+      end
+
+      def clear_agent_tool_calls
+        Tool.current_tool_call_allowance = nil
+      end
+
+      def apply_agent_call_ledger(agent_class)
+        Thread.current[:smith_call_ledger] = @ledger ? nil : build_agent_call_ledger(agent_class)
+      end
+
+      def build_agent_call_ledger(agent_class)
+        agent_budget = agent_class&.budget
+        return nil unless agent_budget
+
+        limits = {}
+        limits[:token_limit] = agent_budget[:token_limit] if agent_budget[:token_limit]
+        limits[:total_cost] = agent_budget[:cost] if agent_budget[:cost]
+        return nil if limits.empty?
+
+        Budget::Ledger.new(limits: limits)
+      end
+
+      def wall_clock_deadline
+        return @wall_clock_deadline if defined?(@wall_clock_deadline)
+
+        @wall_clock_deadline = compute_wall_clock_deadline
+      end
+
+      def compute_wall_clock_deadline
+        limit = self.class.budget&.dig(:wall_clock)
+        own_deadline = limit ? Time.iso8601(@created_at) + limit : nil
+
+        return own_deadline unless @inherited_deadline
+        return @inherited_deadline unless own_deadline
+
+        [own_deadline, @inherited_deadline].min
+      end
+    end
+  end
+end

data/lib/smith/workflow/deterministic_execution.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module DeterministicExecution
+      private
+
+      def execute_deterministic_step(transition)
+        check_deadline!
+        step = build_deterministic_step(transition)
+        emit_deterministic_trace(transition, result: :started)
+        transition.deterministic_block.call(step)
+        apply_deterministic_writes!(step)
+        emit_deterministic_trace(
+          transition,
+          result: step.routed_to ? :routed : :success,
+          routed_to: step.routed_to,
+          outcome_kind: step.outcome&.dig(:kind)
+        )
+        nil
+      rescue StandardError => e
+        emit_deterministic_trace(transition, result: :failed, error: e.message)
+        raise
+      end
+
+      def build_deterministic_step(transition)
+        DeterministicStep.new(
+          context: snapshot_value(@context),
+          session_messages: snapshot_value(@session_messages || []),
+          tool_results: snapshot_value(@tool_results || []),
+          state: @state,
+          transition_name: transition.name
+        )
+      end
+
+      def apply_deterministic_writes!(step)
+        @context.merge!(step.context_writes)
+        step.context_writes.each_key { |key| record_persisted_key!(key) }
+        @router_next_transition = step.routed_to if step.routed_to
+        @outcome = snapshot_value(step.outcome) if step.outcome
+      end
+
+      def emit_deterministic_trace(transition, result:, routed_to: nil, error: nil, outcome_kind: nil)
+        data = { transition: transition.name, from: transition.from, to: transition.to,
+                 kind: transition.deterministic_kind, result: result }
+        data[:routed_to] = routed_to if routed_to
+        data[:error] = error if error
+        data[:outcome_kind] = outcome_kind if outcome_kind
+        Smith::Trace.record(type: :deterministic_step, data: data)
+      end
+    end
+  end
+end

data/lib/smith/workflow/deterministic_step.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class DeterministicStep
+      attr_reader :context, :tool_results, :session_messages, :current_state, :transition_name,
+                  :context_writes, :routed_to, :outcome
+
+      def initialize(context:, session_messages:, tool_results:, state:, transition_name:)
+        @context = context
+        @session_messages = session_messages
+        @tool_results = tool_results
+        @current_state = state
+        @transition_name = transition_name
+        @context_writes = {}
+        @routed_to = nil
+        @outcome = nil
+      end
+
+      def last_output
+        return @last_output if defined?(@last_output)
+
+        msg = session_messages.reverse.find { |m| m[:role] == :assistant || m[:role] == "assistant" }
+        @last_output = msg&.dig(:content)
+      end
+
+      alias_method :output, :last_output
+
+      def read_context(key)
+        @context_writes.key?(key) ? @context_writes[key] : context[key]
+      end
+
+      def write_context(key, value)
+        raise WorkflowError, "write_context key must be a Symbol, got #{key.class}" unless key.is_a?(Symbol)
+
+        @context_writes[key] = value
+      end
+
+      def route_to(transition_name)
+        raise WorkflowError, "route_to already called with :#{@routed_to}" if @routed_to
+
+        @routed_to = transition_name
+      end
+
+      def write_outcome(kind:, payload:)
+        raise WorkflowError, "write_outcome kind must be a Symbol, got #{kind.class}" unless kind.is_a?(Symbol)
+        raise WorkflowError, "write_outcome already called with :#{@outcome[:kind]}" if @outcome
+
+        @outcome = { kind: kind, payload: payload }
+      end
+
+      def fail!(message, retryable: nil, kind: nil, details: nil)
+        raise DeterministicStepFailure.new(message, retryable: retryable, kind: kind, details: details)
+      end
+    end
+  end
+end