silas 0.3.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8ece90334c6059bd396179bfae54b62ebd8abc483d72309da718dbb8e147845
-  data.tar.gz: '014359b0b35a36e7b34b796fbb9194f99c49bf39a1901b4b82cb7b94a10c0ea0'
+  metadata.gz: 0f722788fa436905b6ea94ee9666ca71013fa6eace683f7d3dc8eec4f257fbe2
+  data.tar.gz: 85d3ae116127d4b91207526d7936440092250854380938a94eba177cd26f3eeb
 SHA512:
-  metadata.gz: 25e3610da0c9a62b6e9f2a0f956e01c989c62eec40bfdee6703b1bd9206821bb6b4a7988726671b57cd53949ae518239a76d76511cc260b3279db9a36b4f38c4
-  data.tar.gz: f891bf52671a8cd2c7fdc9041b036194939995dc4de7dee7bdd8f09cea986593bc526681d161d41add81b16cfe9257d75df7599e09a7fb85d5af52a9b117828d
+  metadata.gz: 645b843c5dbde892fa0725c1f33302bf39b3b10eef43ff14b0828efeb0420ead72d82e34b9bb3828cf99aa8f880db4f6017f2913023884a679385ca68a21ae41
+  data.tar.gz: 2b5b8df36d8747fde43b1eccffb466f17a3a9ef430ebc77b055b36c73ff987c4e07c66eb14ef2265d34b37b1ff824cf4681737a2bca1333e4e7dad88c8db142b

data/CHANGELOG.md

@@ -1,5 +1,198 @@
 # 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
+worked, the naming locked down before 1.0 freezes it, and the durable loop
+finally observable.
+
+### Fixed
+
+- **The email approval channel had never worked.** Both the approval email
+  template and the confirmation page called `approval_url`/`approval_path`,
+  but the route is declared inside `namespace :channels`, so the real helpers
+  are `channels_approval_url`/`_path`. Rendering raised — meaning
+  **`ChannelMailer#approval` blew up and the "your agent needs approval" email
+  was never delivered**, and the confirmation page 500'd. If you relied on
+  email approvals, you were silently never notified that a money-moving call
+  was parked. Found by writing the first specs for these surfaces.
+
+### Changed (breaking, pre-1.0)
+
+- **The inference seam is now `Adapters::`, not `Engines::`** — and
+  `config.adapter`, not `config.engine`. "Engine" meant two unrelated things
+  in one namespace: the Rails engine at `Silas::Engine`, and the pluggable
+  inference backend. Every comparable seam disambiguates — ActiveJob has
+  `QueueAdapters::`, ActiveStorage `Service::`, RubyLLM `Provider`. Done now
+  because 1.0 freezes the public API and host apps subclass this seam.
+  **Nothing breaks today**: `Silas::Engines::Base`, `config.engine`, and
+  `Silas.resolved_engine` all still resolve, warn through the new deprecator,
+  and are removed in 2.0.
+- **Notification names follow the Rails convention** `<event>.silas` (like
+  `sql.active_record`). The two pre-existing events were backwards:
+  `silas.step` → `step.silas`, `silas.delta` → `delta.silas`. Update any
+  subscriber; `subscribe(/\.silas\z/)` now catches everything.
+
+### Added
+
+- **Instrumentation for the durable loop.** It emitted almost nothing before:
+  a turn could start, park for a human, be rescued after a `kill -9`, breach a
+  budget and finish without a single line. Ten events now — `turn`, `step`,
+  `tool`, `park`, `resume`, `approval`, `budget`, `rescue`, `nondeterminism`,
+  `delta` — with documented payloads that always carry `turn_id`/`session_id`,
+  so a subscriber never has to join. **`tool.silas`** times the tool's own
+  execution and reports how it settled (the most useful span in the system);
+  **`resume.silas`** carries `parked_for` — how long the human actually took.
+  `Silas::LogSubscriber` (modelled on Solid Queue's) turns them into log lines
+  at operator-filterable levels: parks and rescues INFO, budget WARN, failed
+  turns and nondeterminism ERROR, per-token chatter DEBUG — and stays silent
+  when the rescuer did nothing.
+- **`Silas.deprecator`** — an `ActiveSupport::Deprecation` registered in
+  `app.deprecators[:silas]`, so hosts silence or raise on Silas deprecations
+  exactly as they do Rails'. Every message names the replacement *and* the
+  removal version.
+- **Coverage for the four money-path surfaces that had none** (36 specs):
+  `Channels::SlackController` (unsigned / wrong-secret / stale-timestamp
+  requests refused end to end; retries and bot messages ignored; buttons
+  settle through the same `approve!`/`decline!`),
+  `Channels::ApprovalsController` (tampered, garbage, expired and
+  wrong-purpose tokens refused; **GET never mutates**, so a link preview or
+  scanner cannot approve a refund; a replayed link on a settled invocation
+  422s), `AgentMailbox` (References → In-Reply-To → Message-ID threading, so
+  replies continue rather than restart), and `ChannelMailer` (renders, shows
+  the arguments, embeds two distinct absolute links whose tokens verify back).
+- **Quality tooling, enforced in CI**: `rubocop-rails-omakase` (Rails' own
+  style baseline, zero offenses), SimpleCov with a **90% line-coverage floor
+  that fails the build** (actual: 92.5%), Brakeman and bundler-audit (clean —
+  the single deliberate CSRF suppression is documented with its reasoning in
+  `config/brakeman.ignore`), and a `rake zeitwerk:check` job that eager-loads
+  every constant to catch naming violations lazy tests never see.
+- **Dependency contract specs.** Silas reaches into Solid Queue and RubyLLM
+  internals, where a rename breaks *recovery* silently. Ten specs pin them:
+  the dead-process error classes the rescuer allowlists,
+  `FailedExecution#retry`, the Solid Queue >= 1.2 continuations floor,
+  RubyLLM's `with_schema`/`before_message`/`Tool::Halt`/model registry and the
+  error classes `retry_on` names, and `resume_errors_after_advancing` staying
+  false. Plus an allowed-to-fail CI canary against ruby_llm edge, for early
+  warning on the 2.0 horizon.
+- **`docs/conventions.md`** — the naming and structure rules (why the seam is
+  `Adapters::`; the deliberate `class << self` vs `module_function` split) and
+  the audited posture: nothing mass-assigned, no `raw`/`html_safe` anywhere,
+  `Time.current` throughout, indexes on query paths rather than every foreign
+  key. Written down so nobody "fixes" something load-bearing.
+
+No migration. 336 specs green on SQLite and Postgres.
+
 ## 0.3.2
 
 - **The `timeout` budget no longer counts time spent parked for approval.**

data/README.md

@@ -104,15 +104,15 @@ hundreds of times per release (results in `chaos_host/results/`):
   deploy that changes tools/skills mid-turn fails the turn loudly
   (`NondeterminismError`) instead of resuming into a different agent.
 
-## Engine
+## Adapter
 
-Inference is one pluggable seam (`config.engine`): `:ruby_llm` — API-key auth
+Inference is one pluggable seam (`config.adapter`): `:ruby_llm` — API-key auth
 via [RubyLLM](https://rubyllm.com), any provider it supports — is the default
 and the production path. Compose resilience via `config.around_model_call`, or
 swap in any object responding to `#execute_step` (the eval harness and the
 chaos tests do exactly that).
 
-> The experimental `:agent_sdk` engine (a `claude -p` subprocess) was removed
+> The experimental `:agent_sdk` adapter (a `claude -p` subprocess) was removed
 > in 0.2: its subscription-auth rationale was structurally unreachable, and it
 > carried weaker guarantees than `:ruby_llm` on every axis. Its in-process MCP
 > server survives and returns as a first-class *mount your tools as MCP*
@@ -192,21 +192,27 @@ 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
 
-Turns stream. The `:ruby_llm` engine emits text deltas as the model responds:
+Turns stream. The `:ruby_llm` adapter emits text deltas as the model responds:
 `bin/rails silas:chat` prints tokens as they arrive, and the inbox trace
 renders them live over Turbo (coalesced to ~10Hz). Deltas are decoration over
 the durable rows — never persisted, never fed back to the model, and a
 replayed step renders from its row with no deltas at all, so streaming adds
 zero risk to the durability contract. Custom sinks subscribe to the
-`"silas.delta"` notification (`{ session_id:, turn_id:, step_id:, step_index:,
+`"delta.silas"` notification (`{ session_id:, turn_id:, step_id:, step_index:,
 text: }`, where `text` is the accumulated string so far — filter by ids;
 notifications are process-global).
 

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

@@ -112,6 +112,8 @@ module Silas
         # replays completed steps from rows, resuming where it left off.
         if (reason = Budget.exceeded_reason(turn))
           turn.update!(status: "waiting", failure_reason: reason)
+          Silas.instrument(:budget, reason: reason, turn_id: turn.id)
+          Silas.instrument(:park, reason: "budget", turn_id: turn.id, detail: reason)
           return
         end
 

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/jobs/silas/dead_job_rescuer_job.rb

@@ -15,7 +15,13 @@ module Silas
     queue_as { Silas.config.queue_name }
 
     def perform
+      Silas.instrument(:rescue) { |payload| sweep(payload) }
+    end
+
+    def sweep(payload)
       ToolInvocation.expire_stale!
+      payload[:rescued] = 0
+      payload[:stranded] = 0
       return 0 unless defined?(SolidQueue)
 
       rescued = 0
@@ -24,9 +30,10 @@ module Silas
           failed.retry
           rescued += 1
         elsif failed.job&.class_name == "Silas::AgentLoopJob"
-          fail_stranded_turn(failed)
+          payload[:stranded] += 1 if fail_stranded_turn(failed)
         end
       end
+      payload[:rescued] = rescued
       rescued
     end
 
@@ -40,13 +47,14 @@ module Silas
     # loudly with its approvals expired.
     def fail_stranded_turn(failed)
       turn = Turn.find_by(id: failed.job.arguments&.dig("arguments", 0))
-      return unless turn&.active?
+      return false unless turn&.active?
 
       exception = failed.error&.dig("exception_class")
       turn.expire_pending_approvals!("turn failed: #{exception}")
       turn.finish!(:failed, reason: "job_failed")
       Rails.logger&.error("[silas] turn #{turn.id} failed: its loop job died with " \
                           "#{exception} — #{failed.error&.dig('message')}")
+      true
     end
   end
 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,9 +38,32 @@ 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)
+      Silas.instrument(:approval, action: "approved", tool: tool_name, by: by,
+                                  invocation_id: id, turn_id: turn_id)
+      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
 
@@ -49,6 +76,8 @@ module Silas
       assert_turn_resumable!
       update!(status: "failed", approval_state: "declined", approved_by: by,
               decline_reason: reason, result: { "denied" => reason })
+      Silas.instrument(:approval, action: "declined", tool: tool_name, by: by,
+                                  invocation_id: id, turn_id: turn_id)
       resume_turn!
     end
 
@@ -56,8 +85,11 @@ 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")
       end
     end
@@ -90,7 +122,9 @@ module Silas
       # instantly re-park on "timeout" — pathological for a gate whose whole
       # point is waiting for a person. Cost/token budgets stay cumulative;
       # they measure real spend.
+      parked_for = turn.updated_at ? (Time.current - turn.updated_at).to_f : nil
       turn.update!(status: "queued", started_at: Time.current)
+      Silas.instrument(:resume, turn_id: turn.id, parked_for: parked_for)
       AgentLoopJob.perform_later(turn.id)
     end
   end

data/app/models/silas/turn.rb

@@ -21,8 +21,14 @@ module Silas
     def active?    = ACTIVE_STATUSES.include?(status)
     def parked?    = status == "waiting" || status == "in_doubt"
 
+    # Duration on this event spans the WHOLE turn, parked time included — it
+    # answers "how long did the customer wait", not "how much compute".
     def finish!(new_status, reason: nil)
-      update!(status: new_status.to_s, failure_reason: reason, finished_at: Time.current)
+      Silas.instrument(:turn, status: new_status.to_s, reason: reason, turn_id: id,
+                              session_id: session_id, agent: session.agent_name,
+                              steps: steps.count) do
+        update!(status: new_status.to_s, failure_reason: reason, finished_at: Time.current)
+      end
     end
 
     def canceled? = status == "canceled"

data/app/views/silas/channel_mailer/approval.text.erb

@@ -3,7 +3,7 @@ Your agent needs approval to run: <%= @invocation.tool_name %>
 Arguments:
 <%= JSON.pretty_generate(@invocation.arguments) %>
 
-Approve: <%= silas.approval_url(token: @approve_token) %>
-Decline: <%= silas.approval_url(token: @decline_token) %>
+Approve: <%= silas.channels_approval_url(token: @approve_token) %>
+Decline: <%= silas.channels_approval_url(token: @decline_token) %>
 
 These links expire; do not forward them.

data/app/views/silas/channels/approvals/show.html.erb

@@ -1,7 +1,7 @@
 <% if @invocation&.awaiting_approval? %>
   <h1>Approval needed: <%= @invocation.tool_name %></h1>
   <pre><%= JSON.pretty_generate(@invocation.arguments) %></pre>
-  <%= form_with url: silas.approval_path(token: params[:token]), method: :post do %>
+  <%= form_with url: silas.channels_approval_path(token: params[:token]), method: :post do %>
     <button type="submit">Confirm <%= @action %></button>
   <% end %>
 <% else %>

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/brakeman.ignore

@@ -0,0 +1,11 @@
+{
+  "ignored_warnings": [
+    {
+      "warning_type": "Cross-Site Request Forgery",
+      "warning_code": 7,
+      "fingerprint": "64dd0725204c2cd5d6b2dba2fac6c278d20cebd07aaed38493f229193f44ed79",
+      "file": "app/controllers/silas/channels/base_controller.rb",
+      "note": "Deliberate: Silas::Channels::BaseController serves inbound WEBHOOKS, which no browser session originates, so a CSRF token cannot exist. Each route authenticates the request itself instead: Slack routes verify an HMAC-SHA256 request signature with a 300s replay window (Silas::Slack.verify_signature, covered by spec/silas/channels/slack_controller_spec.rb), and the email approve/decline routes require a purpose-scoped, expiring MessageVerifier token whose possession IS the credential — CSRF would add nothing an attacker holding the token could not already do (covered by spec/silas/channels/approvals_controller_spec.rb, including tampered/expired/wrong-purpose/replayed tokens and the GET-never-mutates property). The inbox controllers keep protect_from_forgery; the JSON API is ActionController::API and is token-authenticated."
+    }
+  ]
+}

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