silas 0.2.0 → 0.3.0

data/config/routes.rb

@@ -1,4 +1,23 @@
 Silas::Engine.routes.draw do
+  namespace :api do
+    namespace :v1 do
+      resources :sessions, only: %i[create show] do
+        resources :turns, only: :create
+        resources :approvals, only: :index
+        get :stream, on: :member, to: "streams#show"
+      end
+      resources :turns, only: [] do
+        member { post :cancel }
+      end
+      resources :approvals, only: [] do
+        member do
+          post :approve
+          post :decline
+        end
+      end
+    end
+  end
+
   namespace :channels do
     post "slack/events", to: "slack#events"
     post "slack/actions", to: "slack#actions"
@@ -12,7 +31,10 @@ Silas::Engine.routes.draw do
       resources :turns, only: :create
     end
     resources :turns, only: [] do
-      member { post :cancel }
+      member do
+        post :cancel
+        post :raise_budget
+      end
     end
     resources :invocations, only: [] do
       member do

data/db/migrate/20260725000001_add_provider_to_silas_steps.rb

@@ -0,0 +1,13 @@
+class AddProviderToSilasSteps < ActiveRecord::Migration[8.1]
+  def change
+    # The provider RubyLLM's resolution picked for the step's model, stamped at
+    # persist time — cost lookups price against (model, provider) forever
+    # after, immune to registry tie-break changes (85/1081 registry ids exist
+    # under multiple providers at different prices).
+    add_column :silas_steps, :provider, :string
+
+    # Declared in 0.1.0, defaulted to 0, never written — a silent lie to
+    # anyone who queried it. Cost is derived at read time from step tokens.
+    remove_column :silas_turns, :cost_microcents, :integer, null: false, default: 0
+  end
+end

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

@@ -102,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"))

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

@@ -4,11 +4,11 @@ Silas.configure do |config|
   config.engine = :ruby_llm
 
   # Any model your installed ruby_llm's registry resolves (newer models may
-  # need `RubyLLM.models.refresh!` first). "claude-sonnet-5" is the balanced
+  # 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-5"
+  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
@@ -34,8 +34,9 @@ Silas.configure do |config|
   # disables memory entirely.
   # config.memory_approval = :always
 
-  # Cost accounting price overrides: cost-units per 1k tokens, where
-  # 1_000_000 units = $1 (so a $3/M-token rate is 3000).
+  # 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).

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

@@ -120,6 +120,8 @@ module Silas
       when "completed"
         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

data/lib/silas/configuration.rb

@@ -39,35 +39,29 @@ module Silas
     # tools as MCP" seam).
     attr_accessor :mcp_server_host
 
-    # Removed in 0.2 with the :agent_sdk engine. Accepted as warning no-ops for
-    # one release so an existing initializer doesn't crash at boot; hard removal
-    # in 0.3.
-    REMOVED_AGENT_SDK_OPTIONS = %i[
-      auth agent_sdk_claude_bin agent_sdk_model agent_sdk_mcp_host
-      agent_sdk_mcp_timeout_ms agent_sdk_cli_version_range
-    ].freeze
-
-    REMOVED_AGENT_SDK_OPTIONS.each do |option|
-      define_method("#{option}=") { |_value| warn_removed_agent_sdk_option(option) }
-      define_method(option) do
-        warn_removed_agent_sdk_option(option)
-        nil
-      end
-    end
-
-    def warn_removed_agent_sdk_option(option)
-      message = "[Silas] config.#{option} was removed in 0.2 with the :agent_sdk engine and " \
-                "is now a no-op — delete it from your initializer (hard removal in 0.3)."
-      (defined?(::Rails) && ::Rails.logger ? ::Rails.logger.warn(message) : nil) || Kernel.warn(message)
-    end
+    # 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
@@ -92,7 +86,9 @@ module Silas
       @engine = :ruby_llm
       # 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
@@ -125,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!

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/engines/ruby_llm.rb

@@ -43,6 +43,10 @@ module Silas
                 "or pick a registry-known model in config.default_model / agent.yml."
         end
         chat.with_instructions(context[:system]) if context[:system].present?
+        # agent.yml's final_answer schema: RubyLLM renders the provider's
+        # structured-output dialect and JSON-parses the response back to a
+        # Hash — which to_result persists as a "structured" block.
+        chat.with_schema(context[:final_answer]) if context[:final_answer].present?
         context[:tools].each { |definition| chat.with_tool(HaltProxy.new(definition)) }
 
         replay_history(chat, context[:messages])
@@ -117,8 +121,15 @@ module Silas
         assistant = chat.messages.reverse.find { |m| m.role.to_s == "assistant" } || response
 
         blocks = []
-        text = assistant.content.to_s
-        blocks << { "type" => "text", "text" => text } if text.present?
+        content = assistant.content
+        if content.is_a?(Hash)
+          # with_schema active: RubyLLM parsed the response to a Hash. Persist
+          # it as its own block type — content.to_s here would write Ruby's
+          # Hash#inspect string into the transcript as "text".
+          blocks << { "type" => "structured", "data" => content }
+        elsif content.to_s.present?
+          blocks << { "type" => "text", "text" => content.to_s }
+        end
 
         tool_calls = (assistant.tool_calls || {}).values.map do |tc|
           blocks << { "type" => "tool_call", "id" => tc.id, "name" => tc.name,

data/lib/silas/eval/assertions.rb

@@ -39,6 +39,24 @@ module Silas
           check(matcher === @t.final_text, "final answer #{@t.final_text.inspect} does not match #{matcher.inspect}")
         end
 
+        # Structured (final_answer) assertions. With a Hash, expects the whole
+        # payload; with key/value, one field; with a block, a predicate over
+        # the payload. String keys — the payload is stored jsonb.
+        def assert_answer_data(expected = :__unset, key: nil, value: :__unset, &pred)
+          data = @t.answer_data
+          return check(false, "no structured answer (final_answer schema not set, or turn unfinished)") if data.nil?
+
+          if pred
+            check(pred.call(data), "answer_data predicate failed for #{data.inspect}")
+          elsif key
+            check(data[key.to_s] == value, "answer_data.#{key} expected #{value.inspect}, got #{data[key.to_s].inspect}")
+          elsif expected != :__unset
+            check(data == expected, "answer_data expected #{expected.inspect}, got #{data.inspect}")
+          else
+            check(true, nil) # presence alone
+          end
+        end
+
         # No-hallucinated-price guard: every money amount in the final answer must
         # trace to a number the agent actually saw (tool results or the user input),
         # allowing pence<->pounds scaling.

data/lib/silas/eval/transcript.rb

@@ -14,6 +14,7 @@ module Silas
       def completed? = @turn.completed?
       def parked?    = @turn.parked?
       def final_text = @turn.answer_text.to_s
+      def answer_data = @turn.answer_data
       def invocations = @turn.tool_invocations.order(:id).to_a
       def invocations_for(name) = invocations.select { |i| i.tool_name == name.to_s }
       def results = invocations.map(&:result).compact

data/lib/silas/inbox/cost.rb

@@ -1,45 +1,47 @@
 module Silas
   module Inbox
-    # cost_microcents is declared on silas_turns but never populated (only
-    # silas_steps carry real token counts). So the inbox derives cost at read
-    # time from step tokens x a host-supplied price map — and honestly reports
-    # `unpriced` when a model isn't in the map rather than a lying £0.00.
+    # Cost is derived at read time from step tokens. Prices come from
+    # config.model_prices (the OVERRIDE map — custom deployments, fine-tunes,
+    # models newer than the installed registry) and fall back to RubyLLM's
+    # model registry, priced per (model, provider) — 85/1081 registry ids
+    # exist under multiple providers at different prices, which is why steps
+    # stamp the provider. Unknown stays `unpriced`, never a lying $0.00.
     module Cost
       module_function
 
       def for_session(session)
         rows = Silas::Step.joins(:turn)
                           .where(silas_turns: { session_id: session.id })
-                          .group(:model)
-                          .pluck(:model, Arel.sql("SUM(silas_steps.input_tokens)"), Arel.sql("SUM(silas_steps.output_tokens)"))
+                          .group(:model, :provider)
+                          .pluck(:model, :provider, Arel.sql("SUM(silas_steps.input_tokens)"), Arel.sql("SUM(silas_steps.output_tokens)"))
         aggregate(rows)
       end
 
       def for_turn(turn)
         rows = Silas::Step.where(turn_id: turn.id)
-                          .group(:model)
-                          .pluck(:model, Arel.sql("SUM(silas_steps.input_tokens)"), Arel.sql("SUM(silas_steps.output_tokens)"))
+                          .group(:model, :provider)
+                          .pluck(:model, :provider, Arel.sql("SUM(silas_steps.input_tokens)"), Arel.sql("SUM(silas_steps.output_tokens)"))
         aggregate(rows)
       end
 
       def for_agent(agent_name)
         rows = Silas::Step.joins(turn: :session)
                           .where(silas_sessions: { agent_name: agent_name })
-                          .group(:model)
-                          .pluck(:model, Arel.sql("SUM(silas_steps.input_tokens)"), Arel.sql("SUM(silas_steps.output_tokens)"))
+                          .group(:model, :provider)
+                          .pluck(:model, :provider, Arel.sql("SUM(silas_steps.input_tokens)"), Arel.sql("SUM(silas_steps.output_tokens)"))
         aggregate(rows)
       end
 
       def aggregate(rows)
         input = output = microcents = 0
         unpriced = false
-        rows.each do |model, in_tok, out_tok|
+        rows.each do |model, provider, in_tok, out_tok|
           in_tok = in_tok.to_i
           out_tok = out_tok.to_i
           input += in_tok
           output += out_tok
-          if (price = Silas.config.model_prices[model])
-            microcents += (in_tok * price[:in] + out_tok * price[:out]) / 1000
+          if (rate = rate_for(model, provider))
+            microcents += (in_tok * rate[:in] + out_tok * rate[:out]) / 1000
           else
             unpriced = true
           end
@@ -47,6 +49,28 @@ module Silas
         { input_tokens: input, output_tokens: output, microcents: microcents, unpriced: unpriced }
       end
 
+      # {in:, out:} in cost-units per 1k tokens (1e6 units = $1), or nil when
+      # the model can't be priced. Override map first; then the registry —
+      # two-arg find when the step stamped a provider (the bare form
+      # tie-breaks by a hardcoded preference list and can price the wrong
+      # provider), registry $/MTok converted at x1000. A model with no price
+      # data returns nil: unknown is never zero.
+      def rate_for(model, provider)
+        if (price = Silas.config.model_prices[model])
+          return price
+        end
+        return nil if model.nil?
+
+        info = provider.present? ? ::RubyLLM.models.find(model, provider) : ::RubyLLM.models.find(model)
+        in_pm = info.input_price_per_million
+        out_pm = info.output_price_per_million
+        return nil unless in_pm && out_pm
+
+        { in: (in_pm * 1000).round, out: (out_pm * 1000).round }
+      rescue StandardError
+        nil
+      end
+
       # microcents -> "$0.0123" (or nil when unpriced with no priced tokens)
       def format(cents)
         return nil if cents.nil?

data/lib/silas/message_builder.rb

@@ -50,9 +50,16 @@ module Silas
 
     # Text comes from the model's own blocks; tool_use blocks are rebuilt from
     # the settled invocations so the assistant message and the tool results that
-    # follow are always a matched set (same ids, same count).
+    # follow are always a matched set (same ids, same count). A structured
+    # (final_answer) block replays as its JSON text — deterministic (same rows
+    # -> same string), and providers need message content, not our block type.
     def assistant_blocks(step, settled)
-      text = Array(step.response_blocks).select { |b| b["type"] == "text" }
+      text = Array(step.response_blocks).filter_map do |b|
+        case b["type"]
+        when "text"       then b
+        when "structured" then { "type" => "text", "text" => JSON.generate(b["data"]) }
+        end
+      end
       tools = settled.map do |inv|
         { "type" => "tool_call", "id" => inv.tool_call_id,
           "name" => inv.tool_name, "arguments" => inv.arguments || {} }

data/lib/silas/named_agent.rb

@@ -23,6 +23,7 @@ module Silas
     # Definition readers delegate to the scope's parsed agent.yml.
     def model       = scope.agent.model
     def description = scope.agent.description
+    def final_answer = scope.agent.final_answer
     def limits      = scope.agent.limits
     def max_steps   = scope.agent.max_steps
     def max_input_tokens = scope.agent.max_input_tokens

data/lib/silas/registry.rb

@@ -100,13 +100,20 @@ module Silas
     end
 
     # Stable across boots for the same agent definition; changes when any tool
-    # schema (incl. the delegate roster + remote connection tools), or skill
-    # description, changes.
+    # schema (incl. the delegate roster + remote connection tools), skill
+    # description, or final_answer schema changes.
+    #
+    # final_answer is appended ONLY when present: schema-less agents keep a
+    # byte-identical digest across upgrades, so turns parked over a deploy
+    # never fail NondeterminismError for a key they don't use.
     def digest
-      Digest::SHA256.hexdigest(JSON.generate({
-        tools: definitions,
-        skills: skills.map { |s| [ s.name, s.description ] }
-      }))
+      payload = { tools: definitions, skills: skills.map { |s| [ s.name, s.description ] } }
+      payload[:final_answer] = root_agent.final_answer if root_agent.final_answer.present?
+      Digest::SHA256.hexdigest(JSON.generate(payload))
+    end
+
+    def root_agent
+      @root_agent ||= Silas::Agent.load(root: @root)
     end
 
     # --- named agents (app/agents/<name>/ — the staff pattern) ---------------
@@ -192,9 +199,12 @@ module Silas
       builtins["handoff"] = Silas::Tools::Handoff if named && named_agent_dirs.size > 1
       resolver = ->(n) { (tools[n] || builtins.fetch(n)).new }
       definitions = (tools.values + builtins.values).map(&:schema)
-      digest = Digest::SHA256.hexdigest(JSON.generate(tools: definitions, skills: skills.map { |s| [ s.name, s.description ] }))
+      loaded_agent = agent || Silas::Agent.load(dir: dir)
+      payload = { tools: definitions, skills: skills.map { |s| [ s.name, s.description ] } }
+      payload[:final_answer] = loaded_agent.final_answer if loaded_agent.final_answer.present?
+      digest = Digest::SHA256.hexdigest(JSON.generate(payload))
 
-      Silas::AgentScope.new(name: name, dir: dir, agent: agent || Silas::Agent.load(dir: dir),
+      Silas::AgentScope.new(name: name, dir: dir, agent: loaded_agent,
                             resolver: resolver, definitions: definitions, digest: digest, skills: skills)
     end
   end

data/lib/silas/step_runner.rb

@@ -22,6 +22,7 @@ module Silas
             stop_reason: result.stop_reason,
             terminal: result.terminal?,
             model: turn_model(turn),
+            provider: provider_for(turn_model(turn)),
             input_tokens: result.usage&.dig(:input_tokens),
             output_tokens: result.usage&.dig(:output_tokens)
           )
@@ -58,6 +59,7 @@ module Silas
         messages: MessageBuilder.call(turn, upto_index: index),
         tools: Silas.tool_definitions,
         model: turn_model(turn),
+        final_answer: Silas.agent.final_answer,
         limits: { max_steps: Silas.agent.max_steps }
       }
 
@@ -109,5 +111,15 @@ module Silas
     def turn_model(_turn)
       Silas.agent.model
     end
+
+    # The provider RubyLLM's own resolution picks for this model id, stamped
+    # on the row so cost lookups price against (model, provider) forever
+    # after — the registry's tie-break can change; the row shouldn't. nil for
+    # ids the installed registry doesn't know (fakes, custom engines).
+    def provider_for(model)
+      ::RubyLLM.models.find(model).provider
+    rescue StandardError
+      nil
+    end
   end
 end

data/lib/silas/version.rb

@@ -1,3 +1,3 @@
 module Silas
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/silas.rb

@@ -43,6 +43,7 @@ require "silas/instructions"
 require "silas/step_runner"
 require "silas/eval" # after engines (ScriptedEngine < Engines::Base)
 require "silas/chat"
+require "silas/doctor"
 
 module Silas
   class << self