solid_loop 0.0.4 → 0.0.5

data/app/views/solid_loop/messages/_message.html.erb

@@ -1,73 +1,64 @@
 <div id="sl-message-<%= message.id %>" class="sl-card sl-message sl-message--<%= message.role %>">
   <div class="sl-message__header">
-    <strong class="sl-message__role">
-      <%= message.role %>
-    </strong>
+    <strong class="sl-message__role"><%= message.role %></strong>
     <% model_name = message.metadata&.dig("model") %>
     <% if model_name.present? %>
-      <span class="sl-badge sl-badge--pending" title="Model that served this turn" style="margin-left: 6px; font-weight: normal;">
-        <%= model_name %>
-      </span>
+      <span class="sl-badge sl-badge--pending sl-message__model" title="Model that served this turn"><%= model_name %></span>
     <% end %>
-    <span class="sl-message__time">
-      <%= message.created_at.strftime("%H:%M:%S") %>
-    </span>
+    <span class="sl-message__time"><%= message.created_at.strftime("%H:%M:%S") %></span>
   </div>
 
+  <%# Each block below owns its own <pre>. The container must NOT be pre-wrap:
+      it would render this template's own indentation and blank lines as content,
+      which is what used to indent the first line and open gaps before the footer. %>
   <div class="sl-json">
     <% if message.content.present? %>
-      <%= message.content %>
+      <pre class="sl-pre-wrap sl-message__body"><%= message.content %></pre>
     <% end %>
 
     <% if message.tool_calls_raw.present? || message.tool_calls.any? %>
       <div class="sl-message__tools">
-        <strong>Tools:</strong>
-        <div class="sl-mt-10">
-          <% (message.tool_calls.any? ? message.tool_calls : message.tool_calls_raw).each do |tc| %>
-            <% 
-               name = tc.is_a?(SolidLoop::ToolCall) ? tc.function_name : tc.dig("function", "name")
-               tc_id = tc.is_a?(SolidLoop::ToolCall) ? tc.id : nil
-            %>
-            <div class="sl-badge <%= tc.is_a?(SolidLoop::ToolCall) && tc.is_success ? 'sl-badge--success' : 'sl-badge--pending' %>" style="margin-bottom: 5px;">
-              <% if tc_id %>
-                <%= link_to name, tool_call_path(tc_id), style: "color: inherit; text-decoration: none;" %>
-              <% else %>
-                <%= name %>
-              <% end %>
-            </div>
-          <% end %>
-        </div>
+        <span class="sl-message__tools-label">Tools</span>
+        <% (message.tool_calls.any? ? message.tool_calls : message.tool_calls_raw).each do |tc| %>
+          <%
+             name  = tc.is_a?(SolidLoop::ToolCall) ? tc.function_name : tc.dig("function", "name")
+             tc_id = tc.is_a?(SolidLoop::ToolCall) ? tc.id : nil
+          %>
+          <span class="sl-badge <%= tc.is_a?(SolidLoop::ToolCall) && tc.is_success ? 'sl-badge--success' : 'sl-badge--pending' %>">
+            <% if tc_id %><%= link_to name, tool_call_path(tc_id), class: "sl-badge__link" %><% else %><%= name %><% end %>
+          </span>
+        <% end %>
       </div>
     <% end %>
 
     <% if message.reasoning_content.present? %>
-      <div class="sl-message__reasoning">
-        <em>Thinking:</em>
+      <details class="sl-message__reasoning">
+        <summary class="sl-message__reasoning-toggle">Thinking (<%= message.reasoning_content.length %> chars)</summary>
         <pre class="sl-pre-wrap"><%= message.reasoning_content %></pre>
-      </div>
+      </details>
     <% end %>
 
     <div class="sl-message__footer">
       <div class="sl-message__footer-item">
-        Tokens: <span class="sl-message__footer-value">P<%= message.tokens_prompt %>+C<%= message.tokens_completion %></span>
+        Tokens <span class="sl-message__footer-value">P<%= message.tokens_prompt %>+C<%= message.tokens_completion %></span>
         <% if message.tokens_prompt_cached > 0 %>
-          <span style="color: var(--sl-success); font-size: 0.9em; margin-left: 4px;">(cached <%= message.tokens_prompt_cached %>)</span>
+          <span class="sl-message__cached">(cached <%= message.tokens_prompt_cached %>)</span>
         <% end %>
       </div>
       <div class="sl-message__footer-item">
-        Cost: <span class="sl-message__footer-value"><%= sl_money(message.cost) %></span>
+        Cost <span class="sl-message__footer-value"><%= sl_money(message.cost) %></span>
       </div>
       <% if message.tps > 0 %>
         <div class="sl-message__footer-item">
-          TPS: <span class="sl-message__footer-value"><%= message.tps %></span>
+          TPS <span class="sl-message__footer-value"><%= message.tps %></span>
         </div>
       <% end %>
       <% if message.ttft > 0 %>
         <div class="sl-message__footer-item">
-          TTFT: <span class="sl-message__footer-value"><%= number_with_precision(message.ttft, precision: 2) %>s</span>
+          TTFT <span class="sl-message__footer-value"><%= number_with_precision(message.ttft, precision: 2) %>s</span>
         </div>
       <% end %>
-      <div class="sl-message__footer-item" style="margin-left: auto;">
+      <div class="sl-message__footer-item sl-message__footer-item--end">
         <%= link_to "Details", message_path(message), class: "sl-btn sl-btn--small" %>
       </div>
     </div>

data/app/views/solid_loop/messages/index.html.erb

@@ -66,8 +66,22 @@
           %>"><%= message.role.upcase %></span>
         </td>
         <td class="sl-table__td"><%= message.metadata&.dig("model").presence || "—" %></td>
-        <td class="sl-table__td">P<%= message.tokens_prompt %>+C<%= message.tokens_completion %></td>
-        <td class="sl-table__td"><%= sl_money(message.cost) %></td>
+        <td class="sl-table__td">
+          <%# `tokens_total` is the persisted figure the loop's budget is checked
+              against; the in/out split is the detail, so it goes underneath
+              rather than being the only thing shown ("P0+C0" told you nothing).
+              A message still being streamed has its completion tokens written by
+              `trigger_content_append` but no total yet, so fall back to the sum
+              rather than printing "—" next to a non-zero breakdown. %>
+          <% total = message.tokens_total.to_i.positive? ? message.tokens_total.to_i : message.tokens_prompt.to_i + message.tokens_completion.to_i %>
+          <span class="sl-metric"><%= sl_tokens(total) %></span>
+          <% if message.tokens_prompt.to_i.positive? || message.tokens_completion.to_i.positive? %>
+            <span class="sl-metric__sub">
+              in <%= number_with_delimiter(message.tokens_prompt.to_i) %> · out <%= number_with_delimiter(message.tokens_completion.to_i) %><%= " · cached #{number_with_delimiter(message.tokens_prompt_cached.to_i)}" if message.tokens_prompt_cached.to_i.positive? %>
+            </span>
+          <% end %>
+        </td>
+        <td class="sl-table__td"><span class="sl-metric <%= "sl-metric--blank" unless message.cost.to_f.positive? %>"><%= sl_money(message.cost) %></span></td>
         <td class="sl-table__td"><%= message.created_at.strftime("%Y-%m-%d %H:%M") %></td>
         <td class="sl-table__td" style="text-align: right;">
           <%= link_to "View", message_path(message), class: "sl-btn sl-btn--small" %>

data/app/views/solid_loop/tool_calls/index.html.erb

@@ -1,3 +1,7 @@
+<div class="sl-page-header">
+  <h2>Tool Calls</h2>
+</div>
+
 <div class="sl-card">
   <%= form_with url: tool_calls_path, method: :get, class: "sl-page-header__actions", style: "justify-content: flex-start; flex-wrap: wrap;" do |f| %>
     <div style="display: flex; align-items: center; gap: 8px;">
@@ -6,7 +10,11 @@
     </div>
     <div style="display: flex; align-items: center; gap: 8px; margin-left: 20px;">
       <span class="sl-stat-card__label">Function:</span>
-      <%= f.text_field :function_name, value: params[:function_name], class: "sl-btn sl-btn--small", placeholder: "list_files" %>
+      <%= f.select :function_name,
+          options_for_select([["All Functions", ""]] + @function_names.map { |name| [name, name] }, params[:function_name]),
+          {},
+          class: "sl-btn sl-btn--small",
+          onchange: "this.form.submit()" %>
     </div>
     <div style="display: flex; align-items: center; gap: 8px; margin-left: 20px;">
       <span class="sl-stat-card__label">Status:</span>
@@ -27,20 +35,27 @@
   <thead>
     <tr>
       <th class="sl-table__th">ID</th>
-      <th class="sl-table__th">Message ID</th>
+      <th class="sl-table__th">Loop</th>
+      <th class="sl-table__th">Message</th>
       <th class="sl-table__th">Function</th>
       <th class="sl-table__th">Status</th>
+      <th class="sl-table__th">Duration</th>
       <th class="sl-table__th">Created At</th>
       <th class="sl-table__th">Actions</th>
     </tr>
   </thead>
   <tbody>
     <% @tool_calls.each do |tool_call| %>
+      <% loop_id = @loop_ids_by_message[tool_call.message_id] %>
       <tr>
         <td class="sl-table__td"><%= tool_call.id %></td>
+        <td class="sl-table__td">
+          <%= link_to "##{loop_id}", loop_path(loop_id) if loop_id %>
+        </td>
         <td class="sl-table__td"><%= link_to tool_call.message_id, message_path(tool_call.message_id) if tool_call.message_id %></td>
-        <td class="sl-table__td"><%= tool_call.function_name %></td>
+        <td class="sl-table__td"><strong><%= tool_call.function_name %></strong></td>
         <td class="sl-table__td"><span class="sl-badge sl-badge--<%= tool_call.error_message.present? ? 'error' : 'success' %>"><%= tool_call.error_message.present? ? 'failed' : 'success' %></span></td>
+        <td class="sl-table__td"><%= sl_duration_cell(tool_call.duration, scale: :tool) %></td>
         <td class="sl-table__td"><%= tool_call.created_at.strftime("%Y-%m-%d %H:%M") %></td>
         <td class="sl-table__td">
           <%= link_to "View", tool_call_path(tool_call), class: "sl-btn sl-btn--small" %>

data/db/migrate/20260819000100_solid_loop_add_retention_indexes.rb

@@ -0,0 +1,22 @@
+class SolidLoopAddRetentionIndexes < ActiveRecord::Migration[7.1]
+  # Retention sweeps select by age. Without these, `SolidLoop.prune!` seq-scans
+  # exactly the tables it exists to keep small — the more overdue the cleanup,
+  # the more expensive the query that performs it.
+  #
+  # Built CONCURRENTLY (hence no DDL transaction): these tables are append-only
+  # hot paths — every LLM turn and every inbound MCP request writes one — and an
+  # ACCESS EXCLUSIVE lock for the duration of a plain index build would stall
+  # agents on a table that is, by construction, already large by the time an
+  # operator reaches for retention.
+  disable_ddl_transaction!
+
+  def change
+    add_index :solid_loop_events, :created_at,
+              name: "index_solid_loop_events_on_created_at",
+              algorithm: :concurrently, if_not_exists: true
+
+    add_index :solid_loop_mcp_inbound_sessions, :created_at,
+              name: "index_solid_loop_mcp_inbound_sessions_on_created_at",
+              algorithm: :concurrently, if_not_exists: true
+  end
+end

data/docs/contributing/coverage.md

@@ -40,25 +40,25 @@ Use `make ci` when you want the closest local approximation of the full gem vali
 
 ```bash
 # staged changes only
-rails 'coverage:report[worst,,staged]'
+bundle exec rake 'coverage:report[worst,,staged]'
 
 # all branch changes since main
-rails 'coverage:report[worst,,branch]'
+bundle exec rake 'coverage:report[worst,,branch]'
 
 # last commit
-rails 'coverage:report[worst,,head]'
+bundle exec rake 'coverage:report[worst,,head]'
 ```
 
 ## Explore Weak Spots
 
 ```bash
-rails 'coverage:report[partial]'
-rails 'coverage:report[partial,service]'
-rails 'coverage:report[worst,controller]'
-rails coverage:report
+bundle exec rake 'coverage:report[partial]'
+bundle exec rake 'coverage:report[partial,service]'
+bundle exec rake 'coverage:report[worst,controller]'
+bundle exec rake coverage:report
 ```
 
 ## Source Of Truth
 
-- Task implementation: `lib/tasks/coverage.rake`
+- Task implementation: `tasks/coverage.rake`
 - Coverage artifact: `coverage/coverage.json`

data/docs/decisions/mcp-server.md

@@ -160,8 +160,10 @@ Lifecycle:
 - `DELETE` with a session header → session **terminated, row kept**
   (`terminated_at`), `204`. Destroying the row would cascade into its events —
   a client must not be able to erase its own audit trail with one request.
-- No TTL/eviction in 0.0.4; rows are cheap and admin-visible. Retention can
-  ride the 0.0.5 storage work.
+- No TTL/eviction in 0.0.4; rows are cheap and admin-visible. 0.0.5 adds
+  age-based retention: with `config.mcp_inbound_session_retention` set,
+  `SolidLoop::Janitor` deletes sessions older than that by `created_at`, and
+  their events with them. It stays `nil` (keep everything) by default.
 
 ## Observability
 

data/docs/decisions/reasoning_persistence.md

@@ -14,23 +14,81 @@ If the reasoning block from Turn N is not sent back to the model in Turn N+1, th
 
 `SolidLoop` implements a flexible **Reasoning Protocol** to handle the inconsistent landscape of LLM providers. Instead of a single "hack," we use an **array of strategies** configured per agent/model. This allows combining multiple methods to ensure the model receives its thoughts regardless of how strict or fragmented the provider's API is.
 
+### Choosing a default
+
+The default is `nil` on `SolidLoop::Base#reasoning_strategies`, which means "ask
+the dialect". `open_ai` answers `["reasoning_content"]`, `anthropic`
+`[:anthropic_signed]`, `gemini` `[:gemini_signed]`.
+
+`:xml` was the default for every dialect until 0.0.5, on the reasoning that it
+is the shape no provider can strip. That is true and it is also expensive:
+welded reasoning is part of the assistant message body, so it is billed as
+prompt tokens on every later turn and compounds over a run.
+
+Measured with vLLM's `/tokenize` on the Qwen3 chat template, one six-message
+conversation:
+
+```
+<think> welded into content                1438 tokens
+reasoning_content field                     108
+reasoning omitted entirely                  108
+```
+
+`reasoning_content` and omitting the reasoning altogether cost the same, because
+that template drops the field from history — which is what Qwen3's own guidance
+asks for ("historical model output should only include the final output part").
+
+That equality has to be read carefully: the two encodings are not the same
+request written differently. Welding puts the old thoughts back in front of the
+model as ordinary text; the field, on this template, does not. Choosing the
+field is therefore a decision to stop replaying reasoning on this model family,
+which is what its authors recommend — not a free compression. The saving is
+large: a long agent loop can end up spending a large fraction of its context
+window on repacked reasoning. Whether a given model does better with or without
+its old thoughts is a question for a run, not for a token count.
+
+This is why the choice belongs to the dialect rather than to one global default.
+Each one now answers with the shape its provider actually has a slot for:
+`"reasoning_content"` on `open_ai`, `:anthropic_signed` on `anthropic`,
+`:gemini_signed` on `gemini`.
+
+The two signed shapes carry a provider-issued signature that is verified when
+the reasoning comes back — that is what makes a replayed thought provably the
+model's own instead of ordinary text that has to be re-billed. They are
+therefore all-or-nothing: a message with no captured signature sends **no
+reasoning**, because the alternative is a block the provider rejects. Loops that
+ran before the dialects started storing signatures lose their old thoughts on
+the next turn. That is the intended trade — the alternative was leaving both
+dialects on the shape that costs 13× the tokens. A host that would rather keep
+the text can write `[:anthropic_signed, :xml]`: the `:xml` fallback fires
+exactly when the signed strategy could not.
+
+The measurement is template-specific. Another chat template may render
+`reasoning_content` into the prompt instead of dropping it, in which case the
+token saving disappears (the cleaner wire shape does not). Re-run the three-way
+comparison against a new model before assuming it carries over.
+
 ### Supported Strategies:
 
 *   **`:xml` (The DeepSeek/Reliability Standard):**
-    Wraps the reasoning content in `<think>...</think>` tags and prepends it to the main `content` string. This is the most robust method as it bypasses API field stripping.
+    Wraps the reasoning content in `<think>...</think>` tags and prepends it to the main `content` string. This is the most robust method as it bypasses API field stripping — and the most expensive, since the wrapped text becomes part of the message body and is billed as prompt tokens on every later turn. Reach for it when the provider strips fields, not by default.
     *Note: In `SolidLoop`, this is a "Smart" strategy. It will automatically suppress itself if a native strategy (like `:gemini_signed`) is also present, avoiding redundant context.*
 *   **`:xml!` (Forced XML):**
     Same as `:xml`, but **ignores** native strategy suppression. Use this if you want to ensure thoughts are visible in the main context even if the provider supports native fields.
 *   **`:gemini_signed` (The Google Standard):**
-    Passes both the `thought` text and the `thought_signature` (stored in JSONB metadata) back in specific fields required by Gemini 2.0+ for multi-turn reasoning.
+    Sends the thought back as a Gemini part — `{ thought: true, text: "...", thoughtSignature: "..." }`. Note that `thought` is a **boolean flag** on the part and the summary text lives in `text`, the same key an ordinary answer uses; the signature rides on a part too (the thought part, or the `functionCall` part on a tool-calling turn), never on the candidate. Drops the reasoning when no signature was captured.
+*   **`:anthropic_signed` (The Anthropic Standard):**
+    Sends the thought back as a `{ type: "thinking", thinking: "...", signature: "..." }` content block, first in the assistant message's content array. Anthropic verifies the signature, so this drops the reasoning when none was captured.
 *   **`"field_name"` (Explicit Mapping):**
     Allows copying the reasoning content into a specific JSON key (e.g., `"reasoning_content"`, `"thought"`, or `"internal_thinking"`) to satisfy various provider requirements (OpenRouter, vLLM, Groq).
 
 ### Example Combinations:
 
-*   **`[:xml]`**: Maximum reliability for DeepSeek or OpenRouter (when field stripping is suspected).
+*   **`nil` (the default)**: Let the dialect choose — `"reasoning_content"` on `open_ai`, `:anthropic_signed` on `anthropic`, `:gemini_signed` on `gemini`.
+*   **`[:xml]`**: Maximum reliability for DeepSeek or OpenRouter (when field stripping is suspected), at full prompt-token price.
 *   **`["reasoning", "reasoning_content"]`**: Populating multiple fields in parallel — useful when the provider's accepted field name is uncertain.
 *   **`[:gemini_signed, "thought", "reasoning_content"]`**: A comprehensive strategy for Gemini-compatible providers that might also look for OpenAI-style fields.
+*   **`[:anthropic_signed, :xml]`**: Signed blocks where a signature exists, welded `<think>` where one does not — the `:xml` fallback fires only when the signed strategy could not.
 *   **`[]` (Empty Array)**: Standard for OpenAI o1/o3 (reasoning is stripped to avoid 400 errors).
 
 ## 3. The Reasoning Verifier *(not implemented)*
@@ -45,7 +103,65 @@ To ensure an agent is actually "hearing its own thoughts," a **Reasoning Verific
 
 Worth doing — it would give a cheap, repeatable way to verify that `ReasoningPacker` is actually working end-to-end with a given provider/strategy combination, rather than assuming it does.
 
-## 4. Data Storage
+## 4. Measuring the Cost
+
+`ReasoningPacker.pack_all` reports what each request's prompt is carrying, and
+the adapter stamps it onto the assistant message that request produced:
+
+```ruby
+message.metadata["reasoning_carried"]
+# => { "messages" => 6, "chars" => 84616, "inline_chars" => 84616, "tokens_est" => 21154 }
+```
+
+`chars` is everything sent back in any shape; `inline_chars` is only the part
+welded into `content`, which every provider bills. Without it the cost has to be
+reconstructed from message lengths after the fact, which is how a loop reaches
+its window ceiling without anyone seeing why. codex tracks the same number for
+the same reason (`context_manager/history.rs` sums the tokens of every reasoning
+item before the last user message).
+
+## 5. Why There Is No Trimming Strategy
+
+The obvious way to bound a growing context is to stop resending old reasoning —
+keep the newest `n` turns, drop the rest. SolidLoop deliberately offers no such
+strategy, because it is a trap.
+
+A prefix cache exists because turn N's prompt is turn N-1's plus a new tail: the
+server re-uses the KV of everything before it and prefills only the tail. A
+sliding retained window rewrites the *middle* of the prompt instead — the
+message that ages out changes, the prompt diverges at its position, and
+everything after it is prefilled again, every turn. Measured on llama.cpp
+(Qwen3.8-27B Q6_K, prefix caching on), an 8-step agent chain:
+
+| strategy | prompt | fresh/turn | prefill/turn | cached/turn |
+|---|---|---|---|---|
+| full reasoning | 4667 | 576 | 910 ms | 4091 |
+| newest 2 turns | 1541 | 1503 | 1847 ms | 38 |
+| send none | 499 | 59 | 500 ms | 440 |
+
+Trimming is not the problem; *sliding* is. The trimmed run costs twice the
+prefill of the untrimmed history it was meant to be cheaper than, and degrades
+the model's context as well — the worst of both. Both stable rules keep the
+cache: with the full history each reasoning block is prefilled exactly once,
+ever; with none, no block is.
+
+Neither reference harness trims per turn. codex keeps reasoning whole and only
+*accounts* for it (`get_non_last_reasoning_items_tokens()` counts the items
+before the last instruction boundary for estimation, and removes nothing); its
+boundaries move only when a user message arrives. opencode compacts on overflow
+(`session/compaction.ts`, `PRUNE_MINIMUM = 20_000`, `PRUNE_PROTECT = 40_000`):
+one pass that summarises the old history into a single assistant message and
+keeps a recent tail within a budget, after which the prompt is monotonically
+extending again. The Qwen3 GGUF chat template encodes the same instinct — its
+`preserve_thinking` flag cuts only before `ns.last_query_index`, a user-turn
+boundary, never per turn.
+
+**Compaction is the missing piece**, and it is bigger than a strategy symbol: it
+needs a summariser, a checkpoint message kind, and a rule for when to fire.
+Until it exists, the two supported positions are "carry the reasoning and let
+the prefix cache pay for it" and "send none".
+
+## 6. Data Storage
 
 *   **Reasoning Text:** Stored in the `reasoning_content` column of `solid_loop_messages`.
 *   **Signatures & Metadata:** Stored in the `metadata` JSONB column. This ensures we can support future tokens like `thought_signature` without schema migrations.

data/docs/guides/dialects.md

@@ -50,6 +50,6 @@ A Dialect object must implement the following methods to be compatible with the
 
 1.  **`completion_url(base_url)`**: Returns the specific API endpoint.
 2.  **`render_payload(universal_payload)`**: (Optional) Transforms the payload before sending.
-3.  **`apply_reasoning_strategies!(messages, strategies)`**: Formats message history according to the [Reasoning Protocol](./reasoning_persistence.md).
+3.  **`apply_reasoning_strategies!(messages, strategies)`**: Formats message history according to the [Reasoning Protocol](../decisions/reasoning_persistence.md). A `strategies` of `nil` means the agent left the choice to the dialect — substitute your own `default_reasoning_strategies`. Return the carry report from `ReasoningPacker.pack_all`; the adapter stamps it onto the message as `metadata["reasoning_carried"]`.
 4.  **`extract_message_data(raw_json)`**: Extracts content and tools from a streaming chunk or partial response.
 5.  **`normalize_response(raw_json)`**: Converts a full API response into the SolidLoop universal format (including token usage and metadata).

data/docs/guides/mcp_transports.md

@@ -184,6 +184,78 @@ Semantics:
 - Toolsets are stateless by default (`session_id` = nil → synthetic). A toolset
   may override `on_initialize(params, context)` to mint and later receive a
   real session id.
+- **`serverInfo.version`** defaults to the gem's version, which is rarely what a
+  mounted server means — semantically it is the version of *your* MCP server.
+  Declare it next to the name:
+
+  ```ruby
+  class SearchTools < SolidLoop::Mcp::Toolset
+    server_name    "search"
+    server_version "1.0.0"
+  end
+  ```
+
+- **`ping`** is answered out of the box with an empty result, as the base
+  protocol requires. Unknown methods still get `-32601`.
+- **Error codes** follow the MCP specification, which prescribes **`-32602`**
+  (invalid params) for an unknown tool or prompt on `tools/call` / `prompts/get`
+  — not `-32601`. `-32601` is reserved for an unknown *method*.
+
+### Dynamic tool and prompt catalogs
+
+The `tool` / `prompt` DSL registers at class-load time. A host whose catalog
+lives in the database and changes without a deploy overrides four instance
+methods instead — they default to the DSL and are consulted on every request
+(and by `capabilities`), so a row added a second ago is advertised on the next
+`prompts/list`:
+
+| Method | Default | Used by |
+| --- | --- | --- |
+| `available_tools` | `self.class.tools` | `tools/list` |
+| `find_tool(name)` | lookup in `available_tools` | `tools/call` |
+| `available_prompts` | `self.class.prompts` | `prompts/list`, `capabilities` |
+| `find_prompt(name)` | lookup in `available_prompts` | `prompts/get` |
+
+```ruby
+class SearchTools < SolidLoop::Mcp::Toolset
+  def available_prompts
+    SavedPrompt.active.each_with_object({}) do |row, acc|
+      acc[row.name] = PromptDefinition.new(
+        name: row.name, description: row.description, arguments: row.arguments,
+        handler: ->(args, _ctx) { format(row.body, args) }
+      )
+    end
+  end
+end
+```
+
+Return `{}` for "none", and keep the override **total**: `capabilities` calls
+`available_prompts` during `initialize`, so a raising override fails the
+handshake rather than one request.
+
+### Overriding `deliver`
+
+`deliver` is the documented seam for answering a method the gem does not model.
+The envelope builders it needs are **public API** and covered by the
+compatibility promise: `success_envelope(request, result)`,
+`error_envelope(request, code, message)`, `json_boundary(value)` and
+`tool_result(value)`.
+
+```ruby
+def deliver(payload, session_id: nil, context: nil)
+  request = json_boundary(payload)
+  return super unless request["method"] == "resources/list"
+
+  SolidLoop::Mcp::Result.new(
+    body: success_envelope(request, "resources" => []),
+    session_id: session_id, raw_request: payload, raw_response: nil, status: 200
+  )
+end
+```
+
+Prefer the dynamic-catalog hooks above when the need is "my prompts/tools come
+from somewhere else" — overriding `deliver` for that intercepts the protocol to
+solve a catalog problem, and has to be re-checked against every gem upgrade.
 - **Transactions:** the block runs on the caller's thread and shares the job's
   ActiveRecord connection. That makes a tool atomic with SolidLoop's own writes
   — and makes `transaction do ... end` inside a tool a *nested* transaction.

data/docs/validation.md

@@ -0,0 +1,85 @@
+# Validation
+
+What SolidLoop has been run against before a release, and what it has not.
+
+A gem that drives other people's inference budgets should be specific about the
+shape of its own evidence, including the gaps. This page is that statement, kept
+current per release.
+
+## The automated suite
+
+Unit, integration and request specs run against a PostgreSQL dummy app on Rails
+7.1, 7.2 and 8.1 (see [Testing](../README.md#testing)). The LLM and MCP peers
+are stubbed by emulators that speak each provider's wire format.
+
+The limit of that is worth saying plainly: **an emulator encodes our own reading
+of a provider's wire format.** Where the reading is wrong, the emulator is wrong
+in the same direction and the suite stays green. That is exactly what had
+happened to the `gemini` dialect before 0.0.5 — it had misread thought parts
+since it was written, and every test passed. Emulators catch regressions; they
+cannot catch a shared misconception.
+
+## 0.0.5 — local inference, sustained agentic load
+
+Before this release SolidLoop ran as the engine of a private agent application:
+batches of loops in parallel, each one a multi-turn coding task using MCP tools,
+repeated across many runs. The inference side was entirely local:
+
+| | |
+| --- | --- |
+| Servers | llama.cpp (`--jinja`, `--kv-unified`) and vLLM |
+| Model | Qwen3 27B — GGUF Q6_K on llama.cpp, NVFP4 on vLLM |
+| Hardware | 2 × NVIDIA RTX 5060 Ti, tensor-parallel |
+| Dialect | `open_ai` (both servers expose an OpenAI-compatible API) |
+
+Local OpenAI-compatible servers are a **stricter** test surface than the hosted
+API, which is why this is worth reporting rather than apologising for:
+
+- **They are unforgiving about malformed messages.** After a rejected tool call
+  SolidLoop was emitting a tool message with `"name": null`. vLLM ignores it;
+  llama.cpp rejects the entire request, and because the offending message stays
+  in history the loop then fails on every retry rather than recovering. Hosted
+  providers had never surfaced it. Fixed in 0.0.5.
+- **Their chat templates are inspectable.** What a dialect sends back can be
+  traced to an actual prompt-token count through `/tokenize`, which is how the
+  reasoning transport in 0.0.5 was chosen rather than guessed — see
+  [reasoning_persistence.md](decisions/reasoning_persistence.md).
+- **KV-cache and slot pressure are real and visible**, so context-budget defects
+  present as truncated tool-call arguments and traceable server logs instead of
+  an opaque 400.
+
+The application's own task results are not part of this claim — those measure
+the model, not the gem. What the runs establish about SolidLoop is narrower:
+loops ran concurrently to completion, leases and the reaper held across worker
+restarts, no turn was silently dropped, and the failures that did occur were
+traced to specific defects that now have specs and changelog entries.
+
+## What has not been tested
+
+- **The native `anthropic` and `gemini` dialects have never made a live call.**
+  Their payload shapes come from the published API documentation and are covered
+  by unit tests and emulators, but no real key has exercised them. 0.0.5 changes
+  the default reasoning transport for both to the providers' signed block
+  formats, so that untested path is now the default path for those two dialects.
+  If you are on `anthropic` or `gemini` and want the pre-0.0.5 behaviour while
+  you evaluate, set `reasoning_strategies` to `[:xml]`.
+- **Hosted providers were last exercised in 0.0.4**, through the `open_ai`
+  dialect against OpenAI- and OpenRouter-served models in a pilot Rails
+  application. 0.0.5 has not repeated that run — its provider coverage is the
+  local stand above.
+- **Scale.** SolidLoop has not been run at a size where Postgres or the job
+  backend was the bottleneck, nor over horizons measured in days. The durability
+  design ([durable_attempt_lease.md](decisions/durable_attempt_lease.md)) is
+  exercised by specs and by deliberate mid-run restarts, not by a long
+  production soak.
+
+## Reports are welcome
+
+Running SolidLoop against a provider, model, or scale that is not on this page
+is a genuine contribution, whether or not it comes with a patch. Useful in a
+report: the dialect and provider, the model, whether reasoning came back and in
+which field, and the relevant wire-log rows — `EventLogging` redacts
+credentials, including the API key Gemini carries in the URL, so those rows are
+safe to paste.
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md).