smith-agents 0.10.0 → 0.12.0

data/lib/smith/context/state_injection.rb

@@ -6,19 +6,34 @@ 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
+        existing_index = messages.index { |message| injected_state?(message) }
 
-        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
+
+      # Only a system message carries the marker: hosts cannot admit system
+      # messages, so a user, assistant or tool message that starts with the
+      # marker is content, never Smith's injected state.
+      def self.injected_state?(message)
+        content = message[:content] || message["content"]
+        (message[:role] || message["role"]).to_s == "system" && content.is_a?(String) && content.start_with?(MARKER)
+      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, :injected_state?
     end
   end
 end

data/lib/smith/context.rb

@@ -10,6 +10,7 @@ module Smith
         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)
+        subclass.instance_variable_set(:@untrusted_keys, (@untrusted_keys || []).dup)
       end
 
       def session_strategy(strategy = nil, **opts)
@@ -23,6 +24,7 @@ module Smith
           return @persist_keys || []
         end
 
+        validate_persist_keys!(keys)
         if also && !keys.include?(:auto)
           raise Smith::WorkflowError, ":also is only valid alongside :auto"
         end
@@ -47,10 +49,36 @@ module Smith
         @persist_mode || :explicit
       end
 
+      def validate_persist_keys!(keys)
+        invalid = keys.grep_v(Symbol)
+        return if invalid.empty?
+
+        raise Smith::WorkflowError, "persist keys must be Symbols, got #{invalid.map(&:inspect).join(", ")}"
+      end
+      private :validate_persist_keys!
+
       def persist_auto_seed
         @persist_auto_seed || []
       end
 
+      # Keys whose values come from outside the system (a fetched document,
+      # an inbound message), or that a step derived from such a value:
+      # `inject_state` formatters and the `seed_messages` builder never
+      # receive them, and an agent that names one in `inputs` is refused,
+      # in this workflow and in any workflow it nests.
+      def untrusted(*keys)
+        return untrusted_keys if keys.empty?
+
+        validate_persist_keys!(keys)
+        raise Smith::WorkflowError, "untrusted takes context keys, not :auto" if keys.include?(:auto)
+
+        @untrusted_keys = (untrusted_keys + keys).uniq
+      end
+
+      def untrusted_keys
+        @untrusted_keys || []
+      end
+
       def inject_state(&block)
         return @inject_state unless block_given?
 

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/artifacts.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+
+module Smith
+  module Doctor
+    module Checks
+      # The artifact store: configured, buildable, usable, and as durable as
+      # the workflow state, since a run that waits, retries or resumes in
+      # another process reads its artifacts there.
+      module Artifacts
+        PROCESS_LOCAL = %w[Smith::Artifacts::Memory].freeze
+        COLUMNS = %w[ref data content_type execution_namespace created_at].freeze
+
+        def self.run(report)
+          raw = ::Smith.config.artifact_store
+          return report.add(**missing) if raw.nil? && !::Smith.config.test_mode
+
+          store = ::Smith.artifact_backend
+          report.add(name: "artifacts.store", status: :pass, message: "Artifact store: #{store_name(store)}")
+          check_usable(report, store)
+          check_durability(report, store)
+          check_ownership(report, store)
+        rescue StandardError => e
+          report.add(name: "artifacts.store", status: :fail, message: "Artifact store configuration is invalid",
+                     detail: e.message)
+        end
+
+        def self.store_name(store) = store.is_a?(Module) ? store.name : store.class.name
+
+        def self.missing
+          { name: "artifacts.store", status: :warn, message: "No artifact store configured",
+            detail: "Set config.artifact_store to :s3 (S3, R2), :active_record, :file, or a store, with " \
+                    "config.artifact_options; steps that store artifacts or read documents fail without one" }
+        end
+
+        # The table an Active Record store writes, the directory a File
+        # store writes, the bucket an S3 store writes.
+        def self.check_usable(report, store)
+          problem = case store
+                    when ::Smith::Artifacts::ActiveRecordStore then table_problem(store)
+                    when ::Smith::Artifacts::File then directory_problem(store)
+                    when ::Smith::Artifacts::S3 then bucket_problem(store)
+                    end
+          return unless problem
+
+          report.add(name: "artifacts.usable", status: :warn, message: "The artifact store cannot be used",
+                     detail: problem)
+        end
+
+        def self.table_problem(store)
+          missing = COLUMNS - store.model.column_names
+          "#{store.model.name} lacks the columns #{missing.join(", ")}" if missing.any?
+        rescue StandardError => e
+          "the store's model cannot be loaded: #{e.message}"
+        end
+
+        def self.directory_problem(store)
+          dir = store.instance_variable_get(:@dir)
+          "the directory #{dir} is not writable" unless ::File.directory?(dir) && ::File.writable?(dir)
+        end
+
+        def self.bucket_problem(store)
+          client = store.instance_variable_get(:@client)
+          return unless client.respond_to?(:head_bucket)
+
+          client.head_bucket(bucket: store.instance_variable_get(:@bucket))
+          nil
+        rescue StandardError => e
+          "the bucket cannot be reached: #{e.class.name}"
+        end
+
+        def self.check_durability(report, store)
+          adapter = ::Smith.config.persistence_adapter
+          return unless PROCESS_LOCAL.include?(store.class.name) && adapter && !process_local_state?(adapter)
+
+          report.add(
+            name: "artifacts.durability", status: :warn,
+            message: "Artifacts are kept in process memory while workflow state is persisted",
+            detail: "A run that waits, retries or resumes in another process loses its artifacts; configure :s3, " \
+                    ":active_record or :file"
+          )
+        end
+
+        def self.process_local_state?(adapter)
+          adapter.to_s == "memory" || adapter.is_a?(::Smith::PersistenceAdapters::Memory)
+        end
+
+        def self.check_ownership(report, store)
+          return if store.respond_to?(:stored_by?)
+
+          report.add(
+            name: "artifacts.ownership", status: :warn,
+            message: "The artifact store cannot tell which run stored a ref (stored_by?)",
+            detail: "Runs read any ref under their prefix, and content parts cannot read documents from it"
+          )
+        end
+        private_class_method :store_name, :missing, :check_usable, :table_problem, :directory_problem, :bucket_problem,
+                             :check_durability, :process_local_state?, :check_ownership
+      end
+    end
+  end
+end

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

@@ -6,7 +6,6 @@ module Smith
       module Configuration
         def self.run(report)
           check_logger(report)
-          check_artifact_store(report)
           check_trace_adapter(report)
           check_pricing(report)
         end
@@ -21,16 +20,6 @@ module Smith
           )
         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(

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

@@ -31,24 +31,34 @@ module Smith
           )
           return
         else
+          check_ttl_support(report, adapter)
           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)
+        # 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)
 
-          adapter.store(PROBE_KEY, payload)
-          restored_payload = adapter.fetch(PROBE_KEY)
-          restored = workflow_class.from_state(JSON.parse(restored_payload))
-          adapter.delete(PROBE_KEY)
+          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)
+          restored = probe_round_trip(adapter)
           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"
+            message: valid ? "Host persistence round-trip works" : "Host persistence round-trip failed",
+            detail: "Written as runs write, with #{probe_write(adapter)}"
           )
         rescue StandardError => e
           report.add(
@@ -58,15 +68,7 @@ module Smith
         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!
+          result = probe_round_trip(adapter).run!
           valid = result.state == :done
 
           report.add(
@@ -79,6 +81,22 @@ module Smith
                      message: "Resume after restore failed", detail: e.message)
         end
 
+        # A probe run stored as runs are (Workflow#persist!: store_versioned
+        # where the adapter has it, and persistence_max_bytes) and restored.
+        def self.probe_round_trip(adapter)
+          workflow_class = build_probe_class
+          adapter.delete(PROBE_KEY)
+          workflow_class.new.persist!(PROBE_KEY, adapter:)
+          workflow_class.restore(PROBE_KEY, adapter:)
+        ensure
+          adapter.delete(PROBE_KEY)
+        end
+
+        def self.probe_write(adapter)
+          versioned = ::Smith::PersistenceAdapters.supports?(adapter, :store_versioned)
+          versioned ? "store_versioned" : "plain store (the adapter has no store_versioned)"
+        end
+
         def self.build_probe_class
           Class.new(::Smith::Workflow) do
             initial_state :idle

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/doctor/checks/state_model.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Smith
+  module Doctor
+    module Checks
+      # Whether an ActiveRecord persistence adapter's model can hold runs:
+      # its locking column, a text payload, and a string key the database
+      # keeps unique. It reads schema metadata only, and skips when the
+      # database cannot be reached (the default doctor run is offline).
+      # Other adapters, and an adapter configuration that does not resolve
+      # (Durability reports it), are not checked.
+      module StateModel
+        NAME = "persistence.state_model"
+
+        module_function
+
+        def run(report)
+          adapter = active_record_adapter
+          return unless adapter
+
+          adapter.check_schema!
+          report.add(name: NAME, status: :pass,
+                     message: "The workflow state model has a lock_version, a text payload and a unique key")
+          report_encryption(report) if adapter.encrypted_payload?
+        rescue StandardError => e
+          report_failure(report, e)
+        end
+
+        def report_failure(report, error)
+          if unreachable?(error)
+            report.add(name: NAME, status: :skip, detail: error.class.name,
+                       message: "The workflow state model was not checked: the database could not be reached")
+          else
+            report.add(name: NAME, status: :fail, message: "The workflow state model cannot hold runs",
+                       detail: error.message)
+          end
+        end
+
+        def report_encryption(report)
+          report.add(name: "#{NAME}.encryption", status: :warn,
+                     message: "The workflow state payload is encrypted",
+                     detail: "Runs store and read it, but split-step exact writes (replace_exact) compare " \
+                             "payloads in the database and cannot use an encrypted one")
+        end
+
+        def unreachable?(error)
+          classes = PersistenceAdapters::ActiveRecordConnectionErrors.classes
+          classes << ::ActiveRecord::NoDatabaseError if defined?(::ActiveRecord::NoDatabaseError)
+          classes.any? { error.is_a?(_1) }
+        end
+
+        def active_record_adapter
+          return unless ::Smith.config.persistence_adapter
+
+          adapter = ::Smith.persistence_adapter
+          adapter if adapter.is_a?(::Smith::PersistenceAdapters::ActiveRecordStore)
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/smith/doctor/installer.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "erb"
 require "fileutils"
 
 module Smith
@@ -41,8 +42,9 @@ module Smith
       end
 
       def rails_template
+        # The generator's initializer, as `rails g smith:install --skip-state-model` writes it.
         template_path = File.expand_path("../../generators/smith/install/templates/smith.rb.tt", __dir__)
-        File.read(template_path)
+        ERB.new(File.read(template_path), trim_mode: "-").result_with_hash(options: { skip_state_model: true })
       end
 
       def plain_template
@@ -78,7 +80,12 @@ module Smith
             #   store(key, payload)
             #   fetch(key)
             #   delete(key)
-            config.artifact_store = Smith::Artifacts::Memory.new
+            #
+            # Artifacts (large outputs, attached documents) need a store that
+            # outlives the process: :s3 (S3, R2) or :active_record, with
+            # config.artifact_options; :memory keeps them in this process.
+            # config.artifact_store = :s3
+            # config.artifact_options = { bucket: "smith-artifacts", region: "us-east-1" }
             config.trace_adapter = Smith::Trace::Memory.new
           end
         RUBY

data/lib/smith/doctor.rb

@@ -15,6 +15,8 @@ require_relative "doctor/checks/live"
 require_relative "doctor/checks/models_registry"
 require_relative "doctor/checks/openai_api_mode"
 require_relative "doctor/checks/persistence_capabilities"
+require_relative "doctor/checks/artifacts"
+require_relative "doctor/checks/state_model"
 
 module Smith
   module Doctor
@@ -23,6 +25,8 @@ module Smith
 
       Checks::Baseline.run(report)
       Checks::Configuration.run(report)
+      Checks::Artifacts.run(report)
+      Checks::StateModel.run(report)
       Checks::ModelsRegistry.run(report)
       Checks::OpenaiApiMode.run(report)
       Checks::Rails.run(report) if detect_rails?