smith-agents 0.4.0

data/lib/smith/context.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Smith
+  class Context
+    class << self
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@session_strategy, @session_strategy)
+        subclass.instance_variable_set(:@persist_keys, (@persist_keys || []).dup)
+        subclass.instance_variable_set(:@persist_mode, @persist_mode || :explicit)
+        subclass.instance_variable_set(:@persist_auto_seed, (@persist_auto_seed || []).dup)
+        subclass.instance_variable_set(:@inject_state, @inject_state)
+      end
+
+      def session_strategy(strategy = nil, **opts)
+        return @session_strategy if strategy.nil?
+
+        @session_strategy = { strategy: strategy, **opts }
+      end
+
+      def persist(*keys, also: nil)
+        if keys.empty? && also.nil?
+          return @persist_keys || []
+        end
+
+        if also && !keys.include?(:auto)
+          raise Smith::WorkflowError, ":also is only valid alongside :auto"
+        end
+
+        if keys.include?(:auto)
+          other_keys = keys.reject { |k| k == :auto }
+          unless other_keys.empty?
+            raise Smith::WorkflowError, "persist :auto must be the sole positional argument; got #{other_keys.inspect}"
+          end
+          @persist_mode = :auto
+          @persist_keys = []
+          @persist_auto_seed = Array(also).map(&:to_sym)
+          return @persist_auto_seed.dup
+        end
+
+        @persist_mode = :explicit
+        @persist_keys ||= []
+        @persist_keys.concat(keys)
+      end
+
+      def persist_mode
+        @persist_mode || :explicit
+      end
+
+      def persist_auto_seed
+        @persist_auto_seed || []
+      end
+
+      def inject_state(&block)
+        return @inject_state unless block_given?
+
+        @inject_state = block
+      end
+    end
+  end
+end

data/lib/smith/doctor/check.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Smith
+  module Doctor
+    Check = Data.define(:name, :status, :message, :detail) do
+      def pass?  = status == :pass
+      def fail?  = status == :fail
+      def warn?  = status == :warn
+      def skip?  = status == :skip
+    end
+  end
+end

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Smith
+  module Doctor
+    module Checks
+      module Baseline
+        def self.run(report)
+          check_smith_loads(report)
+          check_ruby_version(report)
+          check_ruby_llm_loads(report)
+          check_concurrent_loads(report)
+          check_configure(report)
+          check_minimal_workflow(report)
+        end
+
+        def self.check_smith_loads(report)
+          report.add(
+            name: "baseline.smith_loads",
+            status: defined?(::Smith) ? :pass : :fail,
+            message: defined?(::Smith) ? "smith loads" : "smith failed to load",
+            detail: defined?(::Smith) ? nil : "Ensure smith is in your Gemfile and bundle install has been run"
+          )
+        end
+
+        def self.check_ruby_version(report)
+          satisfied = Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.2.0")
+          report.add(
+            name: "baseline.ruby_version",
+            status: satisfied ? :pass : :fail,
+            message: satisfied ? "Ruby #{RUBY_VERSION}" : "Ruby #{RUBY_VERSION} is below minimum 3.2.0",
+            detail: satisfied ? nil : "Smith requires Ruby >= 3.2.0"
+          )
+        end
+
+        def self.check_ruby_llm_loads(report)
+          loaded = defined?(::RubyLLM)
+          report.add(
+            name: "baseline.ruby_llm_loads",
+            status: loaded ? :pass : :fail,
+            message: loaded ? "ruby_llm loads" : "ruby_llm failed to load",
+            detail: loaded ? nil : "Ensure ruby_llm is in your Gemfile"
+          )
+        end
+
+        def self.check_concurrent_loads(report)
+          loaded = defined?(::Concurrent)
+          report.add(
+            name: "baseline.concurrent_loads",
+            status: loaded ? :pass : :fail,
+            message: loaded ? "concurrent-ruby loads" : "concurrent-ruby failed to load",
+            detail: loaded ? nil : "Ensure concurrent-ruby is in your Gemfile"
+          )
+        end
+
+        def self.check_configure(report)
+          callable = ::Smith.respond_to?(:configure) && ::Smith.respond_to?(:config)
+          report.add(
+            name: "baseline.configure",
+            status: callable ? :pass : :fail,
+            message: callable ? "Smith.configure callable" : "Smith.configure not available"
+          )
+        end
+
+        def self.check_minimal_workflow(report)
+          workflow_class = Class.new(::Smith::Workflow) do
+            initial_state :idle
+            state :done
+            transition :check, from: :idle, to: :done
+          end
+          booted = workflow_class.new.state == :idle
+
+          report.add(
+            name: "baseline.minimal_workflow",
+            status: booted ? :pass : :fail,
+            message: booted ? "Minimal workflow boots" : "Minimal workflow failed to initialize"
+          )
+        rescue StandardError => e
+          report.add(name: "baseline.minimal_workflow", status: :fail, message: "Minimal workflow failed",
+                     detail: e.message)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Smith
+  module Doctor
+    module Checks
+      module Configuration
+        def self.run(report)
+          check_logger(report)
+          check_artifact_store(report)
+          check_trace_adapter(report)
+          check_pricing(report)
+        end
+
+        def self.check_logger(report)
+          configured = !::Smith.config.logger.nil?
+          report.add(
+            name: "config.logger",
+            status: configured ? :pass : :warn,
+            message: configured ? "Logger configured" : "No logger configured",
+            detail: configured ? nil : "Set config.logger for Smith runtime logging"
+          )
+        end
+
+        def self.check_artifact_store(report)
+          configured = !::Smith.config.artifact_store.nil?
+          report.add(
+            name: "config.artifact_store",
+            status: configured ? :pass : :warn,
+            message: configured ? "Artifact store configured" : "No artifact store configured",
+            detail: configured ? nil : "Large outputs will use in-memory default"
+          )
+        end
+
+        def self.check_trace_adapter(report)
+          configured = !::Smith.config.trace_adapter.nil?
+          report.add(
+            name: "config.trace_adapter",
+            status: configured ? :pass : :warn,
+            message: configured ? "Trace adapter configured" : "No trace adapter configured",
+            detail: configured ? nil : "Traces will be discarded"
+          )
+        end
+
+        def self.check_pricing(report)
+          configured = ::Smith.config.pricing.is_a?(Hash) && !::Smith.config.pricing.empty?
+          report.add(
+            name: "config.pricing",
+            status: configured ? :pass : :warn,
+            message: configured ? "Pricing configured" : "No pricing configured",
+            detail: configured ? nil : "RunResult.total_cost will be 0.0"
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Smith
+  module Doctor
+    module Checks
+      module Durability
+        PROBE_KEY = "smith_doctor_probe"
+
+        def self.run(report)
+          raw_adapter = ::Smith.config.persistence_adapter
+          unless raw_adapter
+            report.add(
+              name: "durability.adapter",
+              status: :warn,
+              message: "No persistence adapter configured",
+              detail: "Set config.persistence_adapter to :rails_cache, :active_record, :redis, :cache_store, or a custom adapter"
+            )
+            return
+          end
+
+          adapter = ::Smith.persistence_adapter
+          add_backend_warning(report, adapter)
+        rescue StandardError => e
+          report.add(
+            name: "durability.adapter",
+            status: :fail,
+            message: "Persistence adapter configuration is invalid",
+            detail: e.message
+          )
+          return
+        else
+          check_persist_and_restore(report, adapter)
+          check_resume_after_restore(report, adapter)
+        end
+
+        def self.check_persist_and_restore(report, adapter)
+          workflow_class = build_probe_class
+          payload = JSON.generate(workflow_class.new.to_state)
+
+          adapter.store(PROBE_KEY, payload)
+          restored_payload = adapter.fetch(PROBE_KEY)
+          restored = workflow_class.from_state(JSON.parse(restored_payload))
+          adapter.delete(PROBE_KEY)
+
+          valid = restored.state == :idle
+          report.add(
+            name: "durability.persist_restore",
+            status: valid ? :pass : :fail,
+            message: valid ? "Host persistence round-trip works" : "Host persistence round-trip failed"
+          )
+        rescue StandardError => e
+          report.add(
+            name: "durability.persist_restore", status: :fail,
+            message: "Host persistence round-trip failed", detail: e.message
+          )
+        end
+
+        def self.check_resume_after_restore(report, adapter)
+          workflow_class = build_probe_class
+          payload = JSON.generate(workflow_class.new.to_state)
+
+          adapter.store(PROBE_KEY, payload)
+          restored_payload = adapter.fetch(PROBE_KEY)
+          restored = workflow_class.from_state(JSON.parse(restored_payload))
+          adapter.delete(PROBE_KEY)
+
+          result = restored.run!
+          valid = result.state == :done
+
+          report.add(
+            name: "durability.resume_after_restore",
+            status: valid ? :pass : :fail,
+            message: valid ? "Restored workflow resumes correctly" : "Restored workflow did not reach terminal state"
+          )
+        rescue StandardError => e
+          report.add(name: "durability.resume_after_restore", status: :fail,
+                     message: "Resume after restore failed", detail: e.message)
+        end
+
+        def self.build_probe_class
+          Class.new(::Smith::Workflow) do
+            initial_state :idle
+            state :done
+            transition :finish, from: :idle, to: :done
+          end
+        end
+
+        def self.add_backend_warning(report, adapter)
+          warning = adapter.respond_to?(:durability_warning) ? adapter.durability_warning : nil
+          return unless warning
+
+          report.add(
+            name: "durability.backend",
+            status: :warn,
+            message: warning
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Smith
+  module Doctor
+    module Checks
+      module Live
+        def self.run(report)
+          check_provider_config(report)
+          check_model_call(report)
+        end
+
+        def self.check_provider_config(report)
+          configured = ruby_llm_configured?
+          report.add(
+            name: "live.provider_config",
+            status: configured ? :pass : :warn,
+            message: configured ? "RubyLLM provider configured" : "No RubyLLM provider credentials detected",
+            detail: configured ? nil : "Configure RubyLLM or set a provider API key env var"
+          )
+        end
+
+        def self.check_model_call(report)
+          attempt_model_call(report)
+        end
+
+        def self.attempt_model_call(report)
+          response = ::RubyLLM.chat.ask("Respond with exactly: ok")
+          has_content = response.respond_to?(:content) && !response.content.nil?
+          report.add(
+            name: "live.model_call",
+            status: has_content ? :pass : :fail,
+            message: has_content ? "Live model call succeeded" : "Live model call returned no content"
+          )
+        rescue StandardError => e
+          report.add(name: "live.model_call", status: :fail, message: "Live model call failed", detail: e.message)
+        end
+
+        def self.ruby_llm_configured?
+          config = ::RubyLLM.config
+          return true if present?(config.openai_api_key)
+          return true if present?(config.anthropic_api_key)
+          return true if present?(config.gemini_api_key)
+
+          false
+        rescue StandardError
+          false
+        end
+
+        def self.present?(value)
+          value.is_a?(String) && !value.empty?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Smith
+  module Doctor
+    module Checks
+      # Validates that every registered agent's resolved model has either:
+      #   (a) an explicit application-side Smith::Models.register override, OR
+      #   (b) a matching Smith::Models::Inference rule (library-shipped).
+      #
+      # If neither, the model gets safe defaults (no thinking, accepts temp,
+      # no tool routing) which may silently degrade behavior. Reports the
+      # uncovered models so hosts know to register overrides or rely on
+      # the safe defaults knowingly.
+      module ModelsRegistry
+        module_function
+
+        def run(report)
+          uncovered = uncovered_models
+          if uncovered.empty?
+            report.add(
+              name: "models.coverage",
+              status: :pass,
+              message: "All registered agents have model profiles or matching inference rules"
+            )
+          else
+            report.add(
+              name: "models.coverage",
+              status: :warn,
+              message: "#{uncovered.size} agent model(s) without explicit profile or matching inference rule",
+              detail: "Uncovered: #{uncovered.join(", ")}. These models will get safe defaults " \
+                      "(no thinking, accepts temperature, no tool routing). Either register an " \
+                      "explicit Smith::Models::Profile via Smith::Models.register, OR add an " \
+                      "Inference rule via Smith::Models::Inference.prepend_rule if the model " \
+                      "fits an existing provider pattern."
+            )
+          end
+        end
+
+        # Walk Smith::Agent::Registry. For each agent, extract the model
+        # id from chat_kwargs (static `model "..."` form). Block-form
+        # `model do |ctx| ... end` agents are skipped because their
+        # model is resolved per-attempt and can't be enumerated at boot.
+        # Check whether find_or_infer returns a custom (non-default)
+        # Profile — meaning either an explicit override or an inference
+        # rule matched.
+        def uncovered_models
+          return [] unless defined?(Smith::Agent::Registry)
+
+          model_ids = []
+          Smith::Agent::Registry.each do |_key, agent|
+            next unless agent.is_a?(Class)
+            next unless agent.respond_to?(:chat_kwargs)
+
+            id = agent.chat_kwargs[:model]
+            model_ids << id if id
+          end
+
+          model_ids.uniq.reject do |model_id|
+            Smith::Models.find(model_id) ||
+              (defined?(Smith::Models::Inference) && Smith::Models::Inference.profile_for(model_id))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Smith
+  module Doctor
+    module Checks
+      # Validates that Smith.config.openai_api_mode is one of the allowed
+      # values (:off | :auto). Also surfaces whether the
+      # Smith::Providers::OpenAI::Responses adapter is loaded when mode
+      # is :auto — if not, gpt-5 family + tools + thinking would raise
+      # NotImplementedError at runtime.
+      module OpenaiApiMode
+        module_function
+
+        def run(report)
+          mode = Smith.config.openai_api_mode
+          unless %i[off auto].include?(mode)
+            report.add(
+              name: "config.openai_api_mode",
+              status: :fail,
+              message: "openai_api_mode = #{mode.inspect} (invalid)",
+              detail: "Must be :off or :auto"
+            )
+            return
+          end
+
+          if mode == :auto && !responses_adapter_loaded?
+            report.add(
+              name: "config.openai_api_mode",
+              status: :warn,
+              message: "openai_api_mode = :auto but Smith::Providers::OpenAI::Responses is not vendored",
+              detail: "When (gpt-5 family + tools + thinking) is detected, the routing path " \
+                      "raises NotImplementedError. Either: (a) set openai_api_mode = :off to fall " \
+                      "back to graceful tool-dropping, or (b) vendor the Responses adapter (PR #770 " \
+                      "on crmne/ruby_llm tracks the upstream effort)."
+            )
+          else
+            report.add(
+              name: "config.openai_api_mode",
+              status: :pass,
+              message: "openai_api_mode = #{mode.inspect}"
+            )
+          end
+        end
+
+        def responses_adapter_loaded?
+          defined?(Smith::Providers::OpenAI::Responses)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "persistence_registry"
+
+module Smith
+  module Doctor
+    module Checks
+      module Persistence
+        def self.run(report)
+          check_active_record(report)
+          check_db_connection(report)
+          check_ruby_llm_persistence(report)
+          check_schema_presence(report)
+          PersistenceRegistry.check(report, ::Smith.config.ruby_llm_model_registry)
+        end
+
+        def self.check_active_record(report)
+          loaded = defined?(::ActiveRecord::Base)
+          report.add(
+            name: "persistence.active_record",
+            status: loaded ? :pass : :fail,
+            message: loaded ? "ActiveRecord available" : "ActiveRecord not available"
+          )
+        end
+
+        def self.check_db_connection(report)
+          unless defined?(::ActiveRecord::Base)
+            report.add(name: "persistence.db_connection", status: :skip, message: "DB check skipped — no ActiveRecord")
+            return
+          end
+
+          verify_active_connection(report)
+        end
+
+        def self.check_ruby_llm_persistence(report)
+          detected = ruby_llm_persistence_detected?
+          report.add(
+            name: "persistence.ruby_llm_surface",
+            status: detected ? :pass : :warn,
+            message: detected ? "RubyLLM persistence surface detected" : "RubyLLM persistence surface not detected",
+            detail: detected ? nil : "RubyLLM may be running in memory-only mode"
+          )
+        end
+
+        def self.check_schema_presence(report)
+          unless defined?(::ActiveRecord::Base)
+            report.add(
+              name: "persistence.schema_presence", status: :skip, message: "Schema check skipped — no ActiveRecord"
+            )
+            return
+          end
+
+          inspect_tables(report)
+        end
+
+        def self.check_model_registry_mode(report)
+          PersistenceRegistry.check(report, ::Smith.config.ruby_llm_model_registry)
+        end
+
+        def self.verify_active_connection(report)
+          active = ::ActiveRecord::Base.connection.active?
+          report.add(
+            name: "persistence.db_connection",
+            status: active ? :pass : :fail,
+            message: active ? "Database connection active" : "Database connection failed"
+          )
+        rescue StandardError => e
+          report.add(name: "persistence.db_connection", status: :fail, message: "Database connection failed",
+                     detail: e.message)
+        end
+
+        def self.ruby_llm_persistence_detected?
+          return false unless defined?(::RubyLLM::Chat)
+
+          ::RubyLLM::Chat.ancestors.any? { |a| a.name&.include?("ActiveRecord") }
+        rescue StandardError
+          false
+        end
+
+        def self.inspect_tables(report)
+          tables = ::ActiveRecord::Base.connection.tables
+          known = tables.select { |t| %w[chats messages tool_calls].include?(t) }
+
+          if known.any?
+            report.add(name: "persistence.schema_presence", status: :pass,
+                       message: "RubyLLM tables found: #{known.join(", ")}")
+          else
+            report.add(name: "persistence.schema_presence", status: :warn,
+                       message: "No RubyLLM persistence tables detected (heuristic)",
+                       detail: "Expected tables like chats, messages, or tool_calls")
+          end
+        rescue StandardError => e
+          report.add(name: "persistence.schema_presence", status: :warn,
+                     message: "Schema check inconclusive", detail: e.message)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Smith
+  module Doctor
+    module Checks
+      # Reports which optional capabilities the configured persistence
+      # adapter supports. Hosts who depend on optimistic locking but
+      # configure a cache-backed adapter (CacheStore / RailsCache) need
+      # to know up front that store_versioned silently falls back to
+      # plain store. Workflow#persist! warns once per adapter class
+      # per Smith boot, but doctor surfaces it eagerly.
+      module PersistenceCapabilities
+        module_function
+
+        OPTIONAL_CAPABILITIES = %i[store_versioned].freeze
+
+        def run(report)
+          adapter = resolve_adapter
+          if adapter.nil?
+            report.add(
+              name: "persistence.capabilities",
+              status: :warn,
+              message: "No persistence adapter configured",
+              detail: "Smith.config.persistence_adapter is nil and Smith.config.test_mode is false. " \
+                      "Hosts using durable workflows must set persistence_adapter."
+            )
+            return
+          end
+
+          missing = OPTIONAL_CAPABILITIES.reject { |cap| Smith::PersistenceAdapters.supports?(adapter, cap) }
+
+          if missing.empty?
+            report.add(
+              name: "persistence.capabilities",
+              status: :pass,
+              message: "#{adapter.class.name} supports all optional persistence capabilities",
+              detail: "Supported: #{OPTIONAL_CAPABILITIES.join(', ')}"
+            )
+          else
+            report.add(
+              name: "persistence.capabilities",
+              status: :warn,
+              message: "#{adapter.class.name} missing optional capabilities: #{missing.join(', ')}",
+              detail: "Workflows using these capabilities fall back to non-versioned writes " \
+                      "with a one-time warning per adapter class. Switch to RedisStore, " \
+                      "ActiveRecordStore (with lock_version column), or the Memory adapter " \
+                      "for full coverage."
+            )
+          end
+        end
+
+        def resolve_adapter
+          Smith.persistence_adapter
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end