silas 0.1.7 → 0.3.0

data/lib/silas/engines/base.rb

@@ -1,8 +1,10 @@
 module Silas
-  # Streamed event from an engine (or the framework) during a step.
-  # Types: :text_delta, :tool_call, :thinking, :usage — and :approval_request,
-  # which only :engine-owned loops (agent_sdk) emit; in :framework-owned loops
-  # approvals are a Ledger concern, never an engine event.
+  # Streamed event from an engine during a step. The type vocabulary is an open
+  # set — consumers must ignore unknown types. Emitted today by Engines::RubyLLM:
+  #   :message_start — once per model call (before_message)
+  #   :text_delta    — { text: } chunks as the response streams
+  # StepRunner coalesces :text_delta into "silas.delta" notifications (see
+  # DeltaBuffer); everything else is available to custom engines/hooks.
   Event = Data.define(:type, :payload)
 
   module Engines
@@ -10,10 +12,6 @@ module Silas
     # and reports what came back; the framework owns the loop, the ledger owns
     # tool execution.
     class Base
-      # :framework — Silas's AgentLoopJob drives the loop (ruby_llm).
-      # :engine    — the engine drives its own loop (agent_sdk, future).
-      def self.loop_ownership = :framework
-
       # context: { turn:, index:, system:, messages:, tools:, model:, limits: }
       # Yields Silas::Event objects as they stream; returns a Result.
       def execute_step(context, &on_event)

data/lib/silas/engines/ruby_llm.rb

@@ -8,8 +8,6 @@ module Silas
     class RubyLLM < Base
       INTERCEPTED = "__silas_intercepted__".freeze
 
-      def self.loop_ownership = :framework
-
       def execute_step(context, &on_event)
         chat = build_chat(context, &on_event)
 
@@ -17,7 +15,17 @@ module Silas
                                                            turn_id: context[:turn]&.id,
                                                            index: context[:index],
                                                            model: context[:model]) do
-          chat.complete
+          if on_event
+            # Streamed: RubyLLM's accumulator returns a Message identical in
+            # shape to the sync path, so to_result needs no branch. Chunks with
+            # tool-call fragments carry nil/empty content — only text streams.
+            chat.complete do |chunk|
+              text = chunk.content
+              on_event.call(Event.new(type: :text_delta, payload: { text: text })) if text.is_a?(String) && !text.empty?
+            end
+          else
+            chat.complete
+          end
         end
 
         to_result(chat, response)
@@ -35,12 +43,19 @@ 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])
 
         if on_event
-          chat.on_new_message { on_event.call(Event.new(type: :message_start, payload: {})) }
+          # before_message replaces the deprecated on_new_message (gone in
+          # RubyLLM 2.0). Under streaming it fires BEFORE the HTTP request —
+          # deliberate; don't "fix" the earlier timing.
+          chat.before_message { on_event.call(Event.new(type: :message_start, payload: {})) }
         end
         chat
       end
@@ -106,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/errors.rb

@@ -1,9 +1,9 @@
 module Silas
   class Error < StandardError; end
 
-  # The :agent_sdk + OAuth footgun (PLAN.md boot guard, non-negotiable): an
-  # ANTHROPIC_API_KEY in the environment would silently override subscription
-  # OAuth and drain credits.
+  # A fatal misconfiguration detected at boot — e.g. a removed engine still
+  # configured, or a missing API key for the configured engine. Fail loud at
+  # configure time, never on the first turn.
   class BootGuardError < Error; end
 
   # A continuation checkpoint occurred inside a ledger transaction. Checkpoints

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

@@ -4,8 +4,6 @@ module Silas
     # eval script the MODEL's decisions while the REAL Ledger runs the REAL tools —
     # so assertions see a genuine transcript.
     class ScriptedEngine < Silas::Engines::Base
-      def self.loop_ownership = :framework
-
       attr_reader :calls
 
       def initialize(steps)

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/inbox/delta_broadcaster.rb

@@ -0,0 +1,38 @@
+module Silas
+  module Inbox
+    # Streams accumulated step text into the live trace as it arrives.
+    #
+    # Synchronous on purpose: broadcast_update_to, not _later — the row
+    # broadcasts ride ActiveJob because they are rare; a delta batch every
+    # ~100ms per running turn would swamp the queue. The push happens on the
+    # worker thread mid-model-call, so it is wrapped: a cable/render failure
+    # can NEVER re-raise into the durable loop.
+    #
+    # Deltas are decoration. The authoritative after_commit row render replaces
+    # the whole step partial (dom_id target) and supersedes anything streamed
+    # into the inner text container.
+    module DeltaBroadcaster
+      EVENT = "silas.delta".freeze
+
+      class << self
+        def subscribe!
+          @subscription ||= ActiveSupport::Notifications.subscribe(EVENT) do |*args|
+            broadcast(args.last)
+          end
+        end
+
+        def broadcast(payload)
+          return unless Silas::Inbox.streaming?
+
+          Turbo::StreamsChannel.broadcast_update_to(
+            Silas::Inbox.stream_name(payload[:session_id]),
+            target: "silas-step-#{payload[:step_id]}-text",
+            html: ERB::Util.html_escape(payload[:text]) # plain text; the row render owns formatting
+          )
+        rescue StandardError => e
+          Rails.logger&.warn("[silas.inbox] delta broadcast failed: #{e.class}: #{e.message}")
+        end
+      end
+    end
+  end
+end

data/lib/silas/ledger.rb

@@ -20,10 +20,16 @@ module Silas
     GUARD_KEY = :silas_ledger_transaction
 
     class << self
-      # True while a ledger transaction is open on this thread. A continuation
-      # checkpoint inside would raise Interrupt and roll back committed-looking
-      # progress (spike finding #5) — AgentLoopJob asserts against this.
-      def in_transaction? = Thread.current[GUARD_KEY] == true
+      # True while a ledger transaction is open in this execution context. A
+      # continuation checkpoint inside would raise Interrupt and roll back
+      # committed-looking progress (spike finding #5) — AgentLoopJob asserts
+      # against this. Stored in IsolatedExecutionState (not Thread.current[],
+      # which is fiber-local) so the guard follows the app's configured
+      # isolation level, exactly like Silas.current_scope — under the default
+      # :thread isolation it survives into internally-created fibers
+      # (enumerators, streaming bodies) where a fiber-local flag would
+      # silently vanish.
+      def in_transaction? = ActiveSupport::IsolatedExecutionState[GUARD_KEY] == true
 
       def assert_no_checkpoint!
         return unless in_transaction?
@@ -50,9 +56,9 @@ module Silas
       end
 
       # Drive a SINGLE freshly-created invocation to a terminal state — the
-      # :agent_sdk MCP endpoint creates one invocation per tools/call and needs
-      # exactly the same exactly-once/effect-mode machinery as settle!. Returns
-      # :done or :parked; the invocation carries its .result.
+      # hosted MCP endpoint (Mcp::Handler) creates one invocation per tools/call
+      # and needs exactly the same exactly-once/effect-mode machinery as
+      # settle!. Returns :done or :parked; the invocation carries its .result.
       def execute_invocation!(invocation, resolver:)
         settle_invocation!(invocation, resolver)
       end
@@ -157,12 +163,18 @@ module Silas
         end
       end
 
+      # :once is scoped to tool name AND arguments. Name-only matching was a
+      # footgun: approving a £5 refund would silently auto-approve a £5,000
+      # refund later in the same session. Identical repeat calls still skip
+      # re-approval; anything else re-parks. Graded gates (thresholds, ranges)
+      # belong in an approval lambda, not :once. (Hash#== is order-independent,
+      # so jsonb key order can't produce false negatives.)
       def previously_approved?(invocation)
         ToolInvocation.joins(:turn)
                       .where(silas_turns: { session_id: invocation.turn.session_id },
                              tool_name: invocation.tool_name, approval_state: "approved")
                       .where.not(id: invocation.id)
-                      .exists?
+                      .any? { |prior| prior.arguments == invocation.arguments }
       end
 
       # Compare-and-swap claim: only one racing execution wins.
@@ -173,11 +185,15 @@ module Silas
         claimed
       end
 
+      # Save/restore, not set/clear: a nested guarded_transaction must not
+      # clobber the outer guard on exit (the old `ensure ... = false` opened a
+      # checkpoint-guard hole for the remainder of the outer transaction).
       def guarded_transaction
-        Thread.current[GUARD_KEY] = true
+        previous = ActiveSupport::IsolatedExecutionState[GUARD_KEY]
+        ActiveSupport::IsolatedExecutionState[GUARD_KEY] = true
         ApplicationRecord.transaction { yield }
       ensure
-        Thread.current[GUARD_KEY] = false
+        ActiveSupport::IsolatedExecutionState[GUARD_KEY] = previous
       end
 
       def wrap_result(result)

data/lib/silas/mcp/handler.rb

@@ -4,9 +4,9 @@ require "securerandom"
 module Silas
   module Mcp
     # JSON-RPC handler for the hosted MCP endpoint. tools/call runs the tool
-    # THROUGH the Ledger, so the :agent_sdk path gets the same exactly-once and
-    # effect-mode semantics as :ruby_llm. Closes over one turn + its anchor step;
-    # authenticated by a per-turn bearer token in the URL query.
+    # THROUGH the Ledger, so a remote MCP caller gets the same exactly-once and
+    # effect-mode semantics as the in-process loop. Closes over one turn + its
+    # anchor step; authenticated by a bearer token in the URL query.
     class Handler
       TOOL_PREFIX = "mcp__silas__".freeze
 
@@ -50,8 +50,9 @@ module Silas
         invocation.reload
 
         if outcome == :parked
-          # v1 excludes approval-gated tools; if one slips through, fail loud.
-          { "isError" => true, "content" => [ text_content("approval-gated tools are not supported by :agent_sdk") ] }
+          # The hosted endpoint excludes approval-gated tools; if one slips
+          # through, fail loud rather than park a caller that can't wait.
+          { "isError" => true, "content" => [ text_content("approval-gated tools are not supported over the hosted MCP endpoint") ] }
         else
           { "content" => [ text_content(JSON.generate(invocation.result)) ] }
         end

data/lib/silas/mcp/server.rb

@@ -2,20 +2,20 @@ require "socket"
 
 module Silas
   module Mcp
-    # A minimal HTTP/1.1 server hosting the MCP Handler for the lifetime of one
-    # claude -p subprocess. Deliberately NOT Puma/Rack: the transport claude's
-    # MCP client needs (verified in the spike) is plain request/response JSON —
-    # one request per connection, application/json, no SSE — so a raw threaded
-    # TCPServer is fewer moving parts than embedding an app server in a worker.
+    # A minimal HTTP/1.1 server hosting the MCP Handler in-process. Deliberately
+    # NOT Puma/Rack: the transport MCP clients need (verified in the spike) is
+    # plain request/response JSON — one request per connection,
+    # application/json, no SSE — so a raw threaded TCPServer is fewer moving
+    # parts than embedding an app server in a worker.
     #
     # In-process: the Handler has direct access to the Ledger/models, so no
-    # cross-service call is needed and it works on any worker box.
+    # cross-service call is needed and it works on any worker box. This is the
+    # seam for the "mount your agent's tools as an MCP server" feature.
     class Server
       attr_reader :port
 
-      def self.start(turn:, step:, tools:, resolver:, host: Silas.config.agent_sdk_mcp_host)
-        token = SecureRandom.hex(16)
-        turn.update_columns(mcp_token: token)
+      def self.start(turn:, step:, tools:, resolver:, host: Silas.config.mcp_server_host)
+        token = SecureRandom.hex(16) # minted and compared in memory only
         handler = Handler.new(turn: turn, step: step, tools: tools, resolver: resolver, token: token)
         new(handler: handler, turn: turn, token: token, host: host).tap(&:boot)
       end

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

@@ -11,7 +11,7 @@ module Silas
       step = Step.find_or_create_by!(turn: turn, index: index)
 
       unless step.completed?
-        result = execute_model_call(turn, index)
+        result = execute_model_call(turn, index, step)
 
         # One transaction: the step's response, its terminal verdict, and the
         # pending ledger rows commit together — or none of them do.
@@ -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)
           )
@@ -48,7 +49,7 @@ module Silas
       end
     end
 
-    def execute_model_call(turn, index)
+    def execute_model_call(turn, index, step)
       assert_definitions_unchanged!(turn)
       engine = Silas.resolved_engine
       context = {
@@ -58,12 +59,28 @@ 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 }
       }
-      if (hook = Silas.config.around_model_call)
-        hook.call(context) { engine.execute_step(context) }
-      else
-        engine.execute_step(context)
+
+      # Live deltas: the engine yields Events, the buffer coalesces them into
+      # "silas.delta" notifications. A replayed step never reaches this method
+      # (the completed? guard above), so replay emits nothing. The emitter is
+      # created HERE and closed over by the inner block, so around_model_call
+      # hooks keep their existing one-argument contract and can't swallow it.
+      buffer = DeltaBuffer.new(turn: turn, step: step)
+      emitter = ->(event) { buffer.append(event.payload[:text].to_s) if event.type == :text_delta }
+
+      begin
+        if (hook = Silas.config.around_model_call)
+          hook.call(context) { engine.execute_step(context, &emitter) }
+        else
+          engine.execute_step(context, &emitter)
+        end
+      ensure
+        # Tail flush BEFORE the step row commits — the authoritative
+        # after_commit render must never race a straggling delta batch.
+        buffer.finish
       end
     end
 
@@ -94,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/tool.rb

@@ -7,6 +7,11 @@ module Silas
   #     approval :always                          # :never | :once | :always | lambda
   #     transactional!                            # or at_most_once! (default) / idempotent!
   #
+  # :once approves ONE (tool, arguments) pair per session — an identical repeat
+  # call skips re-approval; different arguments park again. For graded gates
+  # (e.g. auto-approve under a threshold) use a lambda:
+  #   approval ->(session:, input:) { input[:amount] > 5000 ? :user_approval : :approved }
+  #
   #     def call(order_id:, amount:, note: nil)
   #       ...
   #     end

data/lib/silas/version.rb

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

data/lib/silas.rb

@@ -24,6 +24,8 @@ require "silas/connection"
 require "silas/connections"
 require "silas/inbox"
 require "silas/inbox/cost"
+require "silas/inbox/delta_broadcaster"
+require "silas/delta_buffer"
 require "silas/budget"
 require "silas/registry"
 require "silas/agent"
@@ -31,21 +33,17 @@ require "silas/tools/load_skill"
 require "silas/tools/remember"
 require "silas/tools/recall"
 require "silas/tools/handoff"
-require "silas/engines/base"
-require "silas/agent_sdk/version_guard"
-require "silas/agent_sdk/stream_parser"
-require "silas/agent_sdk/cli"
 require "silas/mcp/handler"
 require "silas/mcp/server"
-require "silas/engines/agent_sdk"
+require "silas/engines/base"
 require "ruby_llm"
 require "silas/engines/ruby_llm"
 require "silas/message_builder"
 require "silas/instructions"
 require "silas/step_runner"
-require "silas/subprocess_runner"
 require "silas/eval" # after engines (ScriptedEngine < Engines::Base)
 require "silas/chat"
+require "silas/doctor"
 
 module Silas
   class << self
@@ -97,13 +95,16 @@ module Silas
 
     def reset_agent_memo! = (@agent = nil) # after Registry.install! swaps dirs
 
-    # The inference adapter instance. config.engine may be a symbol (:ruby_llm,
-    # :agent_sdk) or any object responding to #execute_step (specs, custom).
+    # The inference adapter instance. config.engine may be :ruby_llm or any
+    # object responding to #execute_step (specs, custom).
     def resolved_engine
       @resolved_engine ||=
         case config.engine
         when :ruby_llm then Engines::RubyLLM.new
-        when :agent_sdk then Engines::AgentSdk.new
+        when :agent_sdk
+          raise Error, "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."
         when Symbol then raise Error, "unknown engine #{config.engine.inspect}"
         else config.engine
         end

data/lib/tasks/silas_doctor.rake

@@ -0,0 +1,17 @@
+namespace :silas do
+  desc "Diagnose common Silas misconfigurations (provider key, queue adapter, model, migrations, tools, rescuer, cable, auth)"
+  task doctor: :environment do
+    glyph = { pass: "\e[32m✓\e[0m", warn: "\e[33m!\e[0m", fail: "\e[31m✗\e[0m" }
+    checks = Silas::Doctor.run
+
+    puts "silas:doctor — #{Silas::VERSION}"
+    checks.each do |check|
+      puts " #{glyph[check.status]} #{check.label}#{" — #{check.detail}" if check.detail.present?}"
+    end
+
+    failed = checks.count { |c| c.status == :fail }
+    warned = checks.count { |c| c.status == :warn }
+    puts "\n#{failed} failure(s), #{warned} warning(s)"
+    exit 1 if failed.positive?
+  end
+end