silas 0.4.0 → 0.6.0

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

@@ -4,37 +4,71 @@
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title><%= content_for?(:title) ? yield(:title) : "Silas Inbox" %></title>
+  <%# The night tile, inlined — the engine ships no assets and keeps shipping none. %>
+  <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='32' height='32' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' rx='7' fill='%230F1013'/%3E%3Cg transform='translate(4,4)'%3E%3Ccircle cx='12' cy='12' r='9.6' fill='none' stroke='%23E9EBEF' stroke-width='2.2'/%3E%3Ccircle cx='8.4' cy='15.6' r='2.5' fill='%23F2F4F8'/%3E%3Ccircle cx='15.6' cy='8.4' r='2.5' fill='%23F2F4F8'/%3E%3C/g%3E%3C/svg%3E">
   <% if Silas::Inbox.streaming_available? %><%= turbo_include_tags rescue nil %><% end %>
   <style>
+    /* Direction "Signals" (see docs/conventions.md and the brand book).
+       Dark is PRIMARY — the audience lives in terminals; light is the
+       prefers-color-scheme override, the reverse of most sites. The lamp
+       (--accent) means "you can act on this" — links, focus, the live-step
+       dot — and NEVER means state. State is the aspect colours below. */
     :root {
-      --bg: #f7f7f8; --panel: #ffffff; --ink: #16181d; --muted: #6b7280;
-      --line: #e5e7eb; --accent: #4f46e5; --amber: #b45309; --amber-bg: #fef3c7;
-      --green: #047857; --green-bg: #d1fae5; --red: #b91c1c; --red-bg: #fee2e2;
-      --blue: #1d4ed8; --blue-bg: #dbeafe; --grey-bg: #eef0f3;
-      --radius: 14px; --mono: ui-monospace, SFMono-Regular, Menlo, monospace;
+      --bg:          #0F1013;  /* night */
+      --panel:       #16181D;  /* card, input, button face */
+      --ink:         #E9EBEF;  /* body text, wordmark */
+      --muted:       #969CA8;  /* metadata */
+      --line:        #262A33;  /* borders, rules */
+      --grey-bg:     #1D2027;  /* tool rows, <pre> */
+
+      /* the lamp — white at night, route-blue on paper: the ONE token allowed
+         to change hue between modes, because it represents light, not pigment */
+      --accent:      #F2F4F8;
+      --accent-soft: #1D2027;
+
+      /* aspects — run states */
+      --blue:   #58A6FF;  --blue-bg:   #14233D;  /* running */
+      --amber:  #E3B341;  --amber-bg:  #2E2611;  /* waiting -> "held" */
+      --violet: #B49AE8;  --violet-bg: #241E33;  /* in_doubt */
+      --green:  #3FB950;  --green-bg:  #12291B;  /* completed -> "clear" */
+      --red:    #F85149;  --red-bg:    #331815;  /* failed */
+      --quiet:  #737A87;  --quiet-line:#4A5160;  /* canceled — a lamp goes out */
+
+      --radius: 8px; --mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+      --sans-display: Archivo, "Helvetica Neue", Helvetica, Arial, sans-serif;
     }
-    @media (prefers-color-scheme: dark) {
+    @media (prefers-color-scheme: light) {
       :root {
-        --bg: #0d0f14; --panel: #161a22; --ink: #e6e8ec; --muted: #9aa2af;
-        --line: #262b36; --accent: #818cf8; --amber: #fbbf24; --amber-bg: #3a2e12;
-        --green: #34d399; --green-bg: #10291f; --red: #f87171; --red-bg: #35191a;
-        --blue: #60a5fa; --blue-bg: #14233d; --grey-bg: #1e232d;
+        --bg: #F4F4F2; --panel: #FFFFFF; --ink: #15171B; --muted: #5B5F68;
+        --line: #DCDEE3; --grey-bg: #EDEEF1;
+        --accent: #274FBF; --accent-soft: #E3E9FA;
+        --blue:   #1D4ED8; --blue-bg:   #DCE7F5;
+        --amber:  #92650E; --amber-bg:  #FBEED0;
+        --violet: #63459B; --violet-bg: #EAE3F7;
+        --green:  #157A3D; --green-bg:  #DCF3E3;
+        --red:    #B91C1C; --red-bg:    #FBDCDA;
+        --quiet:  #5B5F68; --quiet-line:#C7CAD1;
       }
     }
     * { box-sizing: border-box; }
     body {
       margin: 0; background: var(--bg); color: var(--ink);
-      font: 15px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+      font: 15px/1.5 ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
       -webkit-font-smoothing: antialiased;
     }
     .wrap { max-width: 640px; margin: 0 auto; padding: 20px 16px 64px; }
     header.top { display: flex; align-items: center; gap: 10px; margin-bottom: 18px; }
-    header.top .logo { font-weight: 700; letter-spacing: -0.02em; font-size: 20px; }
-    header.top .logo a { color: var(--ink); text-decoration: none; }
+    header.top .logo {
+      font-family: var(--sans-display); font-weight: 800;
+      letter-spacing: -0.03em; font-size: 20px;
+      display: inline-flex; align-items: center; gap: 8px;
+    }
+    header.top .logo a { color: var(--ink); text-decoration: none; display: inline-flex; align-items: center; gap: 8px; }
+    header.top .logo svg { display: block; }
     header.top .spacer { flex: 1; }
     .badge { background: var(--amber-bg); color: var(--amber); font-weight: 600;
       font-size: 12px; padding: 3px 9px; border-radius: 999px; }
-    a { color: var(--accent); }
+    a { color: var(--accent); text-underline-offset: 2px; }
     .card { background: var(--panel); border: 1px solid var(--line); border-radius: var(--radius);
       padding: 14px 16px; margin-bottom: 12px; }
     .session-row { display: block; text-decoration: none; color: inherit; }
@@ -49,8 +83,13 @@
     .pill-amber { background: var(--amber-bg); color: var(--amber); }
     .pill-green { background: var(--green-bg); color: var(--green); }
     .pill-red { background: var(--red-bg); color: var(--red); }
-    .pill-pulse { animation: pulse 1.4s ease-in-out infinite; }
-    @keyframes pulse { 0%,100% { opacity: 1; } 50% { opacity: 0.5; } }
+    .pill-violet { background: var(--violet-bg); color: var(--violet); }
+    /* canceled: a person stopped it — a lamp goes out, it doesn't turn red */
+    .pill-quiet { background: transparent; color: var(--quiet);
+      border: 1px dashed var(--quiet-line); padding: 1px 7px; }
+    /* running is the only aspect that moves */
+    .pill-pulse { animation: lamppulse 1.4s ease-in-out infinite; }
+    @keyframes lamppulse { 0%,100% { opacity: 1; } 50% { opacity: 0.45; } }
     .turn { border-left: 2px solid var(--line); padding-left: 14px; margin: 16px 0; }
     .turn-head { display: flex; align-items: center; gap: 8px; margin-bottom: 8px; }
     .turn-input { font-weight: 600; }
@@ -59,51 +98,71 @@
       border-radius: 50%; background: var(--accent); }
     .step-text { margin: 2px 0; }
     .step-live { white-space: pre-wrap; }
-    .tool { background: var(--grey-bg); border-radius: 10px; padding: 8px 10px; margin: 6px 0; font-size: 13px; }
+    .tool { background: var(--grey-bg); border-radius: var(--radius); padding: 8px 10px; margin: 6px 0; font-size: 13px; }
     .tool code { font-family: var(--mono); }
-    pre { font-family: var(--mono); font-size: 12px; background: var(--grey-bg); border-radius: 8px;
+    .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); }
+    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: 12px;
+    .approval { border: 1.5px solid var(--amber); background: var(--amber-bg); border-radius: var(--radius);
       padding: 12px 14px; margin: 10px 0; }
     .approval h3 { margin: 0 0 8px; font-size: 14px; color: var(--amber); }
-    .btn { display: inline-block; border: 0; border-radius: 10px; padding: 11px 18px; min-height: 44px;
+    .approval .question-text { margin: 0 0 8px; }
+    .held-stub { font-size: 13px; color: var(--amber); margin: 6px 0; }
+    .btn { display: inline-block; border: 0; border-radius: var(--radius); padding: 11px 18px; min-height: 44px;
       font-size: 15px; font-weight: 600; cursor: pointer; }
     .btn.approve { background: var(--green); color: #fff; }
     .btn.decline { background: var(--panel); color: var(--red); border: 1px solid var(--red); }
-    .decline-form textarea { width: 100%; border: 1px solid var(--line); border-radius: 8px;
+    .decline-form textarea { width: 100%; border: 1px solid var(--line); border-radius: var(--radius);
       padding: 8px; margin: 8px 0; font: inherit; background: var(--panel); color: var(--ink); resize: vertical; }
     form.inline { display: inline; }
     .cost { font-family: var(--mono); font-size: 12px; color: var(--muted); }
-    .composer textarea { width: 100%; border: 1px solid var(--line); border-radius: 10px;
+    .composer textarea { width: 100%; border: 1px solid var(--line); border-radius: var(--radius);
       padding: 10px 12px; font: inherit; background: var(--panel); color: var(--ink); resize: vertical; }
     .composer textarea:focus { outline: 2px solid var(--accent); outline-offset: -1px; }
     .composer-row { display: flex; align-items: center; justify-content: space-between; gap: 8px; margin-top: 8px; }
-    .btn.send { background: var(--accent); color: #fff; }
-    select.composer-agent { border: 1px solid var(--line); border-radius: 8px; padding: 6px 8px;
+    /* The lamp as a button: dark text on the white lamp at night, paper text
+       on route-blue in the light — var(--bg) tracks both. */
+    .btn.send { background: var(--accent); color: var(--bg); }
+    select.composer-agent { border: 1px solid var(--line); border-radius: var(--radius); padding: 6px 8px;
       font: inherit; background: var(--panel); color: var(--ink); margin-bottom: 8px; }
-    .flash { background: var(--red-bg); color: var(--red); padding: 10px 12px; border-radius: 10px; margin-bottom: 12px; }
+    .flash { background: var(--red-bg); color: var(--red); padding: 10px 12px; border-radius: var(--radius); margin-bottom: 12px; }
     .flash-notice { background: var(--green-bg); color: var(--green); }
     .btn-cancel { border: 1px solid var(--red); background: transparent; color: var(--red);
-      border-radius: 8px; padding: 2px 10px; font-size: 12px; font-weight: 600; cursor: pointer; margin-left: auto; }
+      border-radius: var(--radius); padding: 2px 10px; font-size: 12px; font-weight: 600; cursor: pointer; margin-left: auto; }
     pre.error { background: var(--red-bg); color: var(--red); }
     pre.args { opacity: 0.85; }
     .empty { text-align: center; color: var(--muted); padding: 48px 0; }
+    .rail-title { font-size: 12px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.06em;
+      color: var(--muted); margin: 20px 0 8px; }
     .agent-filter { display: flex; gap: 6px; flex-wrap: wrap; margin-bottom: 14px; }
-    .agent-filter .chip { font-size: 12px; padding: 3px 10px; border: 1px solid #d9dce1;
+    .agent-filter .chip { font-size: 12px; padding: 3px 10px; border: 1px solid var(--line);
       border-radius: 999px; text-decoration: none; color: inherit; }
-    .agent-filter .chip-on { background: #16181d; color: #fff; border-color: #16181d; }
+    .agent-filter .chip-on { background: var(--ink); color: var(--bg); border-color: var(--ink); }
     .pager { text-align: center; margin: 16px 0; }
     .pager .chip { font-size: 13px; padding: 6px 14px; border: 1px solid var(--line);
       border-radius: 999px; text-decoration: none; color: inherit; }
     .topup-form { display: flex; gap: 8px; margin-top: 8px; }
-    .topup-input { flex: 1; border: 1px solid var(--line); border-radius: 8px; padding: 8px 10px;
+    .topup-input { flex: 1; border: 1px solid var(--line); border-radius: var(--radius); padding: 8px 10px;
       font: inherit; background: var(--panel); color: var(--ink); }
   </style>
 </head>
 <body>
   <div class="wrap">
     <header class="top">
-      <span class="logo"><%= link_to "Silas", inbox_sessions_path %></span>
+      <span class="logo">
+        <%= link_to inbox_sessions_path do %>
+          <%# The mark: a position-light signal, diagonal = "proceed". Bezel in
+              ink, lamps in the accent — so the lamps are white at night and
+              route-blue on paper, per the one-token-may-change-hue rule. %>
+          <svg width="22" height="22" viewBox="0 0 24 24" fill="none" role="img" aria-hidden="true"><circle cx="12" cy="12" r="9.6" fill="none" style="stroke: var(--ink)" stroke-width="2.2"/><circle cx="8.4" cy="15.6" r="2.5" style="fill: var(--accent)"/><circle cx="15.6" cy="8.4" r="2.5" style="fill: var(--accent)"/></svg><span>silas</span>
+        <% end %>
+      </span>
       <span class="spacer"></span>
       <% if content_for?(:header_extra) %><%= yield :header_extra %><% end %>
     </header>

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

@@ -1,14 +1,37 @@
-<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 %>
+<%# 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.
+
+    The wrapper id is dom_id(invocation, :approval) — DISTINCT from the trace
+    row's dom_id(invocation) — because this card lives at the TOP of the
+    session (04) while the trace keeps a stub. When the invocation settles,
+    Broadcastable replaces this target with the empty shell below and the card
+    disappears from the top. %>
+<div id="<%= dom_id(invocation, :approval) %>">
+<% if !invocation.awaiting_approval? %>
+<% elsif 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 %>
 </div>

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

@@ -5,23 +5,35 @@
     <%# 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>
     <% 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>
     <% elsif invocation.approval_state == "expired" %>
-      <span class="muted">approval expired unanswered</span>
+      <span class="muted"><%= invocation.question? ? "question expired unanswered" : "approval expired unanswered" %></span>
     <% end %>
   </div>
   <% if invocation.awaiting_approval? %>
-    <%= render "silas/inbox/invocations/approval_card", invocation: invocation %>
+    <%# The card itself lives at the TOP of the session (04) — the trace keeps
+        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. %>
+    <%# 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? %>
-      <pre class="args"><%= pretty_args(invocation.arguments) %></pre>
+      <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? %>
-      <pre><%= pretty_args(invocation.result) %></pre>
+      <details class="tool-result">
+        <summary>result</summary>
+        <pre><%= pretty_args(invocation.result) %></pre>
+      </details>
     <% end %>
   <% end %>
 </div>

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

@@ -0,0 +1,14 @@
+<%= link_to inbox_session_path(session), class: "card session-row" 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 %>
+    <% pending = pending_counts.fetch(session.id, 0) %>
+    <% if pending.positive? %><span class="badge"><%= pending %> held</span><% end %>
+  </div>
+  <div class="muted">
+    <%= pluralize(session.turns.size, "turn") %> ·
+    <%= session.channel.presence || "direct" %> ·
+    <%= silas_relative_time(session.updated_at) %>
+  </div>
+<% end %>

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

@@ -33,21 +33,22 @@
 <% if @sessions.empty? %>
   <div class="empty">No agent sessions yet — start one above.</div>
 <% else %>
-  <% @sessions.each do |session| %>
-    <%= link_to inbox_session_path(session), class: "card session-row" 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 %>
-        <% pending = @pending_counts.fetch(session.id, 0) %>
-        <% if pending.positive? %><span class="badge"><%= pending %> to approve</span><% end %>
-      </div>
-      <div class="muted">
-        <%= pluralize(session.turns.size, "turn") %> ·
-        <%= session.channel.presence || "direct" %> ·
-        <%= silas_relative_time(session.updated_at) %>
-      </div>
-    <% end %>
+  <%# 06: the rail, grouped by who's blocked. Held = a person is needed
+      (pending approvals/questions, or a turn parked waiting/in_doubt);
+      Working = a worker holds it; Filed = nothing needs anyone. Grouping is
+      over the loaded page — same queries the flat list already ran. %>
+  <%
+    held, rest = @sessions.partition do |s|
+      @pending_counts.fetch(s.id, 0).positive? ||
+        s.turns.any? { |t| %w[waiting in_doubt].include?(t.status) }
+    end
+    working, filed = rest.partition { |s| s.turns.any? { |t| %w[queued running].include?(t.status) } }
+  %>
+  <% { "Held" => held, "Working" => working, "Filed" => filed }.each do |title, group| %>
+    <% next if group.empty? %>
+    <div class="rail-title"><%= title %></div>
+    <%= render partial: "silas/inbox/sessions/row", collection: group, as: :session,
+               locals: { pending_counts: @pending_counts } %>
   <% end %>
   <% if @next_before %>
     <div class="pager">

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

@@ -15,6 +15,15 @@
   <div id="silas-session-<%= @session.id %>-cost"><%= render "silas/inbox/sessions/cost", session: @session %></div>
 </div>
 
+<%# 04: everything awaiting a person sits ABOVE the movement — the operator
+    never scrolls a long trace hunting for the card. Live parks are appended
+    here by Broadcastable; settled cards replace themselves with an empty
+    shell and vanish. %>
+<div id="silas-session-<%= @session.id %>-approvals">
+  <%= render partial: "silas/inbox/invocations/approval_card",
+             collection: @session.pending_approvals.order(:id), as: :invocation %>
+</div>
+
 <div id="silas-turns">
   <%= render partial: "silas/inbox/turns/turn", collection: @turns, as: :turn %>
 </div>

data/config/routes.rb

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

data/db/migrate/20260725000002_create_silas_compactions.rb

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

data/docs/agents.md

@@ -0,0 +1,81 @@
+# Agents & staff
+
+## The root agent
+
+`app/agent/` is the default agent: `instructions.md` (the persona — ERB,
+snapshotted once per turn), `agent.yml` (data-only config), and directories
+for tools, skills, schedules, channels, and connections. Start it from
+anywhere in your app:
+
+```ruby
+session = Silas.agent.start(input: "Refund order 42, £12.50")
+session.continue(input: "Now email the customer.")
+```
+
+`agent.yml` keys:
+
+```yaml
+model: claude-sonnet-4-5   # must resolve in ruby_llm's registry; defaults to config.default_model
+description: One line, shown in rosters.
+limits:                    # per-turn caps — see docs/budgets.md
+  max_steps: 10
+  max_cost: 0.25
+  timeout: 300
+final_answer:              # optional JSON schema -> Turn#answer_data (structured answers)
+  type: object
+  properties: { verdict: { type: string } }
+  required: [verdict]
+```
+
+## Named agents — the staff pattern
+
+One app can employ several agents, each with its own room:
+
+```
+app/agents/
+  escalations/
+    instructions.md
+    agent.yml        # same keys as the root agent
+    tools/           # its own toolset — the root agent's tools are not inherited
+    skills/
+    schedules/       # its own cron, ticking IT — not the root agent
+```
+
+Sessions are stamped with the agent's name, and every turn — including crash
+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.
+
+```ruby
+Silas.agent("escalations").start(input: "…")
+```
+
+```sh
+bin/rails silas:chat AGENT=escalations   # talk to one staff member
+```
+
+The inbox filters by agent; the root `app/agent/` stays the default.
+
+## Subagents — delegation within a turn
+
+The built-in `delegate` tool runs a scoped sub-task under a subagent's own
+instructions and toolset and returns its answer into the parent turn. Use it
+to keep a specialist's tools out of the main agent's prompt until needed.
+
+## Handoffs — durable work between staff
+
+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.
+
+## Schedules give any agent a clock
+
+A markdown file in the agent's `schedules/` directory — cron frontmatter, body
+= the turn input — compiled by `bin/rails silas:schedules` into Solid Queue
+recurring tasks (cron that fires real work stays a reviewable git diff). A
+scheduled tick is a normal durable turn for **that** agent: it can hold for
+approval, spend budget, and appear in the inbox like any other. `.rb` handlers
+(subclassing `Silas::Schedule::Handler`) cover the programmatic cases.

data/docs/budgets.md

@@ -0,0 +1,67 @@
+# Budgets
+
+A turn gets four caps. Breaching `max_input_tokens`, `max_cost`, or `timeout`
+**parks the turn** — like an approval, at zero compute — completed work is
+never destroyed, and a human can top the cap up and resume from the inbox.
+`max_steps` is different: it's the runaway-loop guard, and hitting it **fails
+the turn loudly** (`failure_reason: "max_steps"`).
+
+## The caps
+
+Declared per agent in `agent.yml` (each is optional; unset = uncapped, except
+`max_steps` which defaults from `config.max_steps`):
+
+```yaml
+limits:
+  max_steps: 10           # model calls per turn
+  max_input_tokens: 200000 # cumulative input tokens across the turn's steps
+  max_cost: 0.25          # dollars per turn (priced tokens only)
+  timeout: 300            # seconds of ACTIVE work — held time doesn't count
+```
+
+## Semantics — the details that matter
+
+- **Checks run between steps**, in the framework-owned loop, never inside a
+  continuation step. A cap can't fire mid-model-call; the in-flight step's
+  work always commits.
+- **Token and cost checks are deterministic** — they read the persisted step
+  rows, so a crash-replay reaches the same verdict.
+- **Cost only counts priced tokens.** Pricing comes from RubyLLM's model
+  registry, overridable per model with `config.model_prices` (fine-tunes,
+  custom deployments, models newer than your installed registry). A model the
+  registry can't price can't be cost-capped.
+- **`timeout` measures active wall-clock.** The clock **restarts when an
+  approval resumes the turn** — it bounds active stretches of work, never the
+  hours a human spends deciding. Crash-rescue resumes keep the original clock:
+  the turn was live the whole time. (Reading the clock is benign
+  non-determinism: a cap firing later on a replay is still a correct cap — the
+  turn genuinely ran too long across the crash.)
+
+## What a breach looks like
+
+The turn parks with status `waiting` and the breached cap as its park reason
+(`max_input_tokens` / `max_cost` / `timeout`). In the inbox the turn shows
+**held** with a raise-budget control; over the API it's visible on the
+session's turns.
+
+## Topping up
+
+`Turn#raise_budget!` records a **per-turn override** that beats the agent's
+configured limit for that cap, then resumes the turn:
+
+```ruby
+turn.raise_budget!(max_cost: 1.00)
+```
+
+The inbox's raise-budget button does exactly this. Overrides live on the turn
+(`budget_overrides`), so one generous exception never loosens the agent's
+standing limits.
+
+## Choosing limits
+
+Set `max_cost` on anything using an expensive model — it's the cap that maps
+to money. `max_steps` is the runaway-loop guard. `timeout` protects worker
+slots from a wedged provider (the adapter's own request timeout should be
+tighter). `max_input_tokens` is mostly superseded by compaction
+(`config.compact_at` summarises long conversations instead of failing them) —
+keep it as a hard ceiling if you cap spend per turn strictly.

data/docs/cancellation.md

@@ -0,0 +1,41 @@
+# Cancellation
+
+Cancel means *a person stopped it* — in the UI it renders as a lamp going out
+(quiet, dashed), not a failure. Under the hood there are exactly two cases,
+decided by whether anything is live:
+
+## Parked or queued: settles immediately
+
+A turn with no live execution — held on an approval, a question, a budget
+breach, or still queued — cancels synchronously:
+
+- status → `canceled`, finished stamp set;
+- every pending approval on the turn is **expired** with the cancel reason
+  recorded as its denial — so a later `approve!` can't zombie-resume a turn
+  someone already killed.
+
+## Running: honored at the next step boundary
+
+A turn a worker is actively executing gets **flagged**
+(`cancel_requested_at`), and the loop honors the flag at the next step
+boundary. The in-flight model call completes and its step commits first —
+aborting mid-step would forfeit paid tokens and create an in-doubt tool window
+for nothing. That's why the inbox button says *"honored at the next step
+boundary."*
+
+If the process crashes between the flag and the boundary, the resume sees the
+flag and cancels then. A cancel landing later than intended is still a correct
+cancel — this is the same benign wall-clock non-determinism as the budget
+timeout.
+
+## Surfaces
+
+```ruby
+turn.cancel!                    # => :canceled or :cancel_requested
+```
+
+- **Inbox**: the cancel button on an active turn.
+- **API**: `POST /silas/api/v1/turns/:id/cancel`.
+
+Canceling raises if the turn is already terminal. The session stays usable —
+`session.continue(input: "…")` starts a fresh turn after a canceled one.