silas 0.1.7 → 0.3.0

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

@@ -53,23 +53,41 @@ module Silas
         end
       end
 
+      RESCUER_ENTRY = <<~YAML.freeze
+        # Silas: retries jobs failed by dead-worker reaping/pruning, sweeps
+        # expired approvals, and fails turns stranded by dead loop jobs. Part
+        # of the durability contract — do not remove.
+        silas_dead_job_rescuer:
+          class: Silas::DeadJobRescuerJob
+          queue: default
+          schedule: every 30 seconds
+      YAML
+
+      # Idempotent and environment-aware: the entry is injected directly under
+      # EVERY deployable top-level env key (production, staging, …) — never a
+      # blind append into whatever block happens to end the file, and never a
+      # duplicate key on a re-run. A staging worker needs the rescuer exactly
+      # as much as production does.
       def add_rescuer_recurring_task
         recurring = "config/recurring.yml"
-        entry = <<~YAML
+        path = File.expand_path(recurring, destination_root)
 
-          # Silas: retries jobs failed by dead-worker reaping/pruning and sweeps
-          # expired approvals. Part of the durability contract — do not remove.
-          silas_dead_job_rescuer:
-            class: Silas::DeadJobRescuerJob
-            queue: default
-            schedule: every 30 seconds
-        YAML
+        unless File.exist?(path)
+          create_file recurring, "production:\n#{RESCUER_ENTRY.indent(2)}"
+          return
+        end
 
-        if File.exist?(File.expand_path(recurring, destination_root))
-          append_to_file recurring, entry.indent(2)
-        else
-          create_file recurring, "production:#{entry.indent(2)}"
+        if File.read(path).include?("silas_dead_job_rescuer")
+          say_status :skip, "#{recurring} already contains silas_dead_job_rescuer", :yellow
+          return
+        end
+
+        injected = false
+        gsub_file recurring, /^(?!development:|test:)([a-zA-Z_]+:)[ \t]*$/ do |header|
+          injected = true
+          "#{header}\n#{RESCUER_ENTRY.indent(2)}"
         end
+        append_to_file recurring, "\nproduction:\n#{RESCUER_ENTRY.indent(2)}" unless injected
       end
 
       def install_migrations
@@ -84,6 +102,7 @@ module Silas
           Silas installed. Next:
             1. bin/rails db:migrate
             2. export ANTHROPIC_API_KEY=sk-ant-...  (config/initializers/ruby_llm.rb reads it)
+               then `bin/rails silas:doctor` to verify the whole setup
             3. Edit app/agent/instructions.md (your agent's persona)
             4. Write tools in app/agent/tools/ (keyword signature = schema)
             5. Talk to it: bin/rails silas:chat  (or Silas.agent.start(input: "hello"))
@@ -91,8 +110,9 @@ module Silas
             7. Channels (optional): set credentials.silas.slack.{signing_secret,bot_token}
                for Slack; route inbound mail to Silas::AgentMailbox for email.
                Delete app/agent/channels/{slack,email}.rb to disable.
-            8. Inbox: live at /silas/inbox once you set config.inbox_auth
-               (deny-by-default until you do).
+            8. Inbox + web chat: /silas/inbox, deny-by-default — uncomment
+               config.inbox_auth in config/initializers/silas.rb to make it visible.
+            9. Restart your server if it was running (app/agent/ registers at boot).
         MSG
       end
     end

data/lib/generators/silas/install/templates/agent.yml

@@ -1,5 +1,5 @@
 # Data-only agent config. Model defaults to Silas.config.default_model.
-# model: claude-sonnet-5
+# model: claude-sonnet-4-5
 description: This application's agent.
 limits:
   max_steps: 25          # model calls per turn
@@ -7,3 +7,12 @@ limits:
   # max_cost: 1.00             # dollars per turn
   # timeout: 300               # wall-clock seconds per turn
 
+# Structured final answers: give the turn's answer a JSON schema and read the
+# parsed Hash from Turn#answer_data (answer_text stays for prose agents).
+# final_answer:
+#   type: object
+#   properties:
+#     verdict: { type: string }
+#     amount_pence: { type: integer }
+#   required: [verdict]
+

data/lib/generators/silas/install/templates/bin_ci

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
-# CI gate: your app tests, then the agent evals (deterministic; non-zero on failure).
+# CI gate: your app tests, then the agent evals. Either failing fails the gate.
 set -e
 echo "== app tests =="
-bin/rails test 2>/dev/null || true
+bin/rails test
 echo "== agent evals =="
 bin/rails silas:eval

data/lib/generators/silas/install/templates/initializer.rb

@@ -1,12 +1,20 @@
 Silas.configure do |config|
   # Inference engine: :ruby_llm (API key, any provider RubyLLM supports), or
-  # :agent_sdk (a `claude -p` subprocess; API-key auth only). See silas/README.
+  # any object responding to #execute_step. See silas/README.
   config.engine = :ruby_llm
 
-  # Any model your installed ruby_llm's registry resolves (newer Claude models
-  # may need `RubyLLM.models.refresh!` first). Alternatives: "claude-sonnet-5"
-  # (balanced), "claude-haiku-4-5" (fastest/cheapest).
-  config.default_model = "claude-opus-4-8"
+  # Any model your installed ruby_llm's registry resolves (newer models may
+  # need `RubyLLM.models.refresh!` first). "claude-sonnet-4-5" is the balanced
+  # default; "claude-haiku-4-5" is fastest/cheapest; Opus models are the most
+  # capable and the most expensive — set per-turn budgets in agent.yml before
+  # reaching for one.
+  config.default_model = "claude-sonnet-4-5"
+
+  # The operator inbox (mounted at /silas/inbox) is DENY-BY-DEFAULT — invisible
+  # until you wire auth. The lambda DENIES by rendering (or head-ing) and
+  # PASSES by not rendering. Devise-style example:
+  # config.inbox_auth = ->(controller) { controller.head :not_found unless controller.current_user&.admin? }
+  # config.inbox_public_read = true   # read-only demo mode; writes stay gated
 
   # Parked approvals expire after this long (the turn fails as approval_expired).
   # config.approval_ttl = 7.days
@@ -16,4 +24,21 @@ Silas.configure do |config|
 
   # Wrap every model call — e.g. ruby_llm-resilience:
   # config.around_model_call = ->(ctx, &call) { RubyLLM::Resilience.chain(:anthropic) { call.() } }
+
+  # Sandbox for the run_code tool: :none (default, code exec off), :docker, or
+  # a hermetic backend (gem "hermetic"), e.g. Hermetic.gvisor(image: "python:3.12-slim").
+  # config.sandbox = :none
+
+  # Memory (the remember/recall tools): on by default, and every remember
+  # PARKS for human approval. :never auto-approves; config.memory = false
+  # disables memory entirely.
+  # config.memory_approval = :always
+
+  # Cost accounting prices itself from RubyLLM's model registry. Override per
+  # model for fine-tunes / custom deployments / models newer than your
+  # installed registry (units per 1k tokens; 1e6 units = $1):
+  # config.model_prices["your-fine-tune"] = { in: 3000, out: 15_000 }
+
+  # Where eval scenarios live (bin/rails silas:eval).
+  # config.eval_dir = "test/agent_evals"
 end

data/lib/generators/silas/install/templates/ruby_llm.rb

@@ -6,4 +6,8 @@
 # Any provider RubyLLM supports works the same way (openai_api_key, etc.).
 RubyLLM.configure do |c|
   c.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+  # The per-request timeout (seconds; RubyLLM default 300). Under streaming
+  # this is an idle-between-chunks timeout — the hang protection for a stuck
+  # provider connection.
+  # c.request_timeout = 120
 end if ENV["ANTHROPIC_API_KEY"].present?

data/lib/silas/agent.rb

@@ -16,6 +16,10 @@ module Silas
 
     def model       = @attrs["model"] || Silas.config.default_model
     def description = @attrs["description"].to_s
+    # Optional JSON schema for the turn's final answer (raw Hash, passed to
+    # RubyLLM's with_schema). Model-visible state: folded into the definitions
+    # digest when present, so a mid-turn change fails loudly.
+    def final_answer = @attrs["final_answer"]
     def limits      = @attrs["limits"] || {}
     def max_steps   = limits["max_steps"] || Silas.config.max_steps
     def max_input_tokens = limits["max_input_tokens"]  # cumulative input tokens per turn

data/lib/silas/chat.rb

@@ -22,21 +22,23 @@ module Silas
 
     def run
       banner
-      if @session && pending_for(@session).exists? # resuming a session that parked last time
-        settle_parked
-        print_outcome(@session.turns.reload.last)
-      end
+      with_delta_stream do
+        if @session && pending_for(@session).exists? # resuming a session that parked last time
+          settle_parked
+          print_outcome(@session.turns.reload.last)
+        end
 
-      loop do
-        @out.print "\nyou> "
-        line = @in.gets
-        break if line.nil?
+        loop do
+          @out.print "\nyou> "
+          line = @in.gets
+          break if line.nil?
 
-        line = line.strip
-        next if line.empty?
-        break if %w[exit quit].include?(line.downcase)
+          line = line.strip
+          next if line.empty?
+          break if %w[exit quit].include?(line.downcase)
 
-        submit(line)
+          submit(line)
+        end
       end
       @out.puts "bye — session #{@session.id}" if @session
     end
@@ -56,7 +58,33 @@ module Silas
       @out.puts "Resuming session #{@session.id} (#{@session.turns.count} turns)." if @session
     end
 
+    # The REPL runs inline, in the same process as the loop — so it hears the
+    # "silas.delta" notifications and prints tokens as they arrive. Filtered by
+    # session id: notifications are process-global.
+    def with_delta_stream
+      @live = {}
+      subscription = ActiveSupport::Notifications.subscribe("silas.delta") do |*args|
+        payload = args.last
+        print_delta(payload) if @session && payload[:session_id] == @session.id
+      end
+      yield
+    ensure
+      ActiveSupport::Notifications.unsubscribe(subscription) if subscription
+    end
+
+    def print_delta(payload)
+      printed = @live[payload[:step_id]] || 0
+      text = payload[:text].to_s
+      @out.print "\nagent> " if printed.zero?
+      @out.print text[printed..]
+      @out.flush if @out.respond_to?(:flush)
+      @live[payload[:step_id]] = text.length
+      @last_streamed = text
+    end
+
     def submit(text)
+      @live = {}
+      @last_streamed = nil
       turn =
         if @session.nil?
           @session = agent_handle.start(input: text)
@@ -90,7 +118,13 @@ module Silas
       turn.reload
       case turn.status
       when "completed"
-        @out.puts "agent> #{turn.answer_text}"
+        if @last_streamed.present? && @last_streamed == turn.answer_text
+          @out.puts # the streamed line IS the answer; just terminate it
+        elsif turn.answer_text.blank? && (data = turn.answer_data)
+          @out.puts "agent> #{JSON.generate(data)}" # final_answer schema: the payload IS the answer
+        else
+          @out.puts "agent> #{turn.answer_text}"
+        end
       when "waiting", "in_doubt"
         if turn.budget_parked?
           @out.puts "(parked: #{turn.failure_reason} budget reached — resume with " \

data/lib/silas/configuration.rb

@@ -1,9 +1,7 @@
 module Silas
   class Configuration
-    # Inference engine seam: :ruby_llm (Phase 1) or :agent_sdk (stub).
+    # Inference engine seam: :ruby_llm, or any object responding to #execute_step.
     attr_accessor :engine
-    # Auth mode for :agent_sdk — :api_key or :oauth (subscription).
-    attr_accessor :auth
     # Default model when agent.yml doesn't specify one.
     attr_accessor :default_model
     # Active Job queue for agent turns.
@@ -37,17 +35,33 @@ module Silas
     # default to credentials.dig(:silas, :slack, ...); nil disables Slack.
     attr_accessor :channel_resolver
     attr_writer :slack_signing_secret, :slack_bot_token
-    # :agent_sdk engine knobs.
-    attr_accessor :agent_sdk_claude_bin, :agent_sdk_model, :agent_sdk_mcp_host,
-                  :agent_sdk_mcp_timeout_ms, :agent_sdk_cli_version_range
+    # Bind host for the in-process MCP server (Mcp::Server — the "mount your
+    # tools as MCP" seam).
+    attr_accessor :mcp_server_host
+
+    # config.auth and the agent_sdk_* options were removed with the :agent_sdk
+    # engine in 0.2 (warning no-ops for one release) and hard-removed in 0.3 —
+    # a leftover write now raises NoMethodError. Delete them from your
+    # initializer.
+    # JSON API (mounted under /silas/api/v1).
+    #   api_auth  — deny-by-default lambda, same contract as inbox_auth: the
+    #               host DENIES by rendering (or head-ing) and PASSES by not
+    #               rendering. Wire a token check, Devise, whatever you run.
+    #   api_actor — controller -> identity string recorded on approvals made
+    #               through the API (approved_by / declined by).
+    #   api_stream_poll_interval — seconds between SSE row polls.
+    #   api_stream_max_duration  — seconds before an SSE stream closes itself
+    #               (clients reconnect with Last-Event-ID); bounds thread hold.
+    attr_accessor :api_auth, :api_actor, :api_stream_poll_interval, :api_stream_max_duration
     # Inbox (mountable UI at /silas/inbox).
     #   inbox_auth        — deny-by-default lambda; the host renders/head-404s to
     #                       DENY and passes by NOT rendering (resilience pattern).
     #   inbox_public_read — reads render for anyone; approve/decline still gated.
     #   inbox_actor       — controller -> identity string (approved_by/decline by:).
-    #   model_prices      — model id -> {in:, out:} cost-units per 1k tokens,
-    #                       where 1_000_000 units = $1 (so a $3/M-token input rate
-    #                       is 3000 units/1k). Cost.format divides by 1e6.
+    #   model_prices      — OVERRIDE map: model id -> {in:, out:} cost-units per
+    #                       1k tokens, 1e6 units = $1 (a $3/M-token rate is
+    #                       3000). Beats the RubyLLM registry, which prices
+    #                       everything else per (model, provider).
     attr_accessor :inbox_auth, :inbox_public_read, :inbox_actor, :model_prices
     # Force-disable live broadcasting even when turbo-rails is present (nil = auto).
     attr_accessor :inbox_streaming
@@ -70,10 +84,11 @@ module Silas
 
     def initialize
       @engine = :ruby_llm
-      @auth = :api_key
       # Must be resolvable by the installed ruby_llm's model registry — newer
       # Claude models may need `RubyLLM.models.refresh!` before they resolve.
-      @default_model = "claude-opus-4-8"
+      # (Sonnet 4.5 ships in every supported registry; never default a first
+      # run to the priciest model.)
+      @default_model = "claude-sonnet-4-5"
       @queue_name = :default
       @around_model_call = nil
       @approval_ttl = 7.days
@@ -91,11 +106,7 @@ module Silas
       @channel_resolver = nil
       @slack_signing_secret = nil
       @slack_bot_token = nil
-      @agent_sdk_claude_bin = "claude"
-      @agent_sdk_model = nil # falls back to the agent model; must be a CLI-accepted id
-      @agent_sdk_mcp_host = "127.0.0.1"
-      @agent_sdk_mcp_timeout_ms = 15_000
-      @agent_sdk_cli_version_range = ">= 2.1.150, < 3"
+      @mcp_server_host = "127.0.0.1"
       @eval_dir = "test/agent_evals"
       @eval_grader = nil
       @sandbox = :none
@@ -110,18 +121,18 @@ module Silas
       @sandbox_workdir = "/workspace"
       @sandbox_docker_bin = "docker"
       @sandbox_timeout = 30
+      @api_auth = ->(controller) { controller.head :not_found } # deny by default
+      @api_actor = ->(_controller) { "api" }
+      @api_stream_poll_interval = 0.5
+      @api_stream_max_duration = 300
       @inbox_auth = ->(controller) { controller.head :not_found } # deny by default
       @inbox_public_read = false
       @inbox_actor = ->(controller) { controller.try(:current_user)&.try(:email) || "inbox" }
-      # Current Claude rates as cost-units per 1k tokens (1e6 units = $1):
-      # Opus 4.8 $5/$25, Sonnet $3/$15, Haiku $1/$5 per million tokens.
-      @model_prices = {
-        "claude-opus-4-8" => { in: 5000, out: 25_000 },
-        "claude-sonnet-5" => { in: 3000, out: 15_000 },
-        "claude-sonnet-4-6" => { in: 3000, out: 15_000 },
-        "claude-haiku-4-5" => { in: 1000, out: 5000 },
-        "claude-haiku-4-5-20251001" => { in: 1000, out: 5000 }
-      }
+      # OVERRIDE map only — pricing comes from RubyLLM's model registry
+      # (1,100+ models, refreshed upstream from models.dev). List a model here
+      # to beat the registry: fine-tunes, custom deployments, models newer
+      # than the installed registry. Units: per 1k tokens, 1e6 units = $1.
+      @model_prices = {}
     end
 
     def validate!
@@ -129,24 +140,45 @@ module Silas
       self
     end
 
-    # PLAN.md §1, non-negotiable: raise if subscription OAuth is configured
-    # while an API key is present — the key would silently win and bill credits.
-    # The inverse also holds: :agent_sdk runs --bare (API-key auth only), so
-    # api_key mode needs a key present.
+    # Fail-loud misconfiguration checks, run from Silas.configure and at boot.
     def boot_guard!
-      if engine == :agent_sdk && auth == :oauth && ENV["ANTHROPIC_API_KEY"].present?
+      if engine == :agent_sdk
         raise BootGuardError,
-              "engine :agent_sdk with auth: :oauth is configured, but ANTHROPIC_API_KEY exists " \
-              "in the environment. The key would silently override subscription OAuth and drain " \
-              "API credits. Unset ANTHROPIC_API_KEY or switch to auth: :api_key."
+              "the :agent_sdk engine was removed in Silas 0.2 — the claude -p subprocess " \
+              "integration is gone (its subscription-auth rationale was unreachable). " \
+              "Use engine :ruby_llm, the production path."
       end
 
-      if engine == :agent_sdk && auth == :api_key && ENV["ANTHROPIC_API_KEY"].blank?
-        raise BootGuardError,
-              "engine :agent_sdk uses --bare (API-key auth only) but ANTHROPIC_API_KEY is not set."
+      check_provider_credentials!
+      warn_unsafe_queue_adapter!
+    end
+
+    # The most common first-run failure: no provider key configured, so the
+    # first turn dies deep inside RubyLLM with a third-party error. Surface it
+    # at boot with the fix. Raises in production (a keyless prod deploy is
+    # always a misconfiguration); warns in development so a fresh app can
+    # still boot and browse the inbox before a key exists.
+    def check_provider_credentials!
+      return unless engine == :ruby_llm && defined?(::RubyLLM)
+
+      providers = ::RubyLLM::Provider.providers.values
+      configured = providers.any? do |provider|
+        requirements = provider.configuration_requirements
+        requirements.any? && requirements.all? { |key| ::RubyLLM.config.public_send(key).present? }
       end
+      return if configured
 
-      warn_unsafe_queue_adapter!
+      message = "[Silas] engine :ruby_llm has no configured provider — no API key is set on " \
+                "RubyLLM.config. Set one in config/initializers/ruby_llm.rb, e.g. " \
+                "RubyLLM.configure { |c| c.anthropic_api_key = ENV[\"ANTHROPIC_API_KEY\"] } " \
+                "— the first agent turn will fail without it."
+      raise BootGuardError, message if defined?(::Rails) && ::Rails.env.production?
+
+      (defined?(::Rails) && ::Rails.logger ? ::Rails.logger.warn(message) : nil) || Kernel.warn(message)
+    rescue BootGuardError
+      raise
+    rescue StandardError
+      nil # a diagnostic must never break boot
     end
 
     # Silas's durability and exactly-once guarantees rest on the queue adapter:
@@ -158,6 +190,10 @@ module Silas
     # mints new tool_call ids the ledger cannot dedup). Solid Queue — or any
     # durable, serializing, DB-backed adapter — is required to run agents; the
     # synchronous :inline adapter is safe for scripts and demos (no durability).
+    #
+    # RAISES in production — running agents on the Async adapter there silently
+    # voids the durability contract. Warns in development (Rails' dev default
+    # is :async and a fresh app must still boot).
     def warn_unsafe_queue_adapter!
       return unless defined?(::ActiveJob::Base)
 
@@ -169,7 +205,11 @@ module Silas
                 "the original job, which double-executes agent steps and breaks " \
                 "exactly-once tool effects. Use :solid_queue (production) or " \
                 ":inline (scripts/demos). See Silas DEPLOY.md."
+      raise BootGuardError, message if defined?(::Rails) && ::Rails.env.production?
+
       (defined?(::Rails) && ::Rails.logger ? ::Rails.logger.warn(message) : nil) || Kernel.warn(message)
+    rescue BootGuardError
+      raise
     rescue StandardError
       # A diagnostic must never break boot.
       nil

data/lib/silas/delta_buffer.rb

@@ -0,0 +1,50 @@
+module Silas
+  # Coalesces model text deltas into ~10Hz "silas.delta" notifications carrying
+  # the ACCUMULATED text so far — subscribers replace rather than append, which
+  # is idempotent under a crash-restream (same step id, fresh stream overwrites
+  # itself) and ordering-safe under Turbo. Deltas are decoration over the
+  # authoritative row render: never persisted, never fed back to the model, and
+  # a replayed step (already completed) emits none.
+  #
+  # Payload: { session_id:, turn_id:, step_id:, step_index:, text: } — every
+  # subscriber MUST filter by these ids (notifications are process-global; a
+  # busy worker interleaves deltas from concurrent turns).
+  class DeltaBuffer
+    INTERVAL = 0.1 # seconds between publishes; #finish flushes the tail
+
+    def initialize(turn:, step:)
+      @turn = turn
+      @step = step
+      @text = +""
+      @published = 0
+      @last_publish = 0.0
+    end
+
+    def append(text)
+      return if text.empty?
+
+      @text << text
+      publish if clock - @last_publish >= INTERVAL
+    end
+
+    # The final flush. StepRunner calls this BEFORE the step row commits, so
+    # the authoritative after_commit render can never race a straggling batch.
+    def finish = publish
+
+    private
+
+    def publish
+      return if @text.empty? || @text.length == @published
+
+      @published = @text.length
+      @last_publish = clock
+      ActiveSupport::Notifications.instrument(
+        "silas.delta",
+        session_id: @turn.session_id, turn_id: @turn.id,
+        step_id: @step.id, step_index: @step.index, text: @text.dup
+      )
+    end
+
+    def clock = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+end

data/lib/silas/doctor.rb

@@ -0,0 +1,155 @@
+require "erb"
+require "yaml"
+
+module Silas
+  # One command for every known first-run failure mode: provider key, queue
+  # adapter, model resolution, migrations, tool validation, the rescuer
+  # entry, cable adapter for live streaming, and auth wiring. Each check was
+  # already written somewhere in the codebase — this makes them reachable as
+  # `bin/rails silas:doctor`.
+  class Doctor
+    Check = Struct.new(:status, :label, :detail) # status: :pass | :warn | :fail
+
+    def self.run(root: Rails.root) = new(root: root).run
+
+    def initialize(root:)
+      @root = Pathname(root)
+    end
+
+    def run
+      [
+        provider_credentials, queue_adapter, model_resolution, migrations,
+        agent_directory, rescuer_entry, streaming_cable, auth_wiring
+      ].flatten.compact
+    end
+
+    private
+
+    def provider_credentials
+      configured = ::RubyLLM::Provider.providers.select do |_slug, provider|
+        requirements = provider.configuration_requirements
+        requirements.any? && requirements.all? { |key| ::RubyLLM.config.public_send(key).present? }
+      end.keys
+      if configured.any?
+        Check.new(:pass, "provider credentials", configured.join(", "))
+      else
+        Check.new(:fail, "provider credentials",
+                  "no API key on RubyLLM.config — set one in config/initializers/ruby_llm.rb; " \
+                  "the first turn will fail without it")
+      end
+    rescue StandardError => e
+      Check.new(:warn, "provider credentials", "could not inspect RubyLLM config (#{e.class})")
+    end
+
+    def queue_adapter
+      name = ActiveJob::Base.queue_adapter.class.name.to_s
+      case name
+      when /SolidQueue/
+        Check.new(:pass, "queue adapter", "solid_queue (durable)")
+      when /AsyncAdapter/
+        Check.new(:fail, "queue adapter",
+                  "in-process :async double-executes continuation steps and voids the durability " \
+                  "contract — use :solid_queue (see DEPLOY.md)")
+      when /InlineAdapter/
+        Check.new(:warn, "queue adapter", "inline — fine for scripts and demos, no durability")
+      else
+        Check.new(:warn, "queue adapter", "#{name.demodulize} — durability requires a serializing, DB-backed adapter")
+      end
+    end
+
+    def model_resolution
+      model = Silas.agent.model
+      info = ::RubyLLM.models.find(model)
+      Check.new(:pass, "model #{model}",
+                "#{info.provider} · $#{info.input_price_per_million}/$#{info.output_price_per_million} per MTok")
+    rescue StandardError
+      Check.new(:fail, "model #{model || '?'}",
+                "not in ruby_llm's registry — `RubyLLM.models.refresh!` or pick a registry model")
+    end
+
+    def migrations
+      missing = %w[silas_sessions silas_turns silas_steps silas_tool_invocations]
+                .reject { |t| ActiveRecord::Base.connection.table_exists?(t) }
+      if missing.any?
+        return Check.new(:fail, "migrations",
+                         "missing #{missing.join(', ')} — bin/rails silas:install:migrations db:migrate")
+      end
+      unless ActiveRecord::Base.connection.column_exists?(:silas_steps, :provider)
+        return Check.new(:warn, "migrations", "0.3 migration pending — bin/rails silas:install:migrations db:migrate")
+      end
+
+      Check.new(:pass, "migrations", "all silas tables present")
+    rescue StandardError => e
+      Check.new(:fail, "database", "#{e.class}: #{e.message.lines.first&.strip}")
+    end
+
+    def agent_directory
+      dir = @root.join("app/agent")
+      return Check.new(:fail, "app/agent", "missing — bin/rails generate silas:install") unless dir.exist?
+
+      checks = []
+      checks << Check.new(:warn, "instructions", "app/agent/instructions.md missing") unless dir.join("instructions.md").exist?
+      begin
+        registry = Silas::Registry.new(root: @root)
+        checks << Check.new(:pass, "tools", "#{registry.tools.size} tool(s) validate")
+      rescue StandardError => e
+        checks << Check.new(:fail, "tools", e.message)
+      end
+      checks
+    end
+
+    def rescuer_entry
+      path = @root.join("config/recurring.yml")
+      unless path.exist?
+        return Check.new(:warn, "rescuer",
+                         "config/recurring.yml missing — the dead-job rescuer is part of the durability contract")
+      end
+      if path.read.include?("silas_dead_job_rescuer")
+        Check.new(:pass, "rescuer", "recurring entry present")
+      else
+        Check.new(:warn, "rescuer", "no silas_dead_job_rescuer entry — SIGKILL recovery won't run")
+      end
+    end
+
+    def streaming_cable
+      unless Silas::Inbox.streaming_available?
+        return Check.new(:warn, "live streaming", "turbo-rails not bundled — the inbox falls back to a polling refresh")
+      end
+
+      cable = @root.join("config/cable.yml")
+      adapter = begin
+        cable.exist? ? YAML.safe_load(ERB.new(cable.read).result, aliases: true)&.dig(Rails.env.to_s, "adapter") : nil
+      rescue StandardError
+        nil
+      end
+      case adapter
+      when "async"
+        Check.new(:warn, "live streaming",
+                  "cable adapter :async is single-process — token deltas emitted in the worker never " \
+                  "reach the browser; use solid_cable or redis")
+      when nil
+        Check.new(:warn, "live streaming", "could not read a cable adapter from config/cable.yml")
+      else
+        Check.new(:pass, "live streaming", "cable adapter #{adapter}")
+      end
+    end
+
+    def auth_wiring
+      [
+        auth_check("inbox auth", Silas.config.inbox_auth, "/silas/inbox", "config.inbox_auth"),
+        auth_check("api auth", Silas.config.api_auth, "/silas/api/v1", "config.api_auth")
+      ]
+    end
+
+    # The deny-by-default lambdas are defined inside silas/configuration.rb;
+    # anything the host wired has a different source_location.
+    def auth_check(label, auth_lambda, surface, option)
+      if auth_lambda.respond_to?(:source_location) &&
+         auth_lambda.source_location&.first.to_s.include?("silas/configuration")
+        Check.new(:warn, label, "deny-by-default — #{surface} is invisible until you set #{option}")
+      else
+        Check.new(:pass, label, "configured")
+      end
+    end
+  end
+end

data/lib/silas/engine.rb

@@ -37,6 +37,12 @@ module Silas
       Silas.config.boot_guard!
     end
 
+    # Live token streaming into the inbox trace: one process-wide subscriber on
+    # "silas.delta"; a no-op unless turbo-rails is present and streaming is on.
+    initializer "silas.delta_broadcaster" do
+      Silas::Inbox::DeltaBroadcaster.subscribe!
+    end
+
     # Registry rebuilds on every code reload in development, once in production.
     initializer "silas.registry" do |app|
       next unless app.root.join("app/agent").exist? || app.root.join("app/agents").exist?