silas 0.6.2 → 0.6.3

data/app/views/layouts/silas/inbox.html.erb

@@ -73,6 +73,17 @@
       padding: 14px 16px; margin-bottom: 12px; }
     .session-row { display: block; text-decoration: none; color: inherit; }
     .session-row:hover { border-color: var(--accent); }
+    /* Lineage. A handoff or a delegation makes a SECOND session: unmarked, the
+       child is a row on the index nobody can account for and the parent's feed
+       shows no sign it ever handed anything over. Neutral tokens throughout —
+       lineage is not a run state, and the lamp is reserved for what you can
+       act on. */
+    .lineage { display: flex; flex-wrap: wrap; align-items: center; gap: 6px;
+      margin: 6px 0 0; color: var(--muted); font-size: 13px; }
+    .lineage-mark { font-family: var(--mono); color: var(--quiet); }
+    .lineage-agent { color: var(--ink); font-weight: 600; }
+    .lineage-child { padding-left: 10px; border-left: 2px solid var(--line); margin-top: 8px; }
+    .session-child { border-left: 3px solid var(--line); }
     .row-top { display: flex; align-items: center; gap: 8px; margin-bottom: 4px; }
     .row-top .name { font-weight: 600; }
     .muted { color: var(--muted); font-size: 13px; }
@@ -98,15 +109,70 @@
       border-radius: 50%; background: var(--accent); }
     .step-text { margin: 2px 0; }
     .step-live { white-space: pre-wrap; }
-    .tool { background: var(--grey-bg); border-radius: var(--radius); padding: 8px 10px; margin: 6px 0; font-size: 13px; }
+    .tool { margin: 6px 0; font-size: 13px; }
     .tool code { font-family: var(--mono); }
     .tool-args { margin: 6px 0; font-size: 13px; }
     .tool-args .kv { display: flex; gap: 8px; padding: 2px 0; border-bottom: 1px dotted var(--line); }
     .tool-args .kv:last-child { border-bottom: 0; }
     .tool-args .k { font-family: var(--mono); font-size: 12px; color: var(--muted); min-width: 96px; }
     .tool-args .v { font-family: var(--mono); font-size: 12px; overflow-wrap: anywhere; }
-    details.tool-result { margin: 6px 0; }
-    details.tool-result summary { cursor: pointer; font-size: 12px; color: var(--muted); }
+    /* The feed. One invocation, one sentence — and SALIENCE is the point:
+       effect mode sets the weight (a read that worked is furniture; a tool
+       that moved money or sent a message is not), run state colours the rule
+       (see the aspect tokens above). A failure is loud whatever it touched. */
+    .deed-line { margin: 0; display: flex; flex-wrap: wrap; align-items: baseline; gap: 5px; }
+    .deed-tool { font-family: var(--mono); font-weight: 600; }
+    .deed-arg { font-family: var(--mono); font-size: 12px; color: var(--muted); overflow-wrap: anywhere; }
+    .deed-sep { color: var(--line); }
+    .deed-arrow { color: var(--muted); }
+    .deed-outcome { font-weight: 600; }
+    .deed-quiet { padding-left: 10px; border-left: 2px solid var(--line); opacity: 0.7; }
+    .deed-quiet .deed-tool { font-weight: 400; }
+    .deed-loud, .deed-exact { background: var(--grey-bg); border-radius: var(--radius);
+      padding: 8px 10px; border-left: 3px solid var(--line); }
+    /* transactional: the effect and its ledger row commit together. The one
+       mode that earns the heaviest rule on the page. */
+    .deed-exact { border-left-width: 5px; }
+    /* state last — it wins the rule colour from the weight classes above */
+    .deed-amber  { border-left-color: var(--amber); }
+    .deed-blue   { border-left-color: var(--blue); }
+    .deed-green  { border-left-color: var(--green); }
+    .deed-red    { border-left-color: var(--red); }
+    .deed-violet { border-left-color: var(--violet); }
+    .deed-amber  .deed-outcome { color: var(--amber); }
+    .deed-blue   .deed-outcome { color: var(--blue); }
+    .deed-green  .deed-outcome { color: var(--green); }
+    .deed-red    .deed-outcome { color: var(--red); }
+    .deed-violet .deed-outcome { color: var(--violet); }
+    .deed-quiet .deed-outcome { color: var(--muted); font-weight: 400; }
+    .deed-detail { margin: 6px 0 0; }
+    .deed-detail summary { cursor: pointer; font-size: 12px; color: var(--muted); }
+    /* [hidden] is a UA rule at the bottom of the cascade, so ANY author
+       `display` on these elements beats it and BOTH readings render at once.
+       The raw blocks carry `hidden` so a host rendering these partials without
+       our stylesheet still sees one reading — the attribute has to keep winning
+       here too. Scoped rather than !important, so the :checked rules below
+       (higher specificity) can still reveal the trace. */
+    #silas-turns [hidden] { display: none; }
+    .deed-head { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; }
+    .raw-state { font-family: var(--mono); font-size: 11px; color: var(--muted); margin: 4px 0 6px; }
+    .turn-meta { margin: -4px 0 8px; }
+    .step-silent { margin: 2px 0; }
+    /* The raw switch. CSS, not a param: every row below can be replaced by a
+       broadcast at any moment and a broadcast render has no reader to ask —
+       both readings ship in the DOM and :checked picks. */
+    .raw-switch { position: absolute; width: 1px; height: 1px; opacity: 0; }
+    .feed-bar { display: flex; justify-content: flex-end; margin: 12px 0 4px; }
+    .feed-bar .chip { font-size: 12px; padding: 3px 10px; border: 1px solid var(--line);
+      border-radius: 999px; color: var(--muted); cursor: pointer; user-select: none; }
+    .raw-switch:checked ~ .feed-bar .chip { background: var(--ink); color: var(--bg); border-color: var(--ink); }
+    .raw-switch:focus-visible ~ .feed-bar .chip { outline: 2px solid var(--accent); outline-offset: 2px; }
+    .raw-switch:checked ~ #silas-turns .feed-only { display: none; }
+    .raw-switch:checked ~ #silas-turns .raw-only { display: block; }
+    /* raw is FLAT — the graded weights are the feed's reading, not the trace's */
+    .raw-switch:checked ~ #silas-turns .tool { background: var(--grey-bg); border-left: 0;
+      border-radius: var(--radius); padding: 8px 10px; opacity: 1; }
+    #silas-turns:has(.turn) + .feed-empty { display: none; }
     pre { font-family: var(--mono); font-size: 12px; background: var(--grey-bg); border-radius: var(--radius);
       padding: 8px 10px; overflow-x: auto; margin: 6px 0; }
     .approval { border: 1.5px solid var(--amber); background: var(--amber-bg); border-radius: var(--radius);

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

@@ -0,0 +1,21 @@
+<%# The call itself, shared by the feed's disclosure and the raw trace.
+
+    Arguments and results are MODEL-authored. Every value below goes through
+    ERB's escape and nothing here is ever marked html_safe. %>
+<div class="raw-state">status <%= invocation.status %> · approval <%= invocation.approval_state || "none" %> · effect <%= invocation.effect_mode %></div>
+<%# What the agent passed — the question an audit surface must answer.
+    Key/value rows (05): scannable at a glance, JSON only per value. %>
+<% if invocation.arguments.present? %>
+  <div class="tool-args">
+    <% invocation.arguments.each do |key, value| %>
+      <div class="kv"><span class="k"><%= key %></span><span class="v"><%= value.is_a?(String) ? value : JSON.generate(value) %></span></div>
+    <% end %>
+  </div>
+<% else %>
+  <div class="muted">called with no arguments</div>
+<% end %>
+<% if invocation.error.present? %>
+  <pre class="error"><%= invocation.error %></pre>
+<% elsif invocation.result.present? %>
+  <pre><%= pretty_args(invocation.result) %></pre>
+<% end %>

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

@@ -1,14 +1,32 @@
-<div class="tool" id="<%= dom_id(invocation) %>">
-  <div>
+<%# One invocation, one sentence — what ran, on what, how it ended — with the
+    call itself behind a disclosure.
+
+    The technical row is rendered TOO, hidden, and the page's raw switch picks
+    between them in CSS. It has to work that way: this partial is
+    broadcast-replaced on every transition, and a broadcast render has no
+    params and no reader to ask. CSS survives every replace; a choice baked
+    into the render would snap back on the first one.
+
+    `hidden` on the raw blocks, not just a class: a host that renders these
+    partials outside the inbox layout (examples/playground does) has none of
+    our stylesheet, and must see the sentence alone rather than both. %>
+<div class="tool deed <%= invocation_weight(invocation) %> <%= invocation_state_class(invocation) %>" id="<%= dom_id(invocation) %>">
+  <p class="deed-line feed-only">
+    <code class="deed-tool"><%= invocation.tool_name %></code>
+    <% invocation_arg_phrases(invocation).each do |phrase| %>
+      <span class="deed-sep">·</span><span class="deed-arg"><%= phrase %></span>
+    <% end %>
+    <span class="deed-arrow">→</span>
+    <span class="deed-outcome"><%= invocation_outcome(invocation) %></span>
+  </p>
+  <div class="deed-head raw-only" hidden>
     <code><%= invocation.tool_name %></code>
     <%= status_pill(invocation.awaiting_approval? ? "required" : invocation.status) %>
     <%# The audit line — who held the lever, and why it moved. %>
-    <% if invocation.approval_state == "approved" %>
-      <span class="muted"><%= invocation.approved_by.present? ? "approved by #{invocation.approved_by}" : "auto-approved by policy" %></span>
-    <% elsif invocation.approval_state == "answered" %>
-      <span class="muted">answered<%= " by #{invocation.approved_by}" if invocation.approved_by.present? %></span>
+    <% if (verdict = verdict_phrase(invocation)) %>
+      <span class="muted"><%= verdict %></span>
     <% elsif invocation.approval_state == "declined" %>
-      <span class="muted">declined<%= " by #{invocation.approved_by}" if invocation.approved_by.present? %><%= " — “#{invocation.decline_reason}”" if invocation.decline_reason.present? %></span>
+      <span class="muted"><%= declined_phrase(invocation) %></span>
     <% elsif invocation.approval_state == "expired" %>
       <span class="muted"><%= invocation.question? ? "question expired unanswered" : "approval expired unanswered" %></span>
     <% end %>
@@ -18,22 +36,19 @@
         its place in the movement with a one-line stub. %>
     <div class="held-stub">↑ held at the signal — <%= invocation.question? ? "answer" : "clear" %> it above</div>
   <% else %>
-    <%# What the agent passed — the question an audit surface must answer.
-        Key/value rows (05): scannable at a glance, JSON only per value. %>
-    <% if invocation.arguments.present? %>
-      <div class="tool-args">
-        <% invocation.arguments.each do |key, value| %>
-          <div class="kv"><span class="k"><%= key %></span><span class="v"><%= value.is_a?(String) ? value : JSON.generate(value) %></span></div>
-        <% end %>
-      </div>
-    <% end %>
-    <% if invocation.error.present? %>
-      <pre class="error"><%= invocation.error %></pre>
-    <% elsif invocation.result.present? %>
-      <details class="tool-result">
-        <summary>result</summary>
-        <pre><%= pretty_args(invocation.result) %></pre>
-      </details>
-    <% end %>
+    <details class="deed-detail feed-only">
+      <summary>arguments and result</summary>
+      <%= render "silas/inbox/invocations/detail", invocation: invocation %>
+    </details>
+    <div class="raw-only" hidden>
+      <%= render "silas/inbox/invocations/detail", invocation: invocation %>
+    </div>
+  <% end %>
+  <%# A handoff or a delegation is the one call whose outcome is another
+      session. It belongs here, at the call that made it — that is the only
+      place in the product where "A handed to B" is a fact you can read.
+      Outside the raw/feed split: lineage is not a reading, it happened. %>
+  <% if (child = invocation_child_session(invocation)) %>
+    <%= render "silas/inbox/sessions/child", child: child %>
   <% end %>
 </div>

data/app/views/silas/inbox/sessions/_child.html.erb

@@ -0,0 +1,14 @@
+<%# One session this one started, as a row on the parent's page.
+
+    silas_engine_path, not the bare helper: this partial is reached from
+    _invocation, which is broadcast-rendered on every tool transition, and
+    bare engine helpers 500 in that renderer. %>
+<div class="lineage lineage-child">
+  <span class="lineage-mark">↳</span>
+  <%= lineage_to_phrase(child) %>
+  <span class="lineage-agent"><%= child.agent_name %></span>
+  <%= link_to "session ##{child.id}", silas_engine_path(:inbox_session_path, child) %>
+  <%# The child's state as it stood when this page rendered — the parent's
+      stream carries no broadcast from the child's session. %>
+  <% if (turn = session_state_turn(child)) %><%= status_pill(turn.status) %><% end %>
+</div>

data/app/views/silas/inbox/sessions/_row.html.erb

@@ -1,8 +1,9 @@
-<%= link_to inbox_session_path(session), class: "card session-row" do %>
+<%= link_to inbox_session_path(session),
+      class: [ "card", "session-row", ("session-child" if session.parent_session) ] do %>
   <div class="row-top">
     <span class="name"><%= session.agent_name %></span>
     <%# Loaded association — no per-row queries. %>
-    <% if (turn = session.turns.detect(&:active?) || session.turns.last) %><%= status_pill(turn.status) %><% end %>
+    <% if (turn = session_state_turn(session)) %><%= status_pill(turn.status) %><% end %>
     <% pending = pending_counts.fetch(session.id, 0) %>
     <% if pending.positive? %><span class="badge"><%= pending %> held</span><% end %>
   </div>
@@ -11,4 +12,14 @@
     <%= session.channel.presence || "direct" %> ·
     <%= silas_relative_time(session.updated_at) %>
   </div>
+  <%# A child session is nobody's stray: its first turn is another agent's
+      brief. Named here, or the index shows a row no one can account for.
+      Text, not a link — the whole card already is one. %>
+  <% if (parent = session.parent_session) %>
+    <div class="lineage">
+      <span class="lineage-mark">↖</span>
+      <%= lineage_from_phrase(session) %>
+      <span class="lineage-agent"><%= parent.agent_name %></span>
+    </div>
+  <% end %>
 <% end %>

data/app/views/silas/inbox/sessions/show.html.erb

@@ -12,6 +12,16 @@
     <span class="muted">#<%= @session.id %></span>
   </div>
   <div class="muted"><%= @session.channel.presence || "direct" %> · started <%= silas_relative_time(@session.created_at) %></div>
+  <%# Lineage up. This session's first turn is another agent's brief; without
+      the line it reads as a session that started itself. %>
+  <% if (parent = @session.parent_session) %>
+    <div class="lineage">
+      <span class="lineage-mark">↖</span>
+      <%= lineage_from_phrase(@session) %>
+      <span class="lineage-agent"><%= parent.agent_name %></span>
+      <%= link_to "session ##{parent.id}", inbox_session_path(parent) %>
+    </div>
+  <% end %>
   <%= render "silas/inbox/sessions/cost", session: @session %>
 </div>
 
@@ -24,9 +34,32 @@
              collection: @session.pending_approvals.order(:id), as: :invocation %>
 </div>
 
+<%# The switch is a bare checkbox and #silas-turns is its SIBLING, because the
+    swap has to be pure CSS: every row in the feed can be replaced by a
+    broadcast at any moment, and a broadcast render has no params to consult.
+    Both readings are in the DOM; :checked decides which one is on. %>
+<input type="checkbox" id="silas-raw" class="raw-switch">
+<div class="feed-bar">
+  <label class="chip" for="silas-raw">raw trace</label>
+</div>
+
 <div id="silas-turns">
   <%= render partial: "silas/inbox/turns/turn", collection: @turns, as: :turn %>
 </div>
+<%# :has, not a Ruby conditional — a turn appended live has to retire this
+    line, and the append never re-renders the page. %>
+<div class="empty feed-empty">Nothing has happened here yet.</div>
+
+<%# Lineage down, for the children the feed cannot place: an at_most_once
+    handoff that crashed after starting the colleague leaves the session
+    created and the result unrecorded, so no row in the trace names it. %>
+<% stranded = stranded_child_sessions(@session, @turns) %>
+<% if stranded.any? %>
+  <div class="card">
+    <div class="muted">Started from this session, at a point the trace never recorded:</div>
+    <%= render partial: "silas/inbox/sessions/child", collection: stranded, as: :child %>
+  </div>
+<% end %>
 
 <div class="card composer">
   <%= form_with url: inbox_session_turns_path(@session) do |f| %>

data/app/views/silas/inbox/steps/_step.html.erb

@@ -1,8 +1,9 @@
 <div class="step" id="<%= dom_id(step) %>">
+  <% text = step_text(step) %>
   <%# The text container is unconditional: silas-step-<id>-text is the live
       delta target. While the step runs, deltas replace its innerHTML; the
       completed row render (this partial, re-broadcast) supersedes them. %>
-  <% if (text = step_text(step)) %>
+  <% if text %>
     <div class="step-text" id="silas-step-<%= step.id %>-text"><%= simple_format(text) %></div>
   <% else %>
     <div class="step-text step-live" id="silas-step-<%= step.id %>-text"></div>
@@ -13,4 +14,10 @@
   <div id="silas-step-<%= step.id %>-tools">
     <%= render partial: "silas/inbox/invocations/invocation", collection: step.tool_invocations, as: :invocation %>
   </div>
+  <%# A completed step with neither text nor a tool call is a model turn that
+      produced nothing. Rare, and worth naming — an unexplained gap in a feed
+      reads as a rendering bug. %>
+  <% if step.completed? && text.blank? && step.tool_invocations.empty? %>
+    <div class="step-silent muted">the model returned nothing on this step</div>
+  <% end %>
 </div>

data/app/views/silas/inbox/turns/_header.html.erb

@@ -17,6 +17,13 @@
       <span class="muted">cancel requested…</span>
     <% end %>
   </div>
+  <%# A settled turn's audit line. A turn that used no tools says exactly
+      that: nothing ran, nothing was written — the absence is the answer an
+      operator came here for, and it has to be stated, not inferred from an
+      empty space. %>
+  <div class="turn-meta muted">
+    asked <%= silas_relative_time(turn.created_at) %> · <%= turn_progress(turn) %><%= " · #{turn_effects_summary(turn)}" unless turn.active? %>
+  </div>
   <% if turn.budget_parked? %>
     <div class="approval">
       <h3>Budget reached — <%= turn.failure_reason %></h3>
@@ -28,7 +35,5 @@
         <button class="btn approve">Raise &amp; resume</button>
       <% end %>
     </div>
-  <% elsif turn.failure_reason.present? %>
-    <div class="muted">failed: <%= turn.failure_reason %></div>
   <% end %>
 </div>

data/docs/agents.md

@@ -46,6 +46,12 @@ resumes — runs under that agent's own tools, skills, instructions, and
 definitions digest. Scope switching is execution-isolated, so concurrent jobs
 running different agents never cross wires.
 
+A named agent is staff, not a lesser agent: it gets `ask_question` (subject to
+`config.ask_question`), `load_skill` when it has skills, `run_code` when the
+sandbox is on, `remember`/`recall`, `handoff`, and the remote tools from
+`app/agent/connections/` — one set of credentials for the whole app. It does
+not get `delegate`; subagents belong to the root agent's turn.
+
 ```ruby
 Silas.agent("escalations").start(input: "…")
 ```
@@ -56,6 +62,10 @@ bin/rails silas:chat AGENT=escalations   # talk to one staff member
 
 The inbox filters by agent; the root `app/agent/` stays the default.
 
+Staff answer their own mail: `config.channel_routes` sends a Slack channel or an
+email address to a named agent, and every turn on that thread runs under their
+scope. See [channels](channels.md#routing-which-agent-wakes).
+
 ## Subagents — delegation within a turn
 
 The built-in `delegate` tool runs a scoped sub-task under a subagent's own
@@ -67,9 +77,11 @@ to keep a specialist's tools out of the main agent's prompt until needed.
 Staff compose through **handoffs, not conversations**: the built-in `handoff`
 tool files a self-contained brief that starts a **linked session** for another
 named agent — asynchronously by default, or `await: true` for an answer.
-Handoffs are exactly-once-guarded and cycle-checked. Two models chatting
-freely is a cost and audit hazard, so it's deliberately unblessed; a handoff
-is a work order, with the paper trail that implies.
+Handoffs are cycle-checked, and at-most-once: filing one is a single external
+effect, so a crash mid-handoff parks the call **in doubt** for a person rather
+than starting the colleague twice. Two models chatting freely is a cost and
+audit hazard, so it's deliberately unblessed; a handoff is a work order, with
+the paper trail that implies.
 
 ## Schedules give any agent a clock
 

data/docs/channels.md

@@ -58,7 +58,7 @@ end
 ```
 
 `dispatch` is the whole inbound API. It maps the external thread to a session and
-then calls the ordinary public API — `Silas.agent.start` for a new thread,
+then calls the ordinary public API — `<agent>.start` for a new thread,
 `session.continue` for a reply. There is no channel-specific loop.
 
 Three things to get right:
@@ -66,7 +66,8 @@ Three things to get right:
 **The thread key must be stable.** The same conversation must produce the same
 key every time, or every message starts a new session and the agent has no
 memory. Use the vendor's conversation or thread id, never a per-message id. Keys
-are namespaced by channel (`whatsapp:abc123`), so two channels can't collide.
+are namespaced by channel *and* agent (`whatsapp:bookkeeper:abc123`), so neither
+two channels nor two staff members sharing a transport can collide.
 
 **Sign over the raw body.** `request.raw_post`, never re-serialized params —
 re-serializing changes the bytes and the HMAC no longer matches. See
@@ -80,6 +81,56 @@ message matters for your transport, buffer it or tell the user.
 Metadata is stored on the session and shown in the inbox, so keep it small and
 free of secrets. It exists so outbound knows where to reply.
 
+### Routing: which agent wakes
+
+By default an inbound thread wakes the root agent. `config.channel_routes` sends
+it to a [named agent](agents.md#named-agents--the-staff-pattern) instead — data
+only, one entry per destination:
+
+```ruby
+# config/initializers/silas.rb
+config.channel_routes = {
+  "slack" => { "C0BILLING" => "bookkeeper" },   # Slack channel id
+  "email" => { "billing@shop.test" => "bookkeeper" }
+}
+```
+
+The outer key is the transport's filename identity (`slack`, `email`, and for a
+generated channel, whatever you named the file). The inner key is whatever that
+transport calls a destination. Both shipped channels read it for you: Slack
+matches the channel the message arrived in, email matches every recipient
+address — To, Cc, and the forwarding headers Action Mailbox itself routes on —
+first match wins, case-insensitively. Anything unmatched wakes the root agent.
+
+The session is stamped with the agent's name, so **every** turn on that thread —
+including crash resumes weeks later — runs under that agent's tools, skills,
+instructions, and definitions digest.
+
+A custom channel opts in with one argument:
+
+```ruby
+Agent::Channels::Whatsapp.dispatch(
+  thread_key: message[:from],
+  input: message.dig(:text, :body).to_s,
+  agent: Silas::Channel.route_for("whatsapp", message[:to]),
+  metadata: { "whatsapp" => { "to" => message[:from] } }
+)
+```
+
+**A route naming an agent that doesn't exist fails the boot that installs it**,
+listing the staff that do exist. That is deliberate: `Silas.agent(name)` raises
+on an unknown name, and finding that out at dispatch time would 500 the webhook
+— which for Slack means a retry, which the retry guard drops, which means the
+message is gone. If a bad name is assigned *after* boot, dispatch does not
+raise: it logs the error and wakes the root agent, which is where that thread
+went before routing existed.
+
+Routing changes how continuation tokens are derived — `whatsapp:abc123` became
+`whatsapp:agent:abc123`. Sessions that predate the change keep working: a lookup
+that misses the new form falls back to the old one, so a live thread carries on
+in the session it already has (with the agent it already had — a conversation
+does not change hands mid-thread). New threads route normally.
+
 ### Verification
 
 `Silas::Webhook.verify_hmac` handles the parts that are identical everywhere —

data/docs/configuration.md

@@ -69,6 +69,7 @@ recipes in [providers](providers.md).
 | Option | Default | Meaning |
 |---|---|---|
 | `slack_signing_secret` / `slack_bot_token` | `credentials.silas.slack.*` | Explicit setters override the credentials path; `nil` disables Slack. |
+| `channel_routes` | `{}` | Which agent an inbound thread wakes: `{ "slack" => { "C0BILLING" => "bookkeeper" }, "email" => { "billing@shop.test" => "bookkeeper" } }`. Unmatched threads wake the root agent. Names are checked at boot against `app/agents/` — a typo fails the deploy, never a webhook. See [channels](channels.md#routing-which-agent-wakes). |
 
 ## Evals
 
@@ -88,7 +89,7 @@ recipes in [providers](providers.md).
 
 | Option | Default | Meaning |
 |---|---|---|
-| `mcp_server_host` | `"127.0.0.1"` | Bind host for the in-process MCP server (serving *your* tools to MCP clients). |
+| `mcp_server_host` | `"127.0.0.1"` | Bind host for the in-process MCP server (`Silas::Mcp::Server`, serving *your* tools to MCP clients). Inert — nothing starts that server yet; see [connections](connections.md). |
 | `mcp_client_factory` | `nil` | `->(connection) { client }` — inject a fake MCP client per connection in tests. |
 
 The remaining accessors (`tool_resolver`, `tool_definitions`,

data/docs/connections.md

@@ -51,8 +51,11 @@ connection at a changed server.
 `config.mcp_client_factory = ->(connection) { fake_client }` injects a fake
 client per connection — the seam the gem's own specs use.
 
-## The other direction
-
-Silas can also *serve* your agent's tools as an MCP server (`Silas::Mcp::Server`,
-bound to `config.mcp_server_host`) — the "mount your tools as MCP" seam, so
-other MCP clients can call the tools you wrote for your agent.
+## The other direction — not wired up yet
+
+`Silas::Mcp::Server` is an in-process HTTP server that hosts your agent's tools
+for outside MCP clients, and `config.mcp_server_host` is its bind host. **You
+cannot turn it on.** Nothing in the gem starts it — the class is exercised by
+its own specs and nothing else — so serving your tools as MCP is not a feature
+you can use today. The code stays because a mounted endpoint is the planned
+shape; until that ships, treat this direction as absent.

data/docs/guarantees.md

@@ -1,11 +1,22 @@
 # Guarantees
 
 Durability in Silas is a contract, not a slide. Everything on this page is
-verified by the in-repo chaos harness (`chaos_host/bin/chaos`), which
-`kill -9`s live agents hundreds of times per release — the current gate is
-100/100 completions per mode across a 295-run matrix, zero duplicate effects,
-byte-identical replay, on SQLite and Postgres. Results live in
-`chaos_host/results/` and every run is reproducible.
+verified by the in-repo chaos harness (`chaos_host/bin/chaos`), which `kill -9`s
+live agents mid-turn. The maintainer runs the full matrix before a release —
+`chaos_host/bin/full_gate`, 275 runs across five kill modes on SQLite and
+Postgres — and commits the output. Last gate: every run completed, zero
+duplicate effects, byte-identical replay. CI runs the spec suite and RuboCop,
+not chaos; the harness is a local gate, and every run is reproducible.
+
+`chaos_host/results/*.jsonl` is an append-only, unedited history, so it carries
+batches from before harness fixes alongside the gate batch. The first two rows
+of `sqlite_compact.jsonl` are one of those: their duplicate counts are the
+harness's turn-scoped side-effect keys colliding across a multi-turn session,
+not effects that happened twice (`chaos_host/RESULTS.md` records the fix). It
+also carries the smaller batches run against individual changes — a batch
+starts wherever `run` restarts at 1, and no field on a row says which batch was
+a gate. `chaos_host/RESULTS.md` is that record; its per-mode run counts are the
+gate's.
 
 ## Turns survive hard process death
 

data/docs/headless.md

@@ -0,0 +1,120 @@
+# Headless Silas
+
+The inbox is a *mountable* engine, not a requirement. Don't mount it and you
+have the whole durable runtime — loop, ledger, approvals, memory, evals — with
+no screens of ours in your app. You build the operator surface; Silas keeps
+the guarantees.
+
+This is the shape to reach for when the person approving things is **your
+user, not your ops team**: a product where "review what the agent wants to
+do" is a first-class feature of your own UI, styled and worded like the rest
+of it.
+
+## The whole approval lifecycle is on the model
+
+The inbox controllers are thin. Everything they do, you can do:
+
+```ruby
+invocation = Silas::ToolInvocation.find(id)
+
+invocation.approve!(by: current_user.email)   # resumes the parked turn
+invocation.decline!(reason: "wrong customer", by: current_user.email)
+invocation.answer!(text: "yes, refund the delivery charge", by: current_user.email)
+```
+
+`answer!` is the reply to an `ask_question` park — information, not
+permission. Each of these settles the invocation, records the actor, and
+resumes the turn. The mounted inbox, the JSON API, the Slack controller and
+the email approve/decline links are simply four callers of the same three
+methods; yours is a fifth.
+
+For the queue itself:
+
+```ruby
+session.pending_approvals          # what this session is parked on
+Silas::ToolInvocation.where(approval_state: "required")   # the whole queue
+Silas::Turn.where(status: "waiting")                      # parked turns
+```
+
+Note the two status vocabularies: a **Turn** is
+`queued/running/waiting/in_doubt/completed/failed/canceled`, while a
+**Session** is only `active/archived`. Parked work is a turn in `waiting`.
+
+Nothing about parking is UI-coupled: a turn parked for approval holds at zero
+compute until one of those methods is called, whatever calls it.
+
+## What you take on
+
+Four things the engine was doing for you:
+
+- **Rendering.** Arguments, results, the transcript, cost lines. The
+  invocation carries `tool_name`, `arguments`, `result`, `approval_state` and
+  its turn/session associations — you decide what an operator sees. Note that
+  a tool's arguments are model-authored text: render them **escaped**, the
+  way the engine's views do.
+- **Authorization.** `config.inbox_auth` and `api_auth` guard *engine*
+  routes. Your controllers are yours — apply your own policy, and remember
+  that approving is a privileged action even when reading isn't.
+- **Live updates.** The engine's Turbo broadcasts target its own DOM ids. If
+  you want live traces, broadcast from your own views; the `Broadcastable`
+  concern's targets are engine-internal and not a public contract.
+- **Approval links in channels.** `Silas::Channel.approval_url` mints signed,
+  expiring one-click links against **engine routes**
+  (`Silas::Engine.routes.url_helpers`), so email and Slack approve/decline
+  depend on the engine being mounted. Going fully headless with channel
+  approvals means minting your own signed links to your own routes;
+  `Channel.token_for` / `Channel.verify_token` are the signing seam, so you
+  keep the token semantics (expiry via `approval_ttl`, no session state in
+  the URL) without the routes.
+
+## Mount it anyway, for the engine room
+
+Headless and mounted are not exclusive, and the most useful arrangement is
+usually both:
+
+- **Your UI is the front office** — the approval moment your user actually
+  touches, in your product's voice.
+- **The mounted inbox is the engine room** — the full technical history,
+  every step, every tool call, every cost, for when someone needs to know
+  exactly what happened. Mount it behind staff-only auth
+  (`config.inbox_auth`) and link into it from your admin.
+
+You get a bespoke operator experience without rebuilding the audit trail, and
+support questions have somewhere to be answered.
+
+## Per-execution scopes, if capabilities vary
+
+If different users, teams or tenants need *different* tools, skills or
+instructions, note that Silas resolves those through the active scope, not
+process-global config:
+
+```ruby
+Silas.with_agent_scope(scope) { ... }   # per-thread AND per-fiber
+```
+
+An `AgentScope` carries `name`, `dir`, `agent`, `resolver`, `definitions`,
+`digest` and `skills` — every model-visible capability. It exists for named
+agents and subagents, and `Silas.scope_for_session` resolves a session's
+scope from its `agent_name` on every turn, so scoped capabilities survive
+parking and resumption.
+
+Constraints worth knowing before you build on this:
+
+- **Credentials are paths, not values.** Connections resolve
+  `credential: crm.token` against `Rails.application.credentials` at call
+  time — designed for *your* app's credentials, not per-end-user OAuth
+  tokens. Per-user credentials need a tool of your own that reads them;
+  `Tool#session` is the context the Ledger injects, so the session is where
+  you hang "whose account is this".
+- **Changing capabilities fails parked turns, by design.** The definitions
+  digest is a nondeterminism guard: a turn parked before its tools changed is
+  *failed* on resume rather than resumed against a different agent. The
+  digest is per-scope, so scoped agents don't invalidate each other — but
+  within a scope, settle parked work before rolling a capability change out.
+- **Memory is not in the digest.** It covers tool schemas, skill names and
+  descriptions, and `final_answer` — so teaching an agent new *facts* is safe
+  for parked turns, while changing its *tools* is not. If you build an
+  end-user-facing way to steer an agent, prefer memory for the frequent path.
+- **Named-agent scopes don't include connection tools.** A scope's resolver
+  is built from its own directory's tools plus builtins; remote MCP tools are
+  wired into the root agent only.