smith-agents 0.4.0

data/docs/TOOLS_AND_GUARDRAILS.md

@@ -0,0 +1,140 @@
+# Tools and Guardrails
+
+## Tools
+
+Smith tools extend RubyLLM tools with:
+
+- privilege enforcement
+- custom authorization
+- tool guardrails
+- deadline enforcement
+- tool-call budgeting
+- tracing
+- result capture (workflow-scoped tool output collection)
+
+Example:
+
+```ruby
+class RefundCustomer < Smith::Tool
+  category :action
+
+  capabilities do
+    privilege :elevated
+  end
+
+  authorize do |context|
+    context[:account_id] && context[:role] == :elevated
+  end
+
+  def perform(context:, charge_id:, reason:)
+    # call your billing system here
+    { refunded: true, charge_id: charge_id, reason: reason }
+  end
+end
+```
+
+### Tool Compatibility (provider-aware tool selection)
+
+Tools can declare which provider/endpoint combinations they tolerate. `Smith::Models::Normalizer` consults this metadata at chat construction and drops incompatible tools rather than letting the provider reject the request. Tools without a declaration are universally compatible (preserves existing behavior).
+
+```ruby
+class WebSearch < Smith::Tool
+  # Allowlist form: specific providers, plus an OpenAI endpoint constraint.
+  compatible_with :anthropic, :gemini, openai: :responses
+
+  def perform(query:)
+    # ...
+  end
+end
+```
+
+When `Smith.config.openai_api_mode = :auto` (the default) AND the tool requires `/v1/responses`, the normalizer instead sets `@params[:openai_api_mode] = :responses` so the routing prepend can dispatch via the Responses endpoint. When `:off`, the tool is dropped gracefully.
+
+The compatibility spec is inherited by subclasses; subclasses can override by calling `compatible_with` again. The spec is consulted only by the Normalizer, so tools without a declaration retain their pre-refactor behavior.
+
+### Tool Result Capture
+
+Tools can declare a `capture_result` block to collect structured data during workflow execution. Smith stores captured data on the workflow and exposes it on `RunResult#tool_results`. Smith does not interpret the payload — the host app owns all projection.
+
+```ruby
+class WebSearch < Smith::Tool
+  capture_result do |kwargs, result|
+    { query: kwargs[:query], urls: extract_urls(result) }
+  end
+
+  def perform(query:)
+    # search implementation
+  end
+end
+```
+
+After workflow execution:
+
+```ruby
+result = MyWorkflow.run_persisted!(key: "search:123", context: { topic: "AI" })
+result.tool_results
+# => [{ tool: "web_search", captured: { query: "AI trends", urls: ["https://..."] } }]
+```
+
+Captured tool results survive persistence — they are included in `to_state` and restored via `from_state`.
+
+`tool_results` is designed for compact structured evidence (URLs, metadata, refs). Hosts should avoid storing large raw payloads there. If large tool outputs are needed, use artifacts and capture refs or metadata instead.
+
+You can still use RubyLLM agent tool wiring on your agents:
+
+```ruby
+class RefundAgent < Smith::Agent
+  register_as :refund_agent
+  model "gpt-4.1-nano"
+  tools RefundCustomer
+end
+```
+
+## Guardrails
+
+Guardrails can be attached at either the workflow level or the agent level.
+
+Workflow guardrails run before agent guardrails for inputs, and before agent guardrails for outputs as well.
+
+Example:
+
+```ruby
+class SupportGuardrails < Smith::Guardrails
+  def require_input(payload)
+    raise "missing input" if payload.nil?
+  end
+
+  def sanitize_output(payload)
+    raise "empty response" if payload.nil?
+  end
+
+  def require_ticket(kwargs)
+    raise "ticket_id required" unless kwargs.dig(:context, :ticket_id)
+  end
+
+  input :require_input
+  output :sanitize_output
+  tool :require_ticket, on: [:refund_customer]
+end
+```
+
+Attach them like this:
+
+```ruby
+class GuardedAgent < Smith::Agent
+  register_as :guarded_agent
+  model "gpt-4.1-nano"
+  guardrails SupportGuardrails
+end
+
+class GuardedWorkflow < Smith::Workflow
+  guardrails SupportGuardrails
+  initial_state :idle
+  state :done
+
+  transition :finish, from: :idle, to: :done do
+    execute :guarded_agent
+  end
+end
+```
+

data/docs/workflow_claim.md

@@ -0,0 +1,58 @@
+# Smith::Workflow::Claim
+
+ActiveRecord-aware atomic claim helper. Consolidates the SELECT FOR UPDATE + status-transition pattern hosts otherwise reinvent in every per-record Execution wrapper.
+
+ActiveRecord is loaded lazily. `lib/smith/workflow/claim.rb` does NOT const-reference `::ActiveRecord` at module load — both `.atomic` and `.cas` raise `Smith::Workflow::Claim::AdapterUnavailable` only when invoked without AR present. Smith stays gem-load-time decoupled from AR.
+
+## `.atomic` — AASM event path
+
+```ruby
+Smith::Workflow::Claim.atomic(
+  ResearchSession,
+  id: session.id,
+  from_statuses: %w[queued],
+  transition_via: :mark_processing!,
+  terminal_statuses: %w[processing ready failed],
+  transaction_owner: ApplicationRecord
+)
+```
+
+Wraps the transition in `transaction_owner.transaction` (defaults to `model_class`). Inside the block: `lock.find(id)`, status check, then `record.public_send(transition_via)` — AASM events fire normally with all callbacks intact.
+
+- Returns the reloaded record on success.
+- Returns `nil` when current status is in `terminal_statuses` (e.g. a duplicate enqueue arriving after the original already finished).
+- Raises `Smith::Workflow::Claim::UnexpectedStatus` when status is outside `from_statuses ∪ terminal_statuses` (default behavior; pass `on_unexpected_status: :ignore` or `:log` to soften).
+- Raises `ArgumentError` when `transition_via:` is nil AND the model responds to `.aasm` — prevents silent AASM-callback drops.
+
+When using cross-model transactions (e.g. AR models inherit from `ApplicationRecord`), pass `transaction_owner: ApplicationRecord` so the existing transaction scope is preserved.
+
+## `.cas` — single-statement CAS path
+
+```ruby
+Smith::Workflow::Claim.cas(
+  Post,
+  id: post.id,
+  from_statuses: %w[draft scheduled failed],
+  to_status: "processing"
+)
+```
+
+Single `update_all` with `where(status: from_statuses)`. Returns the reloaded record or `nil` if rowcount is zero. Stamps `updated_at` via the injected `now:` lambda (defaults to `-> { Time.now.utc }`).
+
+- Does NOT invoke AASM events. AASM callbacks are skipped by design — this path is for non-AASM CAS sites (e.g. `Posts::Publish` style).
+- ActiveRecord 8.x increments `lock_version` on `update_all` when the column is present. Consumer code that depends on `lock_version` should account for this — `.cas` makes no promise about lock_version semantics.
+
+## Idempotency contract
+
+For both strategies, calling twice with the same `id` (no concurrency) returns the claimed record on the first call and `nil` on the second, because the status is no longer in `from_statuses`. No explicit advisory lock is held.
+
+## When to use which
+
+- `.atomic` — the model uses AASM (or you want guards/callbacks/auxiliary timestamps to fire).
+- `.cas` — the model does NOT use AASM AND you want a single-statement update.
+
+If the model has AASM and you want to skip events, call `.cas` explicitly; if you call `.atomic` without `transition_via:` on an AASM model, you'll get an `ArgumentError` so the silent-callback-drop is impossible.
+
+## Testing
+
+Specs that exercise the AR strategies are tagged `:ar` and excluded from the default suite. The full suite under `SMITH_AR_SPECS=1` boots an in-memory SQLite database and the `ClaimableRecord` fixture model. Default `bundle exec rspec` runs 816 examples (Claim load-hygiene only); `SMITH_AR_SPECS=1 bundle exec rspec` runs 831 (adds 15 AR-tagged Claim specs).

data/exe/smith

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "smith"
+require "smith/cli"
+
+exit Smith::CLI.new(ARGV).run

data/lib/generators/smith/install/install_generator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Smith
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path("templates", __dir__)
+
+    def create_smith_initializer
+      template "smith.rb.tt", "config/initializers/smith.rb"
+    end
+
+    def show_next_steps
+      say ""
+      say "Smith installed. Next steps:", :green
+      say "  1. Configure RubyLLM in config/initializers/ruby_llm.rb"
+      say "  2. Run: bin/rails smith:doctor"
+      say "  3. Define your first agent and workflow"
+      say ""
+    end
+  end
+end

data/lib/generators/smith/install/templates/smith.rb.tt

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+Smith.configure do |config|
+  config.logger = Rails.logger
+
+  # Host durability verification / persistence adapter options:
+  # config.persistence_adapter = :rails_cache
+  # config.persistence_options = { namespace: "smith" }
+  #
+  # config.persistence_adapter = :solid_cache
+  # config.persistence_options = { namespace: "smith" }
+  #
+  # config.persistence_adapter = :redis
+  # config.persistence_options = {
+  #   redis: Redis.new(url: ENV.fetch("REDIS_URL")),
+  #   namespace: "smith"
+  # }
+  #
+  # config.persistence_adapter = :active_record
+  # config.persistence_options = {
+  #   model: WorkflowState,
+  #   key_column: :key,
+  #   payload_column: :payload
+  # }
+  #
+  # Custom adapters are also supported if they implement:
+  #   store(key, payload)
+  #   fetch(key)
+  #   delete(key)
+
+  # Artifact storage for large outputs
+  config.artifact_store = Smith::Artifacts::Memory.new
+
+  # Trace adapter (Smith::Trace::Memory, Smith::Trace::Logger, Smith::Trace::OpenTelemetry)
+  config.trace_adapter = Smith::Trace::Logger
+
+  # Best-known model-call cost tracking (optional)
+  # config.pricing = {
+  #   "gpt-4.1-nano" => {
+  #     input_cost_per_token: 0.0000001,
+  #     output_cost_per_token: 0.0000004
+  #   }
+  # }
+end

data/lib/smith/agent/lifecycle.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+module Smith
+  class Agent
+    module Lifecycle
+      TRANSIENT_ERRORS = [
+        RubyLLM::ServerError, RubyLLM::ServiceUnavailableError,
+        RubyLLM::OverloadedError, RubyLLM::RateLimitError
+      ].freeze
+
+      private
+
+      def run_after_completion(agent_class, result, context)
+        return result unless agent_class.method_defined?(:after_completion)
+
+        instance = agent_class.allocate
+        instance.after_completion(result, context)
+      end
+
+      def invoke_agent(agent_class, prepared_input)
+        check_deadline!
+        response, model_used = complete_with_provider(agent_class, prepared_input)
+        snapshot_and_finalize(agent_class, response, model_used)
+      end
+
+      # Returns [response, model_used] as local data — no shared mutable
+      # state. Previously this method set `@last_attempt_model` on the
+      # workflow instance and `snapshot_and_finalize` read it back; under
+      # parallel fan-out, two branches sharing the workflow could race
+      # and attribute the wrong model to the wrong response. Local data
+      # eliminates the race entirely.
+      def complete_with_provider(agent_class, prepared_input)
+        models = build_model_chain(agent_class)
+
+        models.each_with_index do |model_id, index|
+          check_deadline! if index.positive?
+          response = attempt_model(agent_class, prepared_input, model_id)
+          return [response, model_id]
+        rescue Smith::Error
+          raise
+        rescue StandardError => e
+          account_failed_attempt(e, model_id, agent_class)
+          raise Smith::AgentError, e.message unless fallback_eligible?(e) && index < models.length - 1
+        end
+      end
+
+      def build_model_chain(agent_class)
+        primary = if agent_class.respond_to?(:model_block) && agent_class.model_block
+          resolve_dynamic_model(agent_class)
+        else
+          agent_class.chat_kwargs[:model]
+        end
+        fallbacks = agent_class.fallback_models || []
+        [primary, *fallbacks].compact
+      end
+
+      # Evaluates a block-form `model` declaration with the workflow's
+      # @context (Hash, defaults to {} when uninitialized). The block
+      # must return a non-empty string model id; any other value
+      # surfaces as Smith::AgentError so the workflow's failure handler
+      # treats it as a step failure rather than a silent miss.
+      def resolve_dynamic_model(agent_class)
+        result = agent_class.model_block.call(@context || {})
+        return result if result.is_a?(String) && !result.empty?
+
+        raise Smith::AgentError,
+              "model block for #{agent_class} must return a non-empty string; got #{result.inspect}"
+      end
+
+      def attempt_model(agent_class, prepared_input, model_id)
+        chat = agent_class.chat(model: model_id, **bridge_workflow_inputs(agent_class))
+        add_prepared_input(chat, prepared_input)
+        chat = chat.with_schema(agent_class.output_schema) if agent_class.output_schema
+        chat.complete
+      end
+
+      # Bridges declared agent `inputs` from the workflow's @context Hash
+      # to the agent invocation kwargs, so block-form RubyLLM DSLs (tools,
+      # instructions, params, headers, schema) can access workflow-context
+      # data via bare method calls on `self` inside the block (RubyLLM
+      # invokes these via `runtime.instance_exec(&block)`, exposing each
+      # declared input as a singleton method on the runtime object).
+      # Smith's own `model` block-form already receives @context directly
+      # via `block.call(@context)`; this bridge gives runtime_context the
+      # same surface for the RubyLLM-owned blocks.
+      #
+      # Bridges ONLY user-declared inputs — reserved names
+      # (Smith::Agent::RESERVED_INPUT_NAMES: model_id, provider,
+      # endpoint_mode) are auto-injected by Smith::Agent.chat from the
+      # resolved profile, NOT from @context. The slice prevents the bridge
+      # from accidentally passing through stale or wrong values that
+      # happen to live in @context under those keys.
+      #
+      # Contract: declared inputs are ALWAYS passed (with nil when absent
+      # from @context). The declaration is the contract — `inputs :form_kind`
+      # promises that `form_kind` will be a callable singleton method on
+      # the runtime regardless of whether @context happens to have a value.
+      # This eliminates `respond_to?` defensiveness in agent blocks and
+      # mirrors the silent-nil semantics agent authors get from `ctx[:k]`
+      # in the model block. Non-Hash @context short-circuits.
+      def bridge_workflow_inputs(agent_class)
+        return {} unless @context.is_a?(Hash)
+
+        declared = agent_class.inputs || []
+        user_declared = declared - Smith::Agent::RESERVED_INPUT_NAMES
+        user_declared.each_with_object({}) do |name, kwargs|
+          kwargs[name] = @context[name]
+        end
+      end
+
+      def add_prepared_input(chat, prepared_input)
+        return unless prepared_input
+
+        system_messages, other_messages = prepared_input.partition do |message|
+          message_role(message) == :system
+        end
+
+        merge_system_messages!(chat, system_messages) if system_messages.any?
+        other_messages.each { |message| chat.add_message(message) }
+      end
+
+      def merge_system_messages!(chat, prepared_system_messages)
+        return prepared_system_messages.each { |message| chat.add_message(message) } unless chat.respond_to?(:messages)
+
+        existing_system_contents = chat.messages.filter_map do |message|
+          message.content if message_role(message) == :system
+        end
+        prepared_system_contents = prepared_system_messages.filter_map do |message|
+          message_content(message)
+        end
+
+        combined_contents = existing_system_contents + prepared_system_contents
+        return if combined_contents.empty?
+        return prepared_system_messages.each { |message| chat.add_message(message) } unless combined_contents.all?(String)
+
+        if chat.respond_to?(:with_instructions)
+          chat.with_instructions(combined_contents.join("\n\n"))
+        else
+          prepared_system_messages.each { |message| chat.add_message(message) }
+        end
+      end
+
+      def message_role(message)
+        if message.respond_to?(:role)
+          message.role&.to_sym
+        else
+          message[:role]&.to_sym
+        end
+      end
+
+      def message_content(message)
+        if message.respond_to?(:content)
+          message.content
+        else
+          message[:content]
+        end
+      end
+
+      def fallback_eligible?(error)
+        TRANSIENT_ERRORS.any? { |klass| error.is_a?(klass) } ||
+          error.is_a?(Faraday::TimeoutError) ||
+          error.is_a?(Faraday::ConnectionFailed)
+      end
+
+      # `agent_class` is now a parameter (was previously implicit via
+      # `@last_attempt_model`-only path). The caller (`complete_with_provider`)
+      # has the local already, so no shared mutable state is needed.
+      # Records the failed attempt's tokens via the unified `record_usage`
+      # helper, marking the entry as `:failed_attempt`.
+      def account_failed_attempt(error, model_id, agent_class)
+        return unless error.respond_to?(:input_tokens) && error.respond_to?(:output_tokens)
+
+        input = error.input_tokens
+        output = error.output_tokens
+        return unless input.is_a?(Integer) && output.is_a?(Integer)
+
+        cost = Smith::Pricing.compute_cost(model: model_id, input_tokens: input, output_tokens: output)
+        agent_result = Workflow::AgentResult.new(
+          content: nil, input_tokens: input, output_tokens: output, cost: cost, model_used: model_id
+        )
+        record_usage(agent_class, agent_result, :failed_attempt, model_id)
+      end
+
+      def snapshot_and_finalize(agent_class, response, model_used)
+        agent_result = Workflow::AgentResult.from_response(response, response&.content, model_used: model_used)
+        Thread.current[:smith_last_agent_result] = agent_result
+        emit_token_usage(agent_result)
+        compute_agent_cost(agent_result)
+        record_usage(agent_class, agent_result, :completed_attempt, agent_result.model_used)
+
+        agent_result.content = run_after_completion(agent_class, agent_result.content, @context)
+        raise_blank_output!(agent_class, agent_result)
+        agent_result
+      end
+
+      def raise_blank_output!(agent_class, agent_result)
+        return unless blank_agent_output?(agent_result.content)
+
+        raise Smith::BlankAgentOutputError.new(
+          agent_name: agent_class.register_as,
+          model_used: agent_result.model_used
+        )
+      end
+
+      def blank_agent_output?(content)
+        return true if content.nil?
+        return content.strip.empty? if content.is_a?(String)
+
+        false
+      end
+
+      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 }
+        )
+      end
+
+      def compute_agent_cost(agent_result)
+        return unless agent_result.usage_known?
+
+        model = agent_result.model_used
+        agent_result.cost = Smith::Pricing.compute_cost(
+          model: model, input_tokens: agent_result.input_tokens, output_tokens: agent_result.output_tokens
+        )
+      end
+
+      # Single critical section: all three of `@total_tokens`,
+      # `@total_cost`, and `@usage_entries` update under one mutex
+      # acquisition. Replaces the prior `accumulate_usage` which took
+      # the mutex twice (once for tokens, once for cost) — under
+      # parallel fan-out two branches could interleave between those
+      # blocks, leaving totals momentarily inconsistent. Adding the
+      # entry append in a third pass would have widened the window;
+      # one pass closes it entirely.
+      #
+      # `@usage_mutex` is eagerly initialized in `Workflow#initialize`
+      # AND `Workflow#restore_state` (since `from_state` allocates
+      # without `initialize`), so it's always present here.
+      def record_usage(agent_class, agent_result, attempt_kind, model_id)
+        return unless agent_result.usage_known?
+
+        entry = Workflow::UsageEntry.new(
+          usage_id: SecureRandom.uuid,
+          agent_name: agent_class.register_as,
+          model: model_id,
+          input_tokens: agent_result.input_tokens,
+          output_tokens: agent_result.output_tokens,
+          cost: agent_result.cost,
+          attempt_kind: attempt_kind,
+          recorded_at: Time.now.utc.iso8601
+        )
+
+        @usage_mutex.synchronize do
+          @total_tokens = (@total_tokens || 0) + agent_result.input_tokens + agent_result.output_tokens
+          @total_cost   = (@total_cost   || 0.0) + (agent_result.cost || 0.0)
+          @usage_entries << entry
+        end
+      end
+    end
+  end
+end

data/lib/smith/agent/registry.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "dry-container"
+require "monitor"
+
+module Smith
+  class Agent
+    module Registry
+      extend Dry::Container::Mixin
+
+      def self.normalize_key(name)
+        name.to_s
+      end
+
+      def self.find(name)
+        registry_monitor.synchronize do
+          key = normalize_key(name)
+          key?(key) ? resolve(key) : nil
+        end
+      end
+
+      # Override Dry::Container::Mixin#register to route agent classes
+      # through ensure_registered while preserving full generic container
+      # semantics (block, options) for non-agent registrations.
+      def self.register(key, contents = nil, options = {}, &block)
+        if block_given? || !(contents.is_a?(Class) && contents <= Smith::Agent)
+          registry_monitor.synchronize { super(key, contents, options, &block) }
+        else
+          ensure_registered(key, contents)
+        end
+      end
+
+      def self.delete(name)
+        registry_monitor.synchronize do
+          _container.delete(normalize_key(name))
+        end
+      end
+
+      def self.clear!
+        registry_monitor.synchronize do
+          @_container&.clear
+        end
+      end
+
+      def self.ensure_registered(name, klass)
+        validate_agent_class!(klass)
+        key = normalize_key(name)
+
+        registry_monitor.synchronize do
+          existing = key?(key) ? resolve(key) : nil
+
+          if existing.nil?
+            register_unchecked!(key, klass)
+          elsif existing.equal?(klass)
+            # same object — no-op
+          elsif stale_reload_binding?(existing, klass)
+            # same class name, different object — Rails reload case
+            _container.delete(key)
+            register_unchecked!(key, klass)
+          else
+            raise Smith::AgentRegistryError,
+                  "agent registry collision for key #{key.inspect}: " \
+                  "already registered to #{binding_label(existing)}, " \
+                  "cannot replace with #{binding_label(klass)}"
+          end
+
+          klass
+        end
+      end
+
+      def self.fetch!(name, workflow_class: nil, transition_name: nil, role: :agent)
+        registry_monitor.synchronize do
+          key = normalize_key(name)
+          return resolve(key) if key?(key)
+
+          details = []
+          details << "workflow #{workflow_class}" if workflow_class
+          details << "transition :#{transition_name}" if transition_name
+          suffix = details.empty? ? "" : " for #{details.join(', ')}"
+
+          raise Smith::WorkflowError, "unresolved #{role} :#{key}#{suffix}"
+        end
+      end
+
+      # Re-entrant lock (Monitor, not Mutex) so block-backed resolve
+      # inside find/fetch! can safely re-enter the registry without
+      # deadlocking on the same thread.
+      def self.registry_monitor
+        @_registry_monitor ||= Monitor.new
+      end
+
+      def self.validate_agent_class!(klass)
+        return if klass.is_a?(Class) && klass <= Smith::Agent
+
+        raise Smith::AgentRegistryError,
+              "expected a Smith::Agent subclass, got #{klass.inspect}"
+      end
+
+      # Safe label for collision error messages. Handles both classes
+      # (which respond to .name) and plain values (which do not).
+      def self.binding_label(value)
+        if value.respond_to?(:name) && value.name.is_a?(String) && !value.name.empty?
+          value.name
+        else
+          value.inspect
+        end
+      end
+      private_class_method :binding_label
+
+      # Private raw registration that bypasses ensure_registered.
+      # Used internally to avoid recursion/deadlock.
+      # Caller MUST already hold registry_monitor.
+      def self.register_unchecked!(key, klass)
+        config.registry.call(_container, key, klass, {})
+      end
+      private_class_method :register_unchecked!
+
+      def self.stale_reload_binding?(existing, klass)
+        existing_name = existing.respond_to?(:name) ? existing.name : nil
+        klass_name = klass.name
+        existing_name.is_a?(String) && !existing_name.empty? &&
+          klass_name.is_a?(String) && !klass_name.empty? &&
+          existing_name == klass_name
+      end
+      private_class_method :stale_reload_binding?
+    end
+  end
+end