silas 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9abd9603ae899da9a789ded30f092f11f1881ddc9abd2f0edf2638421f469abb
-  data.tar.gz: 16a684a62b54346ee51d4e7b9f6cb92ec19c2d95e7027667b432044d9a1e7f71
+  metadata.gz: 0f722788fa436905b6ea94ee9666ca71013fa6eace683f7d3dc8eec4f257fbe2
+  data.tar.gz: 85d3ae116127d4b91207526d7936440092250854380938a94eba177cd26f3eeb
 SHA512:
-  metadata.gz: 9518d703a421ed47d1c59e9cb74cdbd46686b8a783a1f5aea8f90f5911e0e27f5ccc5fc86da22c8ebe870a3d811b7de28e5abfc2ff837ab7dbc47722d13e3dcc
-  data.tar.gz: 954efe8fac65a18a0d936bafda946bcca96e8dda35201d06637d8f6ee5a8ca425ecd50ab322d2f137e7c0d03b2e97321db7d5cedfc5ac7d0a4b016ddf3184b63
+  metadata.gz: 645b843c5dbde892fa0725c1f33302bf39b3b10eef43ff14b0828efeb0420ead72d82e34b9bb3828cf99aa8f880db4f6017f2913023884a679385ca68a21ae41
+  data.tar.gz: 2b5b8df36d8747fde43b1eccffb466f17a3a9ef430ebc77b055b36c73ff987c4e07c66eb14ef2265d34b37b1ff824cf4681737a2bca1333e4e7dad88c8db142b

data/CHANGELOG.md

@@ -1,5 +1,115 @@
 # Changelog
 
+## 0.5.0 (2026-07-26)
+
+Two new loop primitives (replay-safe compaction, ask_question), a whole-channel
+generator, the adapter rebound onto RubyLLM's public single-turn seam, and
+per-agent schedules. Chaos-gated: **295 kill/deploy cycles across both stores —
+zero duplicate side effects, byte-identical replay** — including a new compact
+mode that kills mid-summarisation and asserts the compaction claim is
+exactly-once and the rebuilt provider messages are byte-identical
+(`chaos_host/RESULTS.md`).
+
+### Added
+
+- **Per-agent schedules.** Named agents own their cron the way they own tools
+  and skills: `app/agents/analyst/schedules/monday_kpis.md` is discovered as
+  `agents/analyst/monday_kpis`, compiled by `silas:schedules` under a
+  collision-free recurring key, and its ticks start **the analyst** — a staff
+  member's schedule never wakes the root agent. `.rb` handlers resolve under
+  the agent's namespace (`Agents::Analyst::Schedules::MondayKpis`).
+
+- **`ask_question` — the agent can park to ask a human something.**
+  Information, not permission: the model calls the new builtin with a
+  question, the turn parks at zero compute through the same machinery as
+  approvals (TTL, channel ping, resume gate), and the operator's free-text
+  reply becomes the tool result the model resumes with
+  (`{"answer" => "..."}`). Answer from the inbox (a question card with a text
+  box replaces approve/decline) or the API
+  (`POST /silas/api/v1/approvals/:id/answer {text:}`); `decline!` remains the
+  refusal path, and an unanswered question expires as
+  `{"answer" => nil, "note" => "question expired unanswered"}`. Channels are
+  pinged only if they implement `deliver_question` — buttons are the wrong UI
+  for free text, so transports without it simply leave the question in the
+  inbox. Disable with `config.ask_question = false`.
+
+  **Upgrade note:** adding a builtin changes the definitions digest, so turns
+  parked across the upgrade fail loudly on resume (the nondeterminism guard
+  working as designed). Settle parked turns before upgrading, or set
+  `config.ask_question = false` to keep the old digest.
+
+- **Context compaction that survives replay.** Long sessions used to grow
+  until the provider rejected the prompt and the turn failed. Now, when the
+  measured context passes `config.compact_at` (default 0.9 of the model's
+  registry context window; set an Integer for an absolute token threshold, or
+  nil to disable), Silas summarises all prior turns into a `silas_compactions`
+  row and the conversation continues — the current turn is never compacted.
+
+  The design constraint is the durability contract: replayed executions must
+  see byte-identical message arrays, so a summary can never be computed at
+  build time. Compaction is an *effect*, made exactly-once the way tool
+  effects are — claimed compare-and-swap (unique index per session + span),
+  generated once, then read deterministically from the row forever. A crash
+  mid-summary leaves a pending row the resume finishes; a crash mid-step
+  replays against the identical compacted history. New `compact.silas`
+  instrumentation event (duration = the summarisation call). Chaos-gated with
+  a dedicated mode: kill -9 during the compacting turn, including
+  mid-summarisation.
+
+### Changed
+
+- **The `:ruby_llm` adapter no longer fights the library.** `Chat#complete`
+  runs RubyLLM's whole agentic loop — model, execute tools, feed results back,
+  model again — but Silas needs a single move, because the step boundary *is*
+  the durability boundary. It used to get one by registering tool proxies that
+  threw `RubyLLM::Tool::Halt` to abort the loop from the inside.
+
+  Chat is now used as the builder it is (it owns model resolution, schema
+  normalisation, system instructions and message construction) and execution
+  drops one layer to `RubyLLM::Provider#complete` — the same call Chat makes
+  internally for a single turn. Entirely public API, and the adapter got
+  smaller: no `Tool::Halt`, no hunting back through `chat.messages` for the
+  assistant reply, and the `before_message` streaming-timing oddity is gone in
+  favour of an event Silas emits itself.
+
+  **This removes Silas's exposure to the largest RubyLLM 2.0 breaking change.**
+  2.0 deletes `Tool::Halt` precisely because the loop became caller-controlled;
+  Silas no longer needs it either way. The adapter also now calls `with_tools`
+  (2.0 drops the singular `with_tool`) and its schema proxy answers to both
+  `params_schema` and `parameters_schema` (2.0 renames it), so the tool path is
+  version-agnostic today. No behaviour change for users.
+
+### Added
+
+- **`rails g silas:channel <name>`** — scaffolds a whole channel, not half of
+  one. Channels were reachable before (`Channel.dispatch` is a ~50-line seam)
+  but the engine ships webhook routes for Slack only, so any other transport
+  meant hand-rolling a controller, a route, and signature verification with no
+  documented contract. The generator writes the outbound `Channel` subclass,
+  a signature-verifying inbound controller, and the route that joins them —
+  with the security decisions already made: verify before anything else, sign
+  over the raw body, fail closed on a missing secret, and send approvals to an
+  operator rather than to whoever started the session.
+- **`Silas::Webhook.verify_hmac`** — the parts of webhook verification that are
+  identical for every vendor (constant-time comparison, replay window,
+  fail-closed on a missing secret), with the vendor's shape (`payload`,
+  `prefix`, `digest`) supplied by the caller. `Silas::Slack.verify_signature`
+  now delegates to it and keeps its exact v0 scheme.
+- **`Silas::Channel.approval_url(invocation, action)`** — a signed, expiring
+  one-click approve/decline link for *any* transport, built from the engine's
+  route set and the discovered mount point, so it works from a delivery job
+  with no routing scope. Raises with the fix when no host is configured rather
+  than minting a dead link.
+- `docs/channels.md`: the inbound/outbound contract, a per-vendor signature
+  table, and a worked WhatsApp Cloud API example.
+
+### Removed
+
+- `demo/refund-desk` and `demo/churn-desk`. Both were copy-paste kits whose
+  READMEs instructed deleting a file the generated eval still asserted on —
+  broken on arrival. `examples/playground` is the example; `docs/why-silas.md`
+  and `docs/vs-eve.md` now point at it.
+
 ## 0.4.0
 
 The architecture-and-hardening release: one shipped feature that had never

data/README.md

@@ -192,11 +192,17 @@ An agent is reached by more than a method call:
 
 - **`schedules/`** — `app/agent/schedules/*.md` (cron frontmatter, body = the turn
   input) or `*.rb` handlers. `bin/rails silas:schedules` compiles them into
-  Solid Queue recurring tasks. A scheduled run is a normal durable turn.
+  Solid Queue recurring tasks. A scheduled run is a normal durable turn. Named
+  agents own their cron the same way they own tools:
+  `app/agents/analyst/schedules/monday_kpis.md` ticks start the analyst, not
+  the root agent.
 - **`channels/`** — `app/agent/channels/*.rb` bind email (Action Mailbox) and
   Slack to the loop. A new thread starts a session, a reply continues it, and
   approvals render as Slack buttons / signed email links that call the same
   `approve!`/`decline!`. Outbound delivery is idempotent and off the durable loop.
+  `bin/rails g silas:channel whatsapp` scaffolds any other transport — a
+  signature-verifying webhook and the outbound half, wired together. See
+  [docs/channels.md](https://github.com/danielstpaul/silas/blob/main/docs/channels.md).
 
 ## Streaming
 

data/app/controllers/silas/api/v1/approvals_controller.rb

@@ -29,6 +29,16 @@ module Silas
         rescue Silas::Error => e
           render json: { error: e.message }, status: :conflict
         end
+
+        # POST /silas/api/v1/approvals/:id/answer  { text: "..." }
+        # ask_question's verdict: the text becomes the tool result.
+        def answer
+          invocation = Silas::ToolInvocation.find(params[:id])
+          invocation.answer!(text: params[:text].to_s.strip, by: current_actor)
+          render json: invocation_json(invocation.reload)
+        rescue Silas::Error => e
+          render json: { error: e.message }, status: :conflict
+        end
       end
     end
   end

data/app/controllers/silas/inbox/invocations_controller.rb

@@ -24,6 +24,14 @@ module Silas
         respond_error(e)
       end
 
+      # ask_question's verdict: the operator's text becomes the tool result.
+      def answer
+        @invocation.answer!(text: params[:text].to_s.strip, by: current_actor)
+        respond_resolved
+      rescue Silas::Error => e
+        respond_error(e)
+      end
+
       private
 
       def set_invocation

data/app/jobs/silas/channel_delivery_job.rb

@@ -24,6 +24,21 @@ module Silas
       channel = Channel.for_session(invocation.turn.session)
       return release!(ToolInvocation, invocation.id, :notified_at) unless channel
 
+      # Questions want free text, and approve/decline buttons are the wrong UI
+      # for that — so a question pings only channels that implement
+      # deliver_question. Without it the claim is KEPT (no retries): the
+      # question waits in the inbox, which every install has.
+      if invocation.question?
+        unless channel.respond_to?(:deliver_question)
+          Rails.logger&.info("[Silas] #{channel.class} has no deliver_question — " \
+                             "question ##{invocation.id} awaits its answer in the inbox")
+          return
+        end
+        return with_release(ToolInvocation, invocation.id, :notified_at) do
+          channel.deliver_question(session: invocation.turn.session, invocation: invocation)
+        end
+      end
+
       with_release(ToolInvocation, invocation.id, :notified_at) do
         channel.deliver_approval(session: invocation.turn.session, invocation: invocation)
       end

data/app/models/silas/compaction.rb

@@ -0,0 +1,32 @@
+module Silas
+  # One compaction row replaces session turns 0..up_to_turn_index with a
+  # persisted summary. Written exactly once (the unique index on
+  # session_id + up_to_turn_index is the compare-and-swap claim), read
+  # deterministically forever after — which is what lets MessageBuilder stay
+  # byte-identical across crash replays: the summary is a row, never a
+  # runtime computation.
+  class Compaction < ApplicationRecord
+    STATUSES = %w[pending completed].freeze
+
+    belongs_to :session, class_name: "Silas::Session"
+    belongs_to :up_to_turn, class_name: "Silas::Turn"
+
+    validates :status, inclusion: { in: STATUSES }
+    validates :up_to_turn_index, presence: true
+
+    scope :completed, -> { where(status: "completed") }
+
+    def completed? = status == "completed"
+
+    # The compaction MessageBuilder applies when building turn: the newest
+    # completed summary strictly before it. (A compaction can never cover its
+    # own turn — it is created during turn N covering 0..N-1 — so `<` is
+    # always satisfiable; it also keeps an eval or replay of an older turn
+    # from seeing a summary written after it.)
+    def self.latest_for(turn)
+      completed.where(session_id: turn.session_id)
+               .where(up_to_turn_index: ...turn.index)
+               .order(:up_to_turn_index).last
+    end
+  end
+end

data/app/models/silas/tool_invocation.rb

@@ -2,7 +2,7 @@ module Silas
   class ToolInvocation < ApplicationRecord
     STATUSES = %w[pending started completed failed in_doubt].freeze
     EFFECT_MODES = %w[transactional at_most_once idempotent].freeze
-    APPROVAL_STATES = [ nil, "required", "approved", "declined", "expired" ].freeze
+    APPROVAL_STATES = [ nil, "required", "approved", "answered", "declined", "expired" ].freeze
 
     include Silas::Inbox::Broadcastable
 
@@ -18,6 +18,10 @@ module Silas
     def in_doubt?  = status == "in_doubt"
     def awaiting_approval? = approval_state == "required"
 
+    # A parked ask_question — same park, different verdict: it is ANSWERED
+    # (free text becomes the tool result), never approved into execution.
+    def question? = tool_name == "ask_question"
+
     # Outbound: when a channel-bound invocation parks for approval, ping the
     # channel off-loop (covers both approval-gate and in-doubt parking).
     after_update_commit :notify_channel_approval, if: :should_notify_approval?
@@ -34,6 +38,10 @@ module Silas
     # parked job exited normally; its continuation is consumed). For an
     # in-doubt invocation, approval means "it did not run — re-execute".
     def approve!(by: nil)
+      if question?
+        raise Error, "invocation #{id} is a question — settle it with answer!, not approve! " \
+                     "(approving would try to EXECUTE ask_question, which has no execution)"
+      end
       assert_parked!
       assert_turn_resumable!
       update!(status: "pending", approval_state: "approved", approved_by: by)
@@ -42,6 +50,23 @@ module Silas
       resume_turn!
     end
 
+    # Answer a parked question. The text IS the tool result — the model resumes
+    # with {"answer" => text}, persisted like any other settled invocation, so
+    # replay determinism costs nothing. (decline! also works on a question: a
+    # refusal to answer, delivered as {"denied" => reason}.)
+    def answer!(text:, by: nil)
+      raise Error, "invocation #{id} (#{tool_name}) is not a question — answer! settles ask_question only" unless question?
+      raise Error, "an answer cannot be blank — decline! is the way to refuse a question" if text.blank?
+
+      assert_parked!
+      assert_turn_resumable!
+      update!(status: "completed", approval_state: "answered", approved_by: by,
+              result: { "answer" => text })
+      Silas.instrument(:approval, action: "answered", tool: tool_name, by: by,
+                                  invocation_id: id, turn_id: turn_id)
+      resume_turn!
+    end
+
     # Decline: for an approval gate, eve's shape — the tool is not executed
     # and the model sees {denied: reason} as the result, then the loop
     # continues. For an in-doubt invocation, decline means "assume it ran /
@@ -60,8 +85,9 @@ module Silas
     # their turns (parked-forever ghosts are a bug, not a feature).
     def self.expire_stale!(now: Time.current)
       where(approval_state: "required").where(approval_expires_at: ..now).find_each do |inv|
-        inv.update!(approval_state: "expired", status: "failed",
-                    result: { "denied" => "approval expired" })
+        result = inv.question? ? { "answer" => nil, "note" => "question expired unanswered" }
+                               : { "denied" => "approval expired" }
+        inv.update!(approval_state: "expired", status: "failed", result: result)
         Silas.instrument(:approval, action: "expired", tool: inv.tool_name,
                                     invocation_id: inv.id, turn_id: inv.turn_id)
         inv.turn.finish!(:failed, reason: "approval_expired")

data/app/views/silas/inbox/invocations/_approval_card.html.erb

@@ -1,14 +1,28 @@
-<div class="approval">
-  <h3>Approval needed — <%= invocation.tool_name %></h3>
-  <pre><%= pretty_args(invocation.arguments) %></pre>
-  <%# silas_engine_path, not bare helpers: this partial is broadcast-rendered
-      through the HOST's renderer, where engine route helpers don't exist and
-      the mounted proxy has no routing scope to lean on. %>
-  <%= form_with url: silas_engine_path(:approve_inbox_invocation_path, invocation), method: :post, class: "inline" do %>
-    <button class="btn approve">Approve</button>
-  <% end %>
-  <%= form_with url: silas_engine_path(:decline_inbox_invocation_path, invocation), method: :post, class: "decline-form" do %>
-    <textarea name="reason" rows="2" placeholder="Reason (optional — sent back to the agent as the tool result)"></textarea>
-    <button class="btn decline">Decline</button>
-  <% end %>
-</div>
+<%# silas_engine_path, not bare helpers: this partial is broadcast-rendered
+    through the HOST's renderer, where engine route helpers don't exist and
+    the mounted proxy has no routing scope to lean on. %>
+<% if invocation.question? %>
+  <div class="approval">
+    <h3>The agent has a question</h3>
+    <p class="question-text"><%= invocation.arguments["question"] %></p>
+    <%= form_with url: silas_engine_path(:answer_inbox_invocation_path, invocation), method: :post, class: "decline-form" do %>
+      <textarea name="text" rows="3" placeholder="Your answer — sent back to the agent as the tool result"></textarea>
+      <button class="btn approve">Answer</button>
+    <% end %>
+    <%= form_with url: silas_engine_path(:decline_inbox_invocation_path, invocation), method: :post, class: "inline" do %>
+      <button class="btn decline">Decline to answer</button>
+    <% end %>
+  </div>
+<% else %>
+  <div class="approval">
+    <h3>Approval needed — <%= invocation.tool_name %></h3>
+    <pre><%= pretty_args(invocation.arguments) %></pre>
+    <%= form_with url: silas_engine_path(:approve_inbox_invocation_path, invocation), method: :post, class: "inline" do %>
+      <button class="btn approve">Approve</button>
+    <% end %>
+    <%= form_with url: silas_engine_path(:decline_inbox_invocation_path, invocation), method: :post, class: "decline-form" do %>
+      <textarea name="reason" rows="2" placeholder="Reason (optional — sent back to the agent as the tool result)"></textarea>
+      <button class="btn decline">Decline</button>
+    <% end %>
+  </div>
+<% end %>

data/config/routes.rb

@@ -13,6 +13,7 @@ Silas::Engine.routes.draw do
         member do
           post :approve
           post :decline
+          post :answer
         end
       end
     end
@@ -40,6 +41,7 @@ Silas::Engine.routes.draw do
       member do
         post :approve
         post :decline
+        post :answer
       end
     end
   end

data/db/migrate/20260725000002_create_silas_compactions.rb

@@ -0,0 +1,26 @@
+class CreateSilasCompactions < ActiveRecord::Migration[8.1]
+  def change
+    create_table :silas_compactions do |t|
+      t.references :session, null: false, index: false # covered by the unique composite below
+      # Provenance only (never in a WHERE — see docs/conventions.md on indexes):
+      # the turn whose index is up_to_turn_index, kept so an operator can walk
+      # from a summary back to the rows it replaced.
+      t.references :up_to_turn, null: false, index: false
+      # THE query + claim column: a compaction covers session turns
+      # 0..up_to_turn_index inclusive.
+      t.integer :up_to_turn_index, null: false
+      t.string :status, null: false, default: "pending" # pending | completed
+      t.text :summary
+      t.integer :tokens_before   # the measured context size that triggered this
+      t.integer :input_tokens    # what the summarisation call itself cost
+      t.integer :output_tokens
+      t.string :model            # which model wrote the summary
+      t.timestamps
+    end
+
+    # The compare-and-swap claim: only one execution may create the compaction
+    # for a given span, however many racing replays attempt it. Also serves the
+    # read path (latest completed compaction per session).
+    add_index :silas_compactions, [ :session_id, :up_to_turn_index ], unique: true
+  end
+end

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).