silas 0.6.1 → 0.6.3

data/docs/providers.md

@@ -0,0 +1,171 @@
+# Providers & gateways
+
+Silas has exactly one inference seam: the `:ruby_llm` adapter. Every model
+call goes through [RubyLLM](https://rubyllm.com), so every provider RubyLLM
+speaks — Anthropic, OpenAI, Gemini, Bedrock, Vertex AI, Azure, Mistral,
+DeepSeek, Perplexity, xAI, OpenRouter, local runtimes — is available to your
+agents with zero Silas-specific glue. Keys live in
+`config/initializers/ruby_llm.rb`; **which provider serves a turn is decided
+by the model id**. Nothing in `app/agent/` changes when the provider does.
+
+## How a model id picks a provider
+
+RubyLLM ships a model registry (1,100+ entries, refreshed upstream from
+[models.dev](https://models.dev)). Silas resolves the agent's `model:` — from
+`agent.yml`, falling back to `config.default_model` — against that registry;
+the matching entry names the provider, and the adapter builds that provider's
+client. The same entry supplies the numbers Silas runs on, per
+(model, provider):
+
+- **pricing** — the cost lines in the inbox and the `max_cost` budget;
+- **context window** — the `compact_at` compaction threshold.
+
+So switching provider is switching model id. A model the registry doesn't
+know fails fast at the first step with the fix in the error
+(`RubyLLM.models.refresh!`, or pick a registry model). And because a
+registry's tie-breaks can change across upgrades, Silas stamps the resolved
+provider on every step row — historical cost lines price against the
+(model, provider) that actually served them, forever.
+
+## Direct providers
+
+The installer's `config/initializers/ruby_llm.rb` maps environment keys in —
+RubyLLM never reads provider keys from the environment by itself:
+
+```ruby
+RubyLLM.configure do |c|
+  c.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+end
+```
+
+Every provider follows the same pattern (`openai_api_key`,
+`gemini_api_key`, …— the full list is in
+[RubyLLM's configuration docs](https://rubyllm.com/configuration/)). For
+cloud-platform shops the "enterprise gateway" is usually just the native
+provider:
+
+| Platform | Keys |
+|---|---|
+| AWS Bedrock | `bedrock_api_key`, `bedrock_secret_key`, `bedrock_region` (+ optional `bedrock_session_token`) |
+| GCP Vertex AI | `vertexai_project_id`, `vertexai_location` (+ optional `vertexai_service_account_key`) |
+| Azure OpenAI | `azure_api_base`, `azure_api_key` (or `azure_ai_auth_token`) |
+
+Verify any of this with `bin/rails silas:doctor` — it reports which providers
+have credentials configured and resolves your default model with its price:
+
+```
+ ✓ provider credentials — anthropic
+ ✓ model claude-sonnet-4-5 — anthropic · $3/$15 per MTok
+```
+
+## OpenRouter: one key, 300+ models
+
+[OpenRouter](https://openrouter.ai) is a first-class RubyLLM provider, and
+the registry ships its catalog (341 models as of ruby_llm 1.16) — one key
+buys your agents Claude, GPT, Gemini, Llama, DeepSeek and the rest, billed
+in one place.
+
+```ruby
+# config/initializers/ruby_llm.rb
+RubyLLM.configure do |c|
+  c.openrouter_api_key = ENV["OPENROUTER_API_KEY"]
+end
+```
+
+Routed models use slash-form ids — `creator/model`, exactly as OpenRouter
+lists them:
+
+```yaml
+# app/agent/agent.yml
+model: anthropic/claude-sonnet-4.5   # via OpenRouter
+```
+
+or globally:
+
+```ruby
+Silas.configure do |c|
+  c.default_model = "anthropic/claude-sonnet-4.5"
+end
+```
+
+The two id families never collide: `claude-sonnet-4-5` is Anthropic direct,
+`anthropic/claude-sonnet-4.5` is the same model via OpenRouter, and each
+resolves to its own registry entry. That per-route entry is the one your
+cost lines and compaction thresholds follow — the route you run, not the
+origin provider. Concretely, in the shipped registry the direct entry lists
+a 200K context window while OpenRouter's route lists 1M, so `compact_at`
+triggers where the route actually overflows.
+
+`silas:doctor` confirms the whole chain:
+
+```
+ ✓ provider credentials — openrouter
+ ✓ model anthropic/claude-sonnet-4.5 — openrouter · $3/$15 per MTok
+```
+
+## OpenAI-compatible gateways
+
+Self-hosted and enterprise gateways (LiteLLM, Vercel AI Gateway, an internal
+proxy) mostly speak the OpenAI chat-completions dialect. Two shapes:
+
+**The gateway serves OpenAI model ids** (`gpt-5.2`, …) — point the OpenAI
+provider at it:
+
+```ruby
+RubyLLM.configure do |c|
+  c.openai_api_key  = ENV["GATEWAY_API_KEY"]
+  c.openai_api_base = "https://gateway.internal/v1"
+end
+```
+
+**The gateway serves models.dev slash ids** (`anthropic/claude-sonnet-4.5`,
+…, as Vercel's AI Gateway does) — repoint the OpenRouter provider, which
+already speaks plain chat-completions against exactly those ids:
+
+```ruby
+RubyLLM.configure do |c|
+  c.openrouter_api_key  = ENV["AI_GATEWAY_API_KEY"]
+  c.openrouter_api_base = "https://ai-gateway.vercel.sh/v1"
+end
+```
+
+Either way the model id must still resolve in the registry — the registry
+entry is where Silas gets pricing and the context window, and a gateway
+that bills differently can be corrected per model with the
+`config.model_prices` override ([configuration](configuration.md)).
+
+Two gateway footnotes, both cheap to check with one real turn:
+
+- RubyLLM renders system messages as role `developer` (OpenAI's current
+  dialect) through these providers. OpenRouter normalises it; if your
+  gateway insists on `system`, set `c.openai_use_system_role = true`.
+- Streaming must pass through as SSE. If the operator inbox shows a turn
+  completing without live text, the gateway buffered the stream.
+
+## Local runtimes
+
+Ollama and GPUStack are RubyLLM providers too (`ollama_api_base`,
+`gpustack_api_base`/`gpustack_api_key`). Local models aren't in the shipped
+registry, so refresh it after configuring — `RubyLLM.models.refresh!` asks
+every configured provider for its live model list and merges the results —
+then use the id it lists. Local models carry no registry pricing: the inbox
+shows their token counts with "cost unavailable", and a `max_cost` budget
+can't bind (only priced tokens count toward it) — list the model in
+`config.model_prices` to restore both.
+
+## Failover and wrapping
+
+Provider outages, rate-limit retries and model failover belong at the
+inference seam, not in your tools. `config.around_model_call` wraps every
+model call the loop makes:
+
+```ruby
+Silas.configure do |c|
+  c.around_model_call = ->(ctx, &call) do
+    RubyLLM::Resilience.chain(:anthropic) { call.() }
+  end
+end
+```
+
+Whatever runs inside still lands in the same durable step — a failover
+retry that succeeds is recorded exactly like a first-try success.

data/docs/traces.md

@@ -0,0 +1,131 @@
+# The trace schema
+
+Every step your agent takes is rows in **your** database — transactional,
+priced, and joinable to the business rows the agent touched. Most frameworks
+treat their execution record as internal bookkeeping in a store beside your
+app. Silas treats it as **a documented, versioned interface**: your analytics,
+your dashboards, and your own tooling are meant to query these tables
+directly.
+
+That is the whole point of the trace living where it does. An external
+observability platform can show you what the agent said; it cannot join the
+tool call to the `refunds` row it created, in one query, with no export:
+
+```sql
+SELECT ti.tool_name, ti.arguments, ti.approved_by, r.amount_pence
+FROM silas_tool_invocations ti
+JOIN refunds r ON r.id = json_extract(ti.result, '$.refund_id')
+WHERE ti.approval_state = 'approved';
+```
+
+## The contract
+
+Columns documented here are **stable within a major version**: they may gain
+siblings in any release, but renames and semantic changes only happen at a
+major, and appear in the CHANGELOG under an upgrade note. Columns *not* listed
+here are internal — query them if you like, but they can move without notice.
+
+## `silas_sessions` — a conversation
+
+| Column | Meaning |
+|---|---|
+| `agent_name` | Which agent owns the session (`"agent"` = the root agent). |
+| `status` | `active` \| `archived`. **Note:** parked work is a *turn* state, not a session state. |
+| `parent_session_id` | Set when this session was created by a handoff or delegation — the lineage the inbox renders. |
+| `channel` | The transport that started it (`"slack"`, `"email"`, …), `NULL` for direct/API. |
+| `metadata` | JSON. Channel-specific context (e.g. the inbound email's sender). Plain `json`, not `jsonb` — the schema works identically on SQLite and Postgres. |
+
+## `silas_turns` — one request, run durably
+
+| Column | Meaning |
+|---|---|
+| `index` | Position within the session; `(session_id, index)` is unique. |
+| `status` | `queued` \| `running` \| `waiting` (parked for a human) \| `in_doubt` \| `completed` \| `failed` \| `canceled`. At most one non-final turn per session — enforced by `index_silas_turns_single_active`. |
+| `input` | What the user (or channel, or schedule) asked. |
+| `instructions_snapshot` | The system prompt as rendered **once** at turn start; immutable after. What the model actually saw, forever. |
+| `definitions_digest` | Hash of tool schemas + skill descriptions at turn start — the nondeterminism guard that refuses to resume a turn against a changed agent. |
+| `failure_reason` | Why a `failed` turn failed (`max_steps`, `definitions_changed`, `job_failed`, budget reasons, …). |
+| `input_tokens` / `output_tokens` / `cost_microcents` | Accumulated across the turn's steps. 1,000,000 microcents = $1. |
+| `budget_overrides` | JSON. A human's top-up on a budget-parked turn, beating `agent.yml` limits. |
+| `started_at` / `finished_at` | Wall-clock bounds. Note `started_at` resets on resume after a park — `limits.timeout` measures *active* time, not human deliberation. |
+
+## `silas_steps` — one model call
+
+| Column | Meaning |
+|---|---|
+| `index` | Position within the turn; `(turn_id, index)` is unique — at most one persisted model response per slot. |
+| `status` | `started` \| `completed`. |
+| `model` / `provider` | What actually served this step. Provider is stamped at execution so historical cost survives registry changes. |
+| `response_blocks` | The model's full response — text, tool calls — as JSON. Replay rebuilds the conversation from these rows. |
+| `stop_reason` | Why the model stopped (`tool_use`, `end_turn`, …). |
+| `terminal` | Write-once after completion; **the** loop-control column. A resumed continuation must re-derive the identical step sequence from it. |
+| `input_tokens` / `output_tokens` | This step's usage; cost derives from these plus `(model, provider)` pricing at read time. |
+
+## `silas_tool_invocations` — one tool call, exactly once
+
+The heart of the ledger.
+
+| Column | Meaning |
+|---|---|
+| `tool_call_id` | The model's id for the call. `(step_id, tool_call_id)` is unique — **this index is the exactly-once key**. |
+| `tool_name` / `arguments` | What was called, with what. Arguments are model-authored — render escaped. |
+| `status` | `pending` \| `started` \| `completed` \| `failed` \| `in_doubt`. |
+| `effect_mode` | `transactional` \| `at_most_once` \| `idempotent` — **snapshotted from the tool class at creation**, so editing a tool mid-park cannot change the semantics of an existing invocation. |
+| `result` | The tool's return value (or the question's answer, or `{"denied": reason}`). |
+| `approval_state` | `NULL` (no gate) \| `required` \| `approved` \| `declined` \| `expired`. `NULL` on a completed invocation means *policy cleared it*; a value means *a decision was made* — that distinction is load-bearing for audit. |
+| `approved_by` | Who decided. `NULL` on an auto-cleared gate, an identity string on a human verdict. |
+| `approval_expires_at` / `decline_reason` | The TTL, and the human's stated reason. |
+
+**The free labeled dataset.** `approval_state` + `approved_by` +
+`decline_reason` record a human's verdict on a specific agent action, with
+full context, in production, at zero annotation cost. If you ever train or
+evaluate against your own traffic, this is where the labels already are.
+
+## `silas_compactions` — summaries that survive replay
+
+One row per compacted span: `session_id`, `up_to_turn_index` (unique
+together — exactly one summary per span no matter how many replays race),
+`status`, `summary`, and what the summarisation itself cost (`tokens_before`,
+`input_tokens`, `output_tokens`, `model`). Deterministic by construction: the
+message builder reads the row, never recomputes.
+
+## `silas_memories` — what the agent knows across sessions
+
+`agent_name`, `scope` (`agent` private \| `app` shared), `subject`,
+`attribute_name`, `content`, `status` (`active` \| `superseded`),
+`superseded_by_id`, and provenance (`session_id`, `turn_id`). Approval-gated
+on write by default. **Single-tenant per deployment** — see
+[guarantees](guarantees.md) for the boundary.
+
+## Queries you already own
+
+Cost per agent per day:
+
+```sql
+SELECT s.agent_name, date(t.created_at) AS day, SUM(t.cost_microcents)/1e6 AS dollars
+FROM silas_turns t JOIN silas_sessions s ON s.id = t.session_id
+GROUP BY 1, 2 ORDER BY 2 DESC;
+```
+
+Every action a specific person approved, with what it did:
+
+```sql
+SELECT ti.created_at, ti.tool_name, ti.arguments, ti.result
+FROM silas_tool_invocations ti
+WHERE ti.approved_by = 'dana@example.com' ORDER BY ti.created_at DESC;
+```
+
+What parked, and for how long, before a human answered:
+
+```sql
+SELECT ti.tool_name, ti.approval_state,
+       (julianday(ti.updated_at) - julianday(ti.created_at)) * 24 AS hours_parked
+FROM silas_tool_invocations ti
+WHERE ti.approval_state IN ('approved','declined','expired');
+```
+
+The replay principle behind all of this: `Silas::MessageBuilder` reconstructs
+the exact prompt at any step from these rows alone, deterministically. Nothing
+in the trace reads the clock or mutable state — which is why a crashed turn
+resumes byte-identically, and why the trace you query is the trace that
+actually ran.

data/docs/tutorial.md

@@ -220,10 +220,12 @@ app/agents/escalations/
 ```
 
 Restart, and the desk can delegate durably: the built-in `handoff` tool files
-a **self-contained brief** that starts a linked session for the named agent —
-exactly-once-guarded and cycle-checked — instead of two models chatting
-freely (a cost and audit hazard, deliberately unblessed). Talk to a
-specialist directly with `Silas.agent("escalations").start(input: "…")` or
+a **self-contained brief** that starts a linked session for the named agent,
+rather than letting two models chat freely (a cost and audit hazard,
+deliberately unblessed). A handoff is cycle-checked and at-most-once: a crash
+mid-handoff parks it in doubt for a person instead of starting the colleague
+twice. Talk to a specialist directly with
+`Silas.agent("escalations").start(input: "…")` or
 `bin/rails silas:chat AGENT=escalations`; the inbox filters by agent.
 
 ## 10 · Fit the governors: budgets and compaction

data/docs/vs-eve.md

@@ -1,7 +1,7 @@
 # Silas vs eve
 
-> Written **2026-07-26** against **eve 0.27.6** and Silas 0.5.x, from eve's
-> published docs and source. Both projects move fast — if you're reading this
+> Written **2026-07-29** against **eve 0.27.8** (source and shipped docs, not
+> marketing) and Silas 0.6.x. Both projects move fast — if you're reading this
 > much later, re-verify before deciding.
 
 Silas and eve share the same organising idea: **an agent is a directory of
@@ -16,22 +16,31 @@ So the honest first cut is simply your stack: **a TypeScript team should use
 eve; a Rails team should use Silas.** The rest of this page is for people near
 the boundary — and for the differences that go deeper than language.
 
+One framing note, because it keeps this page honest: eve is a platform
+company's product, shipping weekly at roughly twenty-five times Silas's source
+volume. A surface-area comparison is a race Silas isn't running. What follows
+compares the **guarantees and the shape**, which is where the projects
+genuinely differ.
+
 ---
 
 ## The comparison
 
-| | Silas | eve (0.27.6) |
+| | Silas | eve (0.27.8) |
 |---|---|---|
 | **Shape** | A gem in your Rails app — your database, your job queue, your auth, one deploy. | A TypeScript service beside your app, with its own workflow store and deploy. |
 | **Authoring** | A directory of plain files. | A directory of plain files — genuinely the same idea. |
-| **Durable loop** | Survives `kill -9`, resumes from the last completed step. Chaos-gated every release: zero duplicate effects, byte-identical replay, SQLite + Postgres. | Workflow-engine replay; interrupted steps re-run. |
+| **Durable loop** | Survives `kill -9`, resumes from the last completed step. A `kill -9` harness (275-run matrix, SQLite + Postgres) is run before each release, results committed to the repo. | Workflow-engine replay; its own docs: "A step interrupted mid-execution re-runs." |
 | **Tool-effect semantics** | **Exactly-once** for DB-recorded effects (`transactional!` — effect + ledger in one transaction). Default at-most-once: an ambiguous crash **parks for a human**. | **At-least-once, documented as such** — "make non-idempotent side effects like charges or emails idempotent, or gate them with approval." Dedup is the tool author's job. |
-| **Human-in-the-loop** | Parks at zero compute; cleared from inbox, Slack, signed email, or API; parks expire; `ask_question` for the reverse direction. | `needsApproval` on tools. |
-| **Operator surface** | A production inbox mounted in your app: live traces, approval cards, audit trail, cost accounting, web chat. | A dev TUI ("not a production chat UI or customer-facing dashboard"); production UIs are assembled from templates. |
-| **Memory** | Shipped: approval-gated triples with provenance and supersession. | Deliberately out of scope. |
+| **Human-in-the-loop** | Parks at zero compute for days; cleared from inbox, Slack, signed email, or API; **approvals expire** (`approval_ttl`); verdicts are compare-and-swap (one card can't be spent twice); `ask_question` for the reverse direction. | `needsApproval` on tools, with typed input requests (options, freeform, display hints — a nicer request shape than Silas's). Approvals have **no expiry**: an unanswered one waits forever. |
+| **A message arriving mid-approval** | **Dropped today** — the sender is told delivery succeeded. An honest gap, fix scheduled. | **Held and replayed** after the approval settles — eve is ahead here. |
+| **A deploy while work is parked** | The turn **refuses to resume against a changed agent** (`NondeterminismError`, loud). Snapshot-resume is planned. | The next turn silently uses the new deployment's instructions, model, and tools — a parked approval can resume into a different agent than the one that asked. |
+| **Operator surface** | A production inbox mounted in your app: activity feed, approval cards, audit trail, cost accounting, handoff lineage, web chat — behind your auth. | A capable dev TUI (drives remote deployments: `--url`, `/deploy`, `/connect`) plus frontend SDKs and templates; the production operator surface is assembled by you. |
+| **Memory** | Cross-session memory ships: approval-gated triples with provenance and supersession. | `defineState` ships typed **session-scoped** durable state; anything cross-session "belongs in an external store" (its own docs) — integrations and patterns, not a shipped subsystem. |
+| **Evals** | Scenario DSL with scripted model decisions running the **real ledger and real tools against real rows**, keyless, as a deploy gate. | A broader harness: `defineEval`, dataset fan-out, gate-vs-soft severity, LLM-as-judge, reporters. eve is ahead on breadth; the difference in kind is that Silas evals exercise the real transactional machinery. |
+| **Channels** | Slack + email built in, **routable to named agents**; a generator scaffolds any transport. | More first-party surfaces (Slack, Discord, Teams, Telegram, Twilio, GitHub, Linear, chat SDK), growing quickly. |
 | **Ecosystem** | Ruby/Rails. | TypeScript + the AI SDK — a much larger ecosystem, with Vercel's distribution behind it. |
-| **Channels & integrations** | Slack + email built in; a generator scaffolds any transport. | More first-party surfaces, growing quickly. |
-| **Maturity** | Early (0.5.x); the durability contract is chaos-verified on every release. | Weeks old publicly; backed by a platform company, shipping at platform speed. |
+| **Maturity** | Early (0.6.x); pre-1.0, evolving deliberately. | Pre-1.0 and explicit about it: "prefer breaking changes… no legacy fallback logic." Backed by a platform company. |
 
 ---
 
@@ -50,22 +59,37 @@ framework where you don't have to.
 
 **Ambiguity parks.** At-least-once means a crash can re-fire a side effect.
 Silas's default is at-most-once with **in-doubt → human**: it never
-double-fires, and an ambiguous call waits for a person.
+double-fires, and an ambiguous call waits for a person. Everyone has
+approved/denied; Silas also has *we don't know, so someone decides*.
+
+**A park is a contract.** Approvals expire rather than ghosting forever, a
+verdict can't be spent twice, and a resumed turn is guaranteed to be the same
+agent that parked — or it fails loudly rather than continuing as something
+else. eve makes the opposite trade on that last point, deliberately: deploys
+apply to live sessions. For exploratory agents that's convenient; for an agent
+whose parked action a human already approved, Silas treats silently redefining
+it as an audit failure.
 
 **The operator surface ships.** `mount Silas::Engine` and the inbox exists —
-held/working/filed rail, live traces, approval cards, audit trail, cost, web
-chat — behind your app's own auth.
+the feed, approval cards, audit trail, cost, lineage — behind your app's own
+auth.
 
-**Memory ships.** Approval-gated, with provenance and supersession. eve
-reasonably says "bring your own"; Silas ships the batteries.
+**The trace lives in your database.** Every step, tool call, argument, result,
+approval and cost is rows in *your* schema, joinable to the business rows the
+agent actually touched. See [traces](traces.md) — the schema is a documented,
+versioned interface, not internal bookkeeping.
 
 ## Where eve goes further
 
 - **The ecosystem.** TypeScript and the AI SDK are where most of the agent
   world lives — more examples, more integrations, a bigger hiring pool, and
   Vercel's reach.
-- **Surface breadth and velocity.** More first-party channels and
-  integrations today, with a platform company's release cadence.
+- **Surface breadth and velocity.** More first-party channels, a fuller evals
+  harness, frontend SDKs, session workspaces with file tools, and a platform
+  company's release cadence.
+- **Deferred input while parked.** A message arriving during an approval is
+  held and replayed. Silas currently drops it — the most honest single row on
+  this page, and scheduled work.
 - **Sandboxing posture.** Container sandboxes are integral to eve's design.
   Silas ships an interim Docker seam and reaches microVM-class isolation via
   the [hermetic](https://github.com/danielstpaul/hermetic) gem.
@@ -88,6 +112,6 @@ app's database, that's where the agent belongs.
 
 ---
 
-*Claims about eve come from its docs and source at 0.27.6, quoted or
+*Claims about eve come from its source and docs at 0.27.8, quoted or
 paraphrased in good faith; corrections welcome. Silas's numbers are
 reproducible from `chaos_host/results/`.*

data/docs/why-silas.md

@@ -28,8 +28,8 @@ beside your app — it's a gem inside the Rails app you already deploy:
 
 Every serious framework makes the loop durable. Silas draws the line a step
 past that, and verifies it with a chaos harness that `kill -9`s live agents
-hundreds of times per release (zero duplicate effects, byte-identical replay
-— [guarantees](guarantees.md)):
+mid-turn — a 275-run matrix before each release, zero duplicate effects,
+byte-identical replay ([guarantees](guarantees.md)):
 
 - **Exactly-once tool effects.** A `transactional!` tool's database write and
   the ledger's record of it commit in **one transaction**. A crash mid-refund
@@ -62,10 +62,10 @@ rails new desk -m https://raw.githubusercontent.com/danielstpaul/silas/main/temp
 
 ## The honest notes
 
-- **Silas is early** — 0.5.x, and the guarantees are proven by a reproducible
-  chaos harness rather than years of production traffic. The contract is
-  measured on every release, and it's stated precisely so you know exactly
-  what's promised.
+- **Silas is early** — 0.6.x, and the guarantees are proven by a reproducible
+  chaos harness rather than years of production traffic. The maintainer runs
+  the matrix before each release and commits the results, and the contract is
+  stated precisely so you know exactly what's promised.
 - **Rails-only, on purpose.** If your team lives in TypeScript, eve is
   excellent and closer to home — the [comparison](vs-eve.md) is honest about
   that in both directions.

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

@@ -1,4 +1,5 @@
 require "rails/generators"
+require "silas/doctor" # ASYNC_QUEUE_REMEDY — one remedy text, two surfaces
 
 module Silas
   module Generators
@@ -125,6 +126,26 @@ module Silas
             9. Restart your server if it was running (app/agent/ registers at boot).
         MSG
       end
+
+      # Rails defaults development to the in-process :async adapter, which the
+      # doctor step above FAILS — without this the documented happy path ends
+      # on a red X. Detected, printed, never written: a gsub against the host's
+      # database.yml no-ops silently the moment they've edited it, and a
+      # force-written cable.yml clobbers whatever Redis config they run.
+      def show_queue_adapter_remedy
+        return unless defined?(::ActiveJob::Base)
+        return unless ::ActiveJob::Base.queue_adapter.class.name.to_s.include?("AsyncAdapter")
+
+        say <<~MSG, :yellow
+
+          Queue adapter: this app is on ActiveJob's in-process :async adapter, and
+          `bin/rails silas:doctor` fails it — :async runs a re-enqueued continuation
+          concurrently with the original, which double-executes steps and breaks
+          exactly-once tool effects.
+
+          #{Silas::Doctor::ASYNC_QUEUE_REMEDY}
+        MSG
+      end
     end
   end
 end

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

@@ -39,6 +39,11 @@ Silas.configure do |config|
   # installed registry (units per 1k tokens; 1e6 units = $1):
   # config.model_prices["your-fine-tune"] = { in: 3000, out: 15_000 }
 
+  # Which agent an inbound Slack thread or email wakes. Unmatched threads wake
+  # the root agent; a name that isn't in app/agents/ fails boot, not a webhook.
+  # config.channel_routes = { "slack" => { "C0BILLING" => "bookkeeper" },
+  #                           "email" => { "billing@example.com" => "bookkeeper" } }
+
   # Where eval scenarios live (bin/rails silas:eval).
   # config.eval_dir = "test/agent_evals"
 end

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

@@ -3,7 +3,9 @@
 #
 #   export ANTHROPIC_API_KEY=sk-ant-...
 #
-# Any provider RubyLLM supports works the same way (openai_api_key, etc.).
+# Any provider RubyLLM supports works the same way (openai_api_key, etc.) —
+# OpenRouter, OpenAI-compatible gateways, and local runtimes are covered in
+# the Silas guide docs/providers.md (shipped in the gem: `bundle show silas`).
 RubyLLM.configure do |c|
   # Silas never uses RubyLLM's acts_as_* ActiveRecord mixins (it owns its own
   # durable schema), so opt into the new API to silence the legacy deprecation

data/lib/silas/channel.rb

@@ -4,36 +4,110 @@ module Silas
   #
   # Inbound is pure trigger reuse: dispatch maps an external thread to a Session
   # via silas_sessions.channel + continuation_token, then calls the UNCHANGED
-  # public API (new thread -> Silas.agent.start; reply -> session.continue).
+  # public API (new thread -> the routed agent's .start; reply -> continue).
   # Outbound (deliver the agent's answer / an approval request) is a subclass
   # responsibility, invoked off the loop by ChannelDeliveryJob — so the loop's
   # determinism and the ledger's exactly-once are never touched.
   class Channel
     TOKEN_PURPOSE = "silas/channel".freeze
+    # silas_sessions.agent_name for the root app/agent — the column's default,
+    # and the name the loop reads as "no named scope".
+    ROOT_AGENT = "agent".freeze
 
     def self.channel_name = name.demodulize.underscore
 
-    # Stable external-thread key, namespaced by channel so two channels can't collide.
-    def self.namespaced(thread_key) = "#{channel_name}:#{thread_key}"
+    # Stable external-thread key, namespaced by channel AND agent: two channels
+    # can't collide, and two staff members sharing one transport can't either.
+    def self.namespaced(thread_key, agent_name = nil)
+      "#{channel_name}:#{agent_name.presence || ROOT_AGENT}:#{thread_key}"
+    end
+
+    # Tokens minted before routing existed have no agent segment. Every one of
+    # them belongs to the root agent — dispatch could start nothing else — so a
+    # miss on the new form falls back to this one and a live thread upgrades
+    # without losing its session.
+    def self.legacy_namespaced(thread_key) = "#{channel_name}:#{thread_key}"
 
-    # The single inbound entry point for every transport.
-    def self.dispatch(thread_key:, input:, metadata: {})
-      token = namespaced(thread_key)
-      if (session = Silas::Session.find_by(continuation_token: token))
+    def self.find_session(thread_key, agent_name)
+      Silas::Session.find_by(continuation_token: namespaced(thread_key, agent_name)) ||
+        Silas::Session.find_by(continuation_token: legacy_namespaced(thread_key))
+    end
+
+    # The single inbound entry point for every transport. `agent` is the NAME of
+    # the staff member this thread belongs to (nil or "agent" = the root agent);
+    # callers read it off configuration with .route_for.
+    def self.dispatch(thread_key:, input:, metadata: {}, agent: nil)
+      name = resolve_agent(agent)
+      if (session = find_session(thread_key, name))
         session.continue(input: input)
         session
       else
-        Silas.agent.start(input: input, metadata: metadata,
-                          channel: channel_name, continuation_token: token)
+        owner = name ? Silas.agent(name) : Silas.agent
+        owner.start(input: input, metadata: metadata,
+                    channel: channel_name, continuation_token: namespaced(thread_key, name))
       end
     rescue ActiveRecord::RecordNotUnique
       # Concurrent first-inbound race: the other request created the session;
-      # treat this message as a continue.
-      session = Silas::Session.find_by!(continuation_token: namespaced(thread_key))
+      # treat this message as a continue. Nothing to continue means the conflict
+      # was something else, so let it out.
+      session = find_session(thread_key, name) or raise
       session.continue(input: input)
       session
     end
 
+    # ---- routing: which agent an inbound thread wakes -----------------------
+
+    # config.channel_routes, normalised to { transport => { key => agent_name } }.
+    # Keys are matched downcased because email recipients are case-insensitive;
+    # Slack channel ids are unaffected by folding both sides the same way.
+    def self.routes
+      (Silas.config.channel_routes || {}).to_h do |transport, table|
+        [ transport.to_s, table.to_h { |key, agent| [ key.to_s.downcase, agent.to_s ] } ]
+      end
+    end
+
+    # The agent name a thread on `transport` belongs to, or nil for the root
+    # agent. Candidate keys are tried in order and the first match wins, so a
+    # caller holding several (an email's recipients) passes them all.
+    def self.route_for(transport, *keys)
+      table = routes[transport.to_s] or return nil
+
+      keys.flatten.filter_map { |key| table[key.to_s.downcase] }.first
+    end
+
+    # Checked at boot by Registry.install! against the app/agents/ roster. A
+    # route naming an agent that doesn't exist is a deploy failure, not a
+    # runtime one: Silas.agent raises on an unknown name, and discovering that
+    # at dispatch time would strand every future message on the thread.
+    def self.validate_routes!(staff)
+      staff = staff.map(&:to_s)
+      routes.each do |transport, table|
+        table.each do |key, agent|
+          next if agent == ROOT_AGENT || staff.include?(agent)
+
+          raise Error, "config.channel_routes[#{transport.inspect}][#{key.inspect}] routes to " \
+                       "agent #{agent.inspect}, which does not exist" \
+                       "#{staff.any? ? " (known: #{staff.sort.join(', ')})" : " — no app/agents/ directories found"}"
+        end
+      end
+    end
+
+    # nil means the root agent. An unknown name resolves to nil instead of
+    # raising: dispatch runs inside a webhook handler, and a 500 there is a
+    # message Slack retries into its own retry guard and then loses. Boot
+    # already refused a bad route, so this only fires when routes were assigned
+    # after boot — the thread lands on the root agent, exactly where it landed
+    # before routing existed, and the log says so.
+    def self.resolve_agent(name)
+      name = name.to_s
+      return nil if name.empty? || name == ROOT_AGENT
+      return name if Silas.named_agent?(name)
+
+      Rails.logger&.error("[Silas] channel route names unknown agent #{name.inspect}; " \
+                          "starting the root agent instead. Fix config.channel_routes.")
+      nil
+    end
+
     # Resolve the channel instance that owns a session (for outbound delivery).
     def self.for_session(session)
       return nil if session.channel.blank?