silas 0.3.2 → 0.5.0

data/lib/generators/silas/channel/channel_generator.rb

@@ -0,0 +1,72 @@
+require "rails/generators"
+
+module Silas
+  module Generators
+    # rails g silas:channel whatsapp
+    #
+    # A channel is two halves that must agree on one name, and hand-rolling
+    # them is where the mistakes live: inbound needs signature verification and
+    # a stable thread key, outbound needs the approval link to reach an
+    # operator. This scaffolds both, wired together, with the security
+    # decisions already made.
+    class ChannelGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Scaffold a Silas channel: outbound Channel class, inbound webhook controller, and its route."
+
+      # Channel identity is the filename (app/agent/channels/whatsapp.rb ->
+      # Agent::Channels::Whatsapp), and Registry#channels resolves it with
+      # `camelize`. A filename that isn't a snake_case identifier produces a
+      # constant Zeitwerk can't define, and the channel then fails at boot
+      # rather than here — so refuse it here, where the message is useful.
+      # (Rails' usual normalisation still applies first: `MsTeams` and
+      # `ms_teams` both land on ms_teams.)
+      def validate_name
+        return if file_name.match?(/\A[a-z_][a-z0-9_]*\z/)
+
+        raise Thor::Error, "#{file_name.inspect} is not a valid channel name — " \
+                           "it must be lowercase words separated by underscores, " \
+                           "starting with a letter (e.g. whatsapp, ms_teams)."
+      end
+
+      # Templates are .rb.tt (Rails' own convention): the .tt keeps ERB-bearing
+      # files out of the linter and off Zeitwerk's radar.
+      def create_channel
+        template "channel.rb.tt", "app/agent/channels/#{file_name}.rb"
+      end
+
+      # The webhook lives in the HOST app, not the engine: only the host knows
+      # the vendor's signature scheme and payload shape. The engine ships
+      # routes for Slack alone because it also ships Slack's verification.
+      def create_controller
+        template "controller.rb.tt", "app/controllers/agent/channels/#{file_name}_controller.rb"
+      end
+
+      def add_route
+        route %(post "/agent/channels/#{file_name}", to: "agent/channels/#{file_name}#create")
+      end
+
+      def show_next_steps
+        say <<~MSG, :green
+
+          Channel "#{file_name}" scaffolded:
+            app/agent/channels/#{file_name}.rb                        (outbound: answers + approvals)
+            app/controllers/agent/channels/#{file_name}_controller.rb (inbound: webhook)
+            config/routes.rb                                        POST /agent/channels/#{file_name}
+
+          Next:
+            1. Set the signing secret:
+               bin/rails credentials:edit  ->  silas:
+                                                 #{file_name}:
+                                                   signing_secret: ...
+            2. Fill in the three TODOs — the vendor's signature scheme, how a
+               message maps to a thread key, and how to post a message back.
+            3. Point the vendor's webhook at https://<your-host>/agent/channels/#{file_name}
+            4. Restart: app/agent/ registers at boot.
+
+          Full contract and a worked example: docs/channels.md
+        MSG
+      end
+    end
+  end
+end

data/lib/generators/silas/channel/templates/channel.rb.tt

@@ -0,0 +1,48 @@
+# <%= class_name %> channel — OUTBOUND delivery for sessions that started in
+# <%= human_name %>. Inbound lives in
+# app/controllers/agent/channels/<%= file_name %>_controller.rb.
+#
+# Identity is this filename: <%= file_name %>.rb -> Agent::Channels::<%= class_name %>,
+# and the controller starts sessions with channel: "<%= file_name %>", which is how
+# Silas finds this class again at delivery time. Delete this file to disable
+# the channel.
+#
+# Both methods run OFF the durable loop, in ChannelDeliveryJob — so a transport
+# outage retries the delivery without re-running a single tool or touching the
+# ledger. Raising here is safe; it costs a retry, not a duplicate side effect.
+class Agent::Channels::<%= class_name %> < Silas::Channel
+  # The agent's final answer for a turn.
+  def deliver_answer(session:, text:)
+    thread = session.metadata["<%= file_name %>"] || {}
+
+    # TODO: post `text` back to the conversation. `thread` is whatever the
+    # controller stashed in metadata (chat id, phone number, message id).
+    raise NotImplementedError,
+          "Agent::Channels::<%= class_name %>#deliver_answer: post #{text.inspect} to #{thread.inspect}"
+  end
+
+  # A tool has parked for human approval; the turn is holding zero compute
+  # until someone answers. `approval_url` mints a signed, expiring one-click
+  # link that works in any transport.
+  def deliver_approval(session:, invocation:)
+    approve = Silas::Channel.approval_url(invocation, :approve)
+    decline = Silas::Channel.approval_url(invocation, :decline)
+
+    # SECURITY: an approval must reach an OPERATOR, never whoever started the
+    # session — mailing the approve link to the customer who asked for the
+    # refund lets them approve it themselves. Deliver to your ops destination
+    # (a staff channel, an on-call number), and FAIL CLOSED when it isn't
+    # configured: no destination means no approval, not a silent one.
+    operator = Rails.application.credentials.dig(:silas, :<%= file_name %>, :operator)
+    if operator.blank?
+      Rails.logger.warn("[Silas] no credentials.silas.<%= file_name %>.operator — approval for " \
+                        "invocation #{invocation.id} not delivered (won't send it to the requester).")
+      return
+    end
+
+    # TODO: send `approve` / `decline` to `operator`, with enough context to
+    # decide: invocation.tool_name and invocation.arguments.
+    raise NotImplementedError,
+          "Agent::Channels::<%= class_name %>#deliver_approval: send #{approve} / #{decline} to #{operator}"
+  end
+end

data/lib/generators/silas/channel/templates/controller.rb.tt

@@ -0,0 +1,66 @@
+# <%= class_name %> channel — INBOUND webhook. Outbound delivery lives in
+# app/agent/channels/<%= file_name %>.rb.
+#
+# Inbound is pure trigger reuse: verify the request is genuine, derive a stable
+# thread key, and hand it to Channel.dispatch — which starts a session for a new
+# thread and continues the existing one for a reply. Nothing here touches the
+# durable loop.
+class Agent::Channels::<%= class_name %>Controller < ActionController::Base
+  # A webhook carries no browser session, so no CSRF token can exist. The
+  # signature below IS the authentication — do not remove one without the other.
+  skip_forgery_protection
+
+  before_action :verify_webhook!
+
+  def create
+    # TODO: derive a STABLE thread key — the same conversation must produce the
+    # same key every time, or every message starts a new session. Use the
+    # vendor's conversation/thread id, never a per-message id.
+    thread_key = params[:conversation_id].to_s
+    text       = params[:text].to_s
+
+    return head(:ok) if thread_key.blank? || text.blank?
+
+    Agent::Channels::<%= class_name %>.dispatch(
+      thread_key: thread_key,
+      input: text,
+      # Whatever deliver_answer needs to reply. Stored on the session, so keep
+      # it small and free of secrets — it is visible in the inbox.
+      metadata: { "<%= file_name %>" => { "conversation_id" => thread_key } }
+    )
+    head :ok
+  rescue Silas::TurnInProgressError
+    # One active turn per session is an invariant, not a queue: a reply that
+    # arrives mid-turn is dropped. Tell the user, or buffer it, if that matters
+    # for your transport.
+    head :ok
+  end
+
+  private
+
+  # Rejects anything not genuinely signed. Silas::Webhook.verify_hmac handles
+  # the parts that are identical everywhere — constant-time comparison, the
+  # replay window, and failing closed when no secret is configured; you supply
+  # the vendor's shape.
+  #
+  # TODO: match your vendor's scheme. The three that vary:
+  #   payload    what they sign. Slack signs "v0:#{timestamp}:#{body}"; GitHub
+  #              and Shopify sign the raw body. It must be request.raw_post,
+  #              never re-serialized params — different bytes, different HMAC.
+  #   prefix     what they put before the digest ("v0=", "sha256=", or "").
+  #   digest     :hex (nearly everyone) or :base64 (Shopify, Twilio).
+  def verify_webhook!
+    ok = Silas::Webhook.verify_hmac(
+      secret: Rails.application.credentials.dig(:silas, :<%= file_name %>, :signing_secret),
+      signature: request.headers["X-Signature"],
+      payload: request.raw_post,
+      # Omitting a timestamp disables replay protection: a captured request can
+      # then be re-sent forever. Pass the vendor's timestamp header if it sends
+      # one, and treat its absence as a reason to check the vendor's docs.
+      timestamp: request.headers["X-Signature-Timestamp"],
+      prefix: "sha256="
+    )
+    head(:unauthorized) unless ok
+    ok
+  end
+end

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

@@ -109,7 +109,8 @@ module Silas
             6. Schedules: edit app/agent/schedules/*, then `bin/rails silas:schedules`
             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.
+               Delete app/agent/channels/{slack,email}.rb to disable. Any other
+               transport: `bin/rails g silas:channel whatsapp`.
             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).

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

@@ -1,7 +1,7 @@
 Silas.configure do |config|
   # Inference engine: :ruby_llm (API key, any provider RubyLLM supports), or
   # any object responding to #execute_step. See silas/README.
-  config.engine = :ruby_llm
+  config.adapter = :ruby_llm
 
   # Any model your installed ruby_llm's registry resolves (newer models may
   # need `RubyLLM.models.refresh!` first). "claude-sonnet-4-5" is the balanced

data/lib/silas/{engines → adapters}/base.rb

@@ -3,11 +3,11 @@ module Silas
   # 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
+  # StepRunner coalesces :text_delta into "delta.silas" notifications (see
   # DeltaBuffer); everything else is available to custom engines/hooks.
   Event = Data.define(:type, :payload)
 
-  module Engines
+  module Adapters
     # The inference seam. An engine executes exactly ONE model call for a step
     # and reports what came back; the framework owns the loop, the ledger owns
     # tool execution.
@@ -25,4 +25,14 @@ module Silas
 
     ToolCall = Data.define(:id, :name, :arguments)
   end
+
+  # Renamed Engines:: -> Adapters:: in 0.4, removed in 2.0. Host apps subclass
+  # Adapters::Base for custom inference backends, so the old constant keeps
+  # resolving (with a warning) rather than blowing up on upgrade.
+  module Engines
+    def self.const_missing(name)
+      Silas.deprecator.warn("Silas::Engines::#{name} is deprecated; use Silas::Adapters::#{name}")
+      Silas::Adapters.const_get(name)
+    end
+  end
 end

data/lib/silas/adapters/ruby_llm.rb

@@ -0,0 +1,221 @@
+module Silas
+  module Adapters
+    # The :ruby_llm adapter: ONE model call per step, streamed, with the tool
+    # calls handed back unexecuted.
+    #
+    # RubyLLM's `Chat#complete` runs the whole agentic loop — model, run tools,
+    # feed results back, model again. Silas needs a single move, because the
+    # step boundary IS the durability boundary (checkpoint, ledger, park). So
+    # Chat is used as the BUILDER it is — it owns model resolution, schema
+    # normalisation, system instructions and message construction — and the
+    # execution goes one layer down to `Provider#complete`, which is exactly
+    # what Chat itself calls for a single turn.
+    #
+    # Everything here is RubyLLM's public API: Chat's attr_readers (model,
+    # messages, tools, schema, tool_prefs), Provider.resolve, and
+    # Provider#complete. (Until 0.5 this used tool proxies that threw
+    # `RubyLLM::Tool::Halt` to abort the loop from inside — RubyLLM 2.0 removes
+    # Halt precisely because the loop became caller-controlled, so this binding
+    # is both simpler now and the forward-compatible one.)
+    class RubyLLM < Base
+      def execute_step(context, &on_event)
+        chat = build_chat(context)
+
+        response = Silas.instrument(:step,
+                                    turn_id: context[:turn]&.id,
+                                    index: context[:index],
+                                    model: context[:model]) do
+          if on_event
+            # Fires before the HTTP request, matching what RubyLLM's
+            # before_message callback did under streaming — but ours, and
+            # explicitly ordered rather than incidentally so.
+            on_event.call(Event.new(type: :message_start, payload: {}))
+            complete(chat) do |chunk|
+              # Chunks carrying tool-call fragments have nil/empty content —
+              # only text streams.
+              text = chunk.content
+              on_event.call(Event.new(type: :text_delta, payload: { text: text })) if text.is_a?(String) && !text.empty?
+            end
+          else
+            complete(chat)
+          end
+        end
+
+        to_result(response, schema: chat.schema)
+      end
+
+      private
+
+      # One turn, tools advertised but never run. Streamed and sync return the
+      # same Message shape (the stream accumulator builds it), so there is no
+      # branch below this point.
+      def complete(chat, &block)
+        provider_for(chat.model).complete(
+          chat.messages,
+          tools: chat.tools,
+          tool_prefs: chat.tool_prefs,
+          temperature: nil,
+          model: chat.model,
+          schema: chat.schema,
+          &block
+        )
+      end
+
+      # Resolved from the model Chat already resolved, so the two can never
+      # disagree. Memoised per provider slug: the adapter instance is itself
+      # memoised on Silas (and dropped whenever config changes), and building a
+      # provider builds a Faraday connection — not something to redo per step.
+      # A benign race here costs one extra connection, never correctness.
+      def provider_for(model_info)
+        @providers ||= {}
+        @providers[model_info.provider] ||=
+          ::RubyLLM::Provider.resolve(model_info.provider).new(::RubyLLM.config)
+      end
+
+      def build_chat(context)
+        chat = begin
+          ::RubyLLM.chat(model: context[:model])
+        rescue ::RubyLLM::ModelNotFoundError
+          raise Silas::Error,
+                "Model #{context[:model].inspect} is not in ruby_llm's model registry. " \
+                "Newer models may need a registry refresh (`RubyLLM.models.refresh!`), " \
+                "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: with_schema renders the provider's
+        # structured-output dialect. The response comes back as a JSON string
+        # (Chat#complete would have parsed it for us) — to_result does that.
+        chat.with_schema(context[:final_answer]) if context[:final_answer].present?
+        # with_tools (plural), not with_tool — 2.0 drops the singular form and
+        # the plural exists in both.
+        context[:tools].each { |definition| chat.with_tools(SchemaProxy.new(definition)) }
+
+        replay_history(chat, context[:messages])
+        chat
+      end
+
+      # Rebuild the provider conversation from Silas's canonical rows. The last
+      # user message is delivered via ask-equivalent add_message; the whole
+      # array goes to the provider on complete.
+      def replay_history(chat, messages)
+        i = 0
+        while i < messages.length
+          msg = messages[i]
+          case msg[:role]
+          when "user"
+            chat.add_message(role: :user, content: msg[:content])
+            i += 1
+          when "assistant"
+            chat.add_message(
+              role: :assistant,
+              content: text_from(msg[:content]),
+              tool_calls: tool_calls_from(msg[:content])
+            )
+            i += 1
+          when "tool"
+            # Anthropic requires every tool_result for one assistant turn to sit
+            # in a single user message. The model can emit parallel tool_use
+            # blocks, so batch all consecutive tool results into one Raw message
+            # (a one-element batch is the ordinary single-tool-call case).
+            first_id = msg[:tool_call_id]
+            blocks = []
+            while i < messages.length && messages[i][:role] == "tool"
+              t = messages[i]
+              blocks << {
+                type: "tool_result",
+                tool_use_id: t[:tool_call_id],
+                content: JSON.generate(t[:content])
+              }
+              i += 1
+            end
+            chat.add_message(role: :tool, tool_call_id: first_id,
+                             content: ::RubyLLM::Content::Raw.new(blocks))
+          else
+            i += 1
+          end
+        end
+      end
+
+      def text_from(blocks)
+        Array(blocks).select { |b| b["type"] == "text" }.map { |b| b["text"] }.join
+      end
+
+      def tool_calls_from(blocks)
+        calls = Array(blocks).select { |b| b["type"] == "tool_call" }
+        return nil if calls.empty?
+
+        calls.to_h do |b|
+          [ b["id"], ::RubyLLM::ToolCall.new(id: b["id"], name: b["name"], arguments: b["arguments"]) ]
+        end
+      end
+
+      def to_result(assistant, schema:)
+        blocks = []
+        content = structured_content(assistant, schema:)
+        if content.is_a?(Hash)
+          # with_schema active: persist the parsed payload 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,
+                      "arguments" => tc.arguments || {} }
+          ToolCall.new(id: tc.id, name: tc.name, arguments: (tc.arguments || {}).stringify_keys)
+        end
+
+        Result.new(
+          blocks: blocks,
+          tool_calls: tool_calls,
+          stop_reason: tool_calls.any? ? "tool_use" : "end_turn",
+          usage: { input_tokens: assistant.tokens&.input, output_tokens: assistant.tokens&.output }
+        )
+      end
+
+      # Chat#complete normally JSON-parses a schema response before handing it
+      # back; calling the provider directly means we do it. A response that
+      # doesn't parse stays a string rather than raising — a malformed payload
+      # is the model's problem to see in the transcript, not a crash.
+      def structured_content(assistant, schema:)
+        content = assistant.content
+        return content unless schema && content.is_a?(String) && !assistant.tool_call?
+
+        begin
+          JSON.parse(content)
+        rescue JSON::ParserError
+          content
+        end
+      end
+
+      # Carries a Silas tool's schema to the provider. Subclasses RubyLLM::Tool
+      # so it satisfies whatever the provider tool-renderers read (today: name,
+      # description, params_schema, parameters, provider_params) without Silas
+      # having to track that list.
+      #
+      # It has no #execute on purpose. Nothing calls it — the ledger owns tool
+      # execution — and RubyLLM::Tool#execute raises NotImplementedError, so if
+      # anything ever did, it fails loudly instead of feeding the model a
+      # sentinel.
+      class SchemaProxy < ::RubyLLM::Tool
+        def initialize(definition)
+          super()
+          @definition = definition
+        end
+
+        def name = @definition["name"]
+        def description = @definition["description"]
+
+        # RubyLLM 1.x reads params_schema; 2.0 renames it parameters_schema
+        # (alongside parameters -> declared_parameters and provider_params ->
+        # provider_options, which we inherit rather than override). Answering to
+        # both is two lines and makes the proxy version-agnostic — confirmed
+        # against ruby_llm edge by the CI canary.
+        def params_schema = @definition["input_schema"]
+        def parameters_schema = @definition["input_schema"]
+      end
+    end
+  end
+end

data/lib/silas/channel.rb

@@ -57,6 +57,34 @@ module Silas
       Rails.application.message_verifier(TOKEN_PURPOSE)
     end
 
+    # A full one-click approve/decline URL for ANY transport — the signed token
+    # is the credential, so the link works in a WhatsApp message, a Discord
+    # embed, or an SMS exactly as it does in email.
+    #
+    # Built from the engine's own route set plus the discovered mount point,
+    # because a channel runs in a delivery job with no routing scope. The host
+    # is required and never guessed: a hostless approval link is a dead link,
+    # so this raises with the fix rather than shipping one.
+    def self.approval_url(invocation, action, host: nil)
+      options = default_url_options.merge(host: host || default_url_options[:host])
+      if options[:host].blank?
+        raise Error, "Silas::Channel.approval_url needs a host. Set " \
+                     "config.action_mailer.default_url_options = { host: \"example.com\" } " \
+                     "(or Rails.application.routes.default_url_options), or pass host:."
+      end
+
+      Silas::Engine.routes.url_helpers.channels_approval_url(
+        token: token_for(invocation, action),
+        script_name: Silas::Inbox.mount_path, **options
+      )
+    end
+
+    def self.default_url_options
+      mailer = Rails.application.config.action_mailer.default_url_options || {}
+      Rails.application.routes.default_url_options.merge(mailer)
+    end
+    private_class_method :default_url_options
+
     # --- outbound interface (subclasses implement) ---
     def deliver_answer(session:, text:)
       raise NotImplementedError, "#{self.class}#deliver_answer"
@@ -65,5 +93,12 @@ module Silas
     def deliver_approval(session:, invocation:)
       raise NotImplementedError, "#{self.class}#deliver_approval"
     end
+
+    # OPTIONAL: ask_question parks ping this instead of deliver_approval —
+    # define it on transports that can collect free text (the question is
+    # invocation.arguments["question"]; settle with invocation.answer!).
+    # Channels without it are simply not pinged; the question waits in the
+    # inbox. Deliberately NOT declared here raising NotImplementedError:
+    # respond_to? is the capability check.
   end
 end

data/lib/silas/chat.rb

@@ -59,11 +59,11 @@ module Silas
     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
+    # "delta.silas" 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|
+      subscription = ActiveSupport::Notifications.subscribe("delta.silas") do |*args|
         payload = args.last
         print_delta(payload) if @session && payload[:session_id] == @session.id
       end