solid_loop 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3bbfed94f57749cc453fa556177eb4aa339e304c41d5c6e2dd58f5f55cd7c55
-  data.tar.gz: beda9759a9b2d1d576b007cc6782139b06c97922b7ce0bb0117685190d437f93
+  metadata.gz: bd93f901cbf4287ccdebd6779430f67cca0e4def0f73c159df3585f31c1644c8
+  data.tar.gz: 246d0fdda33059ed2c5a53d6356b7129f16c5c4c332d470966d366bc15eb659a
 SHA512:
-  metadata.gz: b9447a7363162eac0dcc9c23964855897a427a09a50c7af701e07cbea1edd65967f72766b9e6d419a8312189d35492bf67c1a0253815c779b53e73aadb6e28a0
-  data.tar.gz: 3477debd8e6e9fa6b8b047fb4e7b0cb2cd36aa53edeedfa37c99e05ab1c213a0fc2618f92a22b7edb3e0a014f8d49b48dbf4400728ba4bd4f73819bc048b8a59
+  metadata.gz: 2b742a5195cc53a0e5223b18eab5c18288fb87b8df7554c91cb7c55fd739f79d48dc18185688459fc9a422c333ebbc62ce5c1ae51d33a3d4e459e25d5348c8a6
+  data.tar.gz: 32d43a5bb2b7d2c9802ae12acd8212e6c6c3eaad7feffb2c2122775493071569bd077a5699218498bfd840aca15dd1c428f50e8d48ca102932c4bfe0f3af3cfa

data/CHANGELOG.md

@@ -5,6 +5,451 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.5] - 2026-08-20
+
+#### Fixed
+- **A rejected tool call put `"name": null` on the wire and killed the loop
+  permanently on strict servers.** When a model sends tool-call arguments that
+  are not valid JSON, SolidLoop answers with a "Tool call rejected" tool message
+  asking it to resend — correct, but that call never becomes a `ToolCall` row,
+  so the `tool_call_id -> function_name` lookup for the next request resolved to
+  `nil` and the tool message went out with a null `name`. vLLM ignored it;
+  llama.cpp rejects the whole request with `Failed to parse messages: type must
+  be string, but is null`, and because the offending message stays in history
+  the loop then fails on **every** retry rather than recovering. The lookup is
+  now seeded from the assistant message's `tool_calls_raw` (where the name is
+  still present) before the persisted rows override it, and `name` is omitted
+  rather than sent as null when it cannot be resolved at all.
+- **The `gemini` dialect read thought parts wrong, so on a thinking model the
+  reasoning and the answer swapped places.** `thought` on a Gemini part is a
+  *boolean flag* — the summary text sits in `text`, the same key an ordinary
+  answer uses. The dialect read `part["thought"]` as the reasoning (yielding
+  `true`) and then took the first part carrying a `text` as the answer, which on
+  a thinking response is the thought part. It also looked for `thoughtSignature`
+  on the candidate, where it never appears: signatures ride on a part — the
+  thought part, or the `functionCall` part on a tool-calling turn — so no
+  signature was ever captured and `:gemini_signed` could not work. Outbound
+  parts were built in the same wrong shape (`{ thought: "<text>" }`). The test
+  emulator encoded the same misreading, which is why the suite stayed green.
+  Verified against `ruby_llm`'s Gemini protocol, which handles all four cases.
+
+#### Changed
+- **Reasoning from earlier turns now goes back in each provider's own field
+  instead of being welded into `content`.** `reasoning_strategies` defaulted to
+  `[:xml]` for every dialect, which prepends `<think>…</think>` to the assistant
+  message body — the shape no provider can strip, and the shape every provider
+  bills. Because it lives in the body it is re-sent and re-charged on every
+  subsequent turn and compounds over a run; a long agent loop can end up
+  spending a large fraction of its context window on repacked reasoning, and
+  hit the window ceiling because of it.
+
+  Measured with vLLM's `/tokenize` on the Qwen3 chat template, one six-message
+  conversation cost **1438** prompt tokens welded, **108** in
+  `reasoning_content`, and **108** with the reasoning omitted entirely — the
+  template drops the field from history, as Qwen3's own guidance asks. The
+  equality is the point: welding is not a different encoding of the same
+  request, it re-shows the model its own past thoughts as ordinary text, and on
+  this template it costs ~13x the tokens to do something the model's authors
+  advise against.
+
+  `SolidLoop::Base#reasoning_strategies` now defaults to `nil`, meaning "ask the
+  dialect", and each dialect answers with the shape its provider actually has a
+  slot for:
+
+  | Dialect | Default | Wire shape |
+  | --- | --- | --- |
+  | `open_ai` | `["reasoning_content"]` | `reasoning_content` on the assistant message |
+  | `anthropic` | `[:anthropic_signed]` | `{ type: "thinking", thinking:, signature: }` block, first in `content` |
+  | `gemini` | `[:gemini_signed]` | `{ thought: true, text:, thoughtSignature: }` part |
+
+  The two signed shapes carry a provider-issued signature, which the dialects
+  now capture into `message.metadata["thought_signature"]` (`anthropic` did not
+  read it at all before). Both providers reject an unsigned block, so the signed
+  strategies are all-or-nothing: **messages written before this release have no
+  signature**, and a resumed older loop sends no reasoning for those turns
+  rather than a payload that would 400. Write `[:anthropic_signed, :xml]` to
+  keep the old welding as a fallback — `:xml` now fires exactly when a signed
+  strategy could not, instead of being suppressed by its mere presence.
+
+  **This changes the wire payload for hosts that never set
+  `reasoning_strategies` explicitly.** Restore the old behaviour with
+  `def reasoning_strategies = [:xml]`. A subclass that called `super` and
+  appended to the result must now handle `nil`. The token saving is specific to
+  templates that drop the field; re-run the comparison against a new model
+  before assuming it carries over.
+
+#### Added
+- **"Tools as typed output" is documented, with a supported way to end a loop
+  from the host.** Where tools are a typed output format rather than a
+  conversation — a batch turn of twenty atomic writes, one call per labelled
+  item, one per file in a codemod — the loop still schedules a further turn once
+  every call succeeds, and that turn is a paid request whose content is the word
+  "done". The README now shows a middleware that ends such a loop itself,
+  reaching a terminal state indistinguishable from a model-driven completion one
+  request sooner, and spells out the three details that are load-bearing:
+  placement before `NetworkCalling`, returning without calling downstream, and
+  keeping `expected_execution_token:`. No new API — it uses
+  `configure_llm_middlewares` and `Loop#transition_status`, both already public —
+  but the behaviour is now pinned by
+  `spec/integration/host_driven_completion_spec.rb` so it cannot break silently.
+  The section also says why raising `LimitExceededError` instead is a trap: it
+  ends in `paused`, which `resume!(from: %i[paused failed])` is documented to
+  pick back up.
+- **`docs/validation.md` — what SolidLoop has been run against, and what it has
+  not.** 0.0.5 was exercised under sustained agentic load on local inference
+  (llama.cpp with `--jinja` / `--kv-unified` and vLLM, Qwen3 27B, two consumer
+  GPUs) through the `open_ai` dialect; that surface is stricter than the hosted
+  API and is where the `"name": null` defect above was found. The page is equally
+  explicit about the gaps: the native `anthropic` and `gemini` dialects have
+  never made a live call, hosted providers were last exercised in 0.0.4 through
+  the `open_ai` dialect, and the durability design has not had a long production
+  soak. Reports from other providers and scales are welcome.
+- **The cost of carried reasoning is now a number on the message.** Each
+  assistant message's `metadata["reasoning_carried"]` records what that
+  request's prompt spent on earlier turns' reasoning — `messages`, `chars`,
+  `inline_chars` (the part welded into `content`, which every provider bills)
+  and `tokens_est`. Previously the only way to see it was to reconstruct it from
+  message lengths after the fact, which is why the 40% above went unnoticed.
+- **`Base#resume!` takes `from:` to narrow which statuses it will re-enter.**
+  It has always resumed `completed` loops as well as `init`/`paused`/`failed`,
+  which is right for continuing a finished conversation and wrong wherever a
+  loop has already reported a final result: the resumed turn appends to a run
+  that was over. Hosts had no way to say "restart what stalled, leave finished
+  runs alone" short of checking the status themselves before calling. The
+  default is unchanged (`SolidLoop::Loop::RESUMABLE_STATUSES`), and passing a
+  status resume can never reach (`running`, `queued`) raises `ArgumentError`
+  instead of no-opping forever.
+- **Automatic retry of transient LLM failures.** A 429 or 5xx from a hosted
+  provider killed the whole loop on first occurrence — including a shared-model
+  429 that carried `Retry-After: 30`, i.e. the provider's own instruction to
+  wait was discarded and the run failed instead. `Adapters::Native` now re-sends
+  such a response up to `SolidLoop.config.llm_retries` times (default 2) with
+  exponential backoff, honouring `Retry-After` (delta-seconds and HTTP-date)
+  over its own curve and capping any single wait at `llm_retry_max_delay`.
+  Configurable via `llm_retries`, `llm_retry_base_delay`, `llm_retry_max_delay`
+  and `llm_retry_statuses` (default `[408, 409, 429, 500, 502, 503, 504]`;
+  400/401/403/404/422 are never retried). Two boundaries are deliberate: a read
+  **timeout** is not retried (the full `read_timeout` already elapsed, the
+  request may have been served, and repeating it multiplies the turn's wall
+  clock), and a stream that has already handed a chunk to the caller is not
+  retried (the assistant shell holds partial content, so a re-send would
+  concatenate two generations — the latch is set where content is handed over,
+  not when bytes arrive, so a streamed *error body* stays retryable). Backoff
+  waits poll the cancellation check, so a pause/stop lands within a second
+  instead of after the full delay. Retries appear in the wire log; `ttft` and
+  `duration` describe the attempt that produced the answer.
+- **Retention for events and inbound MCP sessions.** `solid_loop_events` (one
+  row per LLM turn, tool call and inbound MCP request) and
+  `solid_loop_mcp_inbound_sessions` grew without bound, with no way to trim
+  them. `SolidLoop.prune!` (via the new `SolidLoop::JanitorJob`, on the existing
+  `solid_loop_maintenance` queue) now applies `event_retention` and
+  `mcp_inbound_session_retention`. **Off by default** — `nil` means keep
+  forever, because silently deleting a host's audit trail on upgrade would be
+  the wrong default. Deletes in batches of `janitor_batch_size` (default 1000)
+  so a sweep never takes one long lock on a table being written to; idempotent
+  and safe to run concurrently. Sessions are pruned by *creation* age rather
+  than last use, so a client that never terminates and never returns cannot pin
+  its row forever, and a doomed session's events go with it even when
+  `event_retention` is unset. `SolidLoop.last_pruned_at` mirrors
+  `last_reaped_at` as a liveness signal. Additive migration
+  `SolidLoopAddRetentionIndexes` adds the `created_at` indexes the sweep needs,
+  built `CONCURRENTLY` so it does not lock an append-only hot table.
+- **`Mcp::Toolset` answers `ping`.** The base protocol requires a prompt reply
+  with an empty result; the gem returned "method not found", which well-behaved
+  clients read as a dead server.
+- **`Mcp::Toolset.server_version`.** `initialize` reported
+  `serverInfo.version = SolidLoop::VERSION`, so every mounted server announced
+  the *gem's* version — semantically wrong (this is the version of the host's
+  MCP server) and a needless disclosure of an internal detail. Declared next to
+  `server_name`, inherited by subclasses, and still defaulting to
+  `SolidLoop::VERSION`.
+- **Dynamic tool and prompt catalogs.** The `tool` / `prompt` DSL registers at
+  class-load time, which is wrong for a host whose catalog lives in the database
+  and changes without a deploy — the only way out was to override `deliver` and
+  intercept `prompts/list` / `prompts/get`. Four overridable instance methods —
+  `available_tools`, `find_tool`, `available_prompts`, `find_prompt` — 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`.
+- **`SolidLoop::FrozenLoopError`.** `Base#resume!` on an admin-frozen loop
+  raised a bare `StandardError` carrying "Unfreeze in admin UI before resuming
+  this loop", forcing hosts to match on the message text to tell an expected
+  user-facing case (a 422) from a real fault — so rewording the message would
+  silently turn their 422 into a 500. Now typed; still a `StandardError`, so
+  existing rescues keep working.
+- **`SolidLoop::Base#reasoning_effort` — a first-class hook, translated per
+  dialect.** Passing effort through `llm_params` only ever worked on the OpenAI
+  dialect, because the Anthropic and Gemini dialects rebuild the payload from
+  scratch in `render_payload` and drop keys they do not know. The hook now sets a
+  canonical `reasoning_effort` on the payload (mirroring how `max_tokens` works)
+  and each dialect renders its own shape: OpenAI keeps the top-level
+  `reasoning_effort`, Anthropic emits `output_config: { effort: ... }`, and
+  Gemini emits `generationConfig.thinkingConfig.thinkingLevel` upper-cased.
+  Defaults to `nil`, sending nothing. The level vocabulary differs by provider
+  (OpenAI-compatible: minimal/low/medium/high; Anthropic adds xhigh and max;
+  Gemini: LOW/MEDIUM/HIGH), so the value is passed through rather than validated
+  — the provider is the authority on its own vocabulary. Note Gemini 2.5 takes a
+  numeric `thinkingBudget` instead, which this hook does not emit.
+- **`SolidLoop::Base#llm_params` — host-supplied LLM payload keys.** The built
+  payload (`model`, `messages`, `stream`, `tools`) was closed, so a host could
+  not send anything the gem does not model itself. An agent may now return a
+  hash that `MessageBuilding#build_payload` deep-merges over the payload as its
+  last step — `reasoning_effort`, `temperature`, `top_p`, `max_tokens`, or any
+  provider extension. Merged last, so a host can also override a gem-set key
+  (e.g. force `stream: false` for one agent). String keys are symbolized so they
+  cannot produce a duplicate entry alongside a gem-set key. Defaults to `{}`,
+  leaving the payload byte-identical for agents that do not override it. Keys
+  reach the wire verbatim under the OpenAI dialect; the Anthropic and Gemini
+  dialects re-render the payload, so only keys those dialects read survive.
+
+#### Changed
+- **The `Mcp::Toolset` envelope builders are public API.** Overriding `deliver`
+  is the documented extension seam ("the toolset IS the transport"), yet the
+  helpers an override needs to answer a request — `success_envelope`,
+  `error_envelope`, `json_boundary`, `tool_result` — were private, so every
+  override either reached through `send` or depended on private methods a patch
+  release could rename. They are now public and covered by the compatibility
+  promise.
+- **Admin list pages show latency, liveness and wire outcome.** Every list page
+  persisted the numbers that make a run diagnosable and then declined to display
+  them, so the admin could say *that* something happened but never *how long it
+  took* or *whether it worked* — a 608-second LLM read timeout had to be found by
+  querying the database by hand. Concretely:
+  - **Tool Calls** gains a DURATION column (`duration` was already persisted) and
+    a LOOP column linked like the Events page, so a 0.24s `solve_task` and a 40s
+    `fetch_url` are distinguishable and rows can be grouped by run without
+    opening each one. Slow calls are colour-flagged rather than left as a number
+    to be read. The FUNCTION filter was a free-text box the reader had to spell
+    from memory; it is now a select built from the discovered MCP tools (which is
+    the small, bounded side of that lookup — `DISTINCT function_name` over the
+    ever-growing tool_calls table is not), and a filter naming a tool no longer
+    advertised stays selectable instead of being silently reset to "All".
+  - **Events** gains STATUS and DURATION. There is no status column in the
+    schema — the outcome is buried in `response_data`, whose shape depends on
+    which middleware wrote it — so it is now derived once: a persisted
+    `http_status`, a transport/exception `error`, an MCP `isError` result (2xx
+    but the tool failed, flagged amber rather than red), or an implied 200. An
+    event with nothing recorded reads as "—", never as a success. Duration
+    thresholds are per-family: a minute-long local LLM completion is normal, a
+    minute-long MCP call is pathological, and one absolute threshold would have
+    painted the page red and hidden the outliers again. Event badges were all
+    the same blue; the LLM and MCP families now differ, and the MCP lifecycle
+    chatter (`mcp_initialize` / `mcp_list_tools`) recedes into a quiet outline.
+  - **Loops** gains WORK (`Loop#work_duration` — generation + tools, what
+    `max_duration` budgets against), TOKENS (`tokens_total`) and LAST ACTIVITY.
+    A loop that has worked 90 minutes used to look identical to one that was
+    created 90 minutes ago and is hung. Last activity is derived from the loop's
+    `updated_at`: the row is written at every turn commit AND by every lease
+    renewal (`LeaseRenewer` sets `updated_at` explicitly), so it advances *during*
+    a long generation, whereas messages are only written at turn boundaries and
+    streaming appends use `update_columns`, which skips timestamps — and it needs
+    no join. An active loop idle for minutes is flagged as likely stalled. COST
+    lost its column: under local inference it read $0.00 on every row, so it now
+    rides along under the token count and only when it is non-zero.
+  - **MCP Sessions** no longer spends half the table on a 48-character session
+    UUID: it is truncated head-and-tail with a copy-to-clipboard button carrying
+    the full value. The reclaimed width shows the owning loop (with its status)
+    and whether the session is still usable — a session is only ever reused while
+    its loop can still run, so a completed/failed loop's session is history —
+    plus how many tools discovery actually produced.
+  - **Messages** shows `tokens_total` with the in/out split beneath it instead of
+    the cryptic "P0+C0", falling back to the sum while a message is still
+    streaming and its total has not been written yet.
+
+  Associated data is fetched in bounded, narrow queries (one `pluck` per page for
+  the tool-call → loop mapping and the session → loop/tool counts) rather than
+  per row, and the Events and Messages lists now select only the columns they
+  render: `log` and `request_data` alone were tens of KB per event, so a 50-row
+  page was hauling megabytes of wire payload to draw a badge.
+- **Admin message cards are compact and legibly bordered.** The card body was
+  `white-space: pre-wrap`, so the ERB template's own indentation and blank lines
+  rendered as content — the first line of every message came out indented and
+  large gaps opened above the footer. Each block now owns its own `<pre>` and the
+  container does not preserve whitespace. `--sl-border-color` was darker than the
+  card it outlined and read as no edge at all; it is now lighter than the card
+  surface. Padding and gaps are tightened throughout, and reasoning is collapsed
+  behind a `<details>` toggle — it routinely runs to thousands of characters and
+  used to push the per-turn metrics off-screen.
+- **`max_duration` budgets accumulated WORK, not wall clock.** It was checked as
+  `loop.created_at <= max_duration.ago`, so every minute a loop spent paused,
+  failed, or waiting in a queue burned budget exactly like a minute of
+  generation. A loop paused overnight was dead on arrival the moment it resumed,
+  and one resumed after an outage could exhaust its budget having produced
+  nothing. It now checks `Loop#work_duration` — `duration_generation +
+  duration_tools`, both already accumulated on the success and failure paths —
+  which is derived rather than stored, so it cannot drift from its inputs. Work
+  lost to a hard kill is not counted, erring in the safe direction. Loops that
+  previously died on wall clock now get the budget they were meant to have;
+  hosts relying on `max_duration` as a hard wall-clock stop should add their own.
+- **`Pipeline::Builder` positional edits raise instead of guessing.**
+  `insert_before` silently inserted at the FRONT when the target was not found,
+  `insert_after` silently APPENDED, and `replace` silently appended — so a typo,
+  a renamed middleware, or a stale constant quietly rebuilt the pipeline instead
+  of failing. The damage lands far from the cause: a middleware moved ahead of
+  `AgentInitialization` sees an unpopulated context (`env.model_config` is nil),
+  and one moved past the terminal link may never run. All three now raise
+  `Pipeline::Builder::UnknownMiddleware`, whose message lists the stack in order
+  and points at stale class objects as a likely cause. `delete` stays lenient:
+  "this must not run" is unambiguous whether or not it is currently present.
+- **Anthropic dialect default `max_tokens`: 8096 → 64000** (now the named
+  `Dialects::Anthropic::DEFAULT_MAX_TOKENS`). Anthropic *requires* `max_tokens`
+  on every request, so this dialect must supply one when the agent does not —
+  unlike the OpenAI path, where an absent key lets the provider decide. The old
+  value was an unexplained magic number (apparently a typo for 8192) an order of
+  magnitude below the recommended default for streaming requests, which is what
+  SolidLoop does by default; current Claude models accept up to 128k output
+  tokens. A low cap truncates a turn mid-`tool_use`, costing a whole agent step
+  rather than a sentence. Agents that set `Base#max_tokens` are unaffected;
+  agents relying on the default will see longer completions and correspondingly
+  larger bills — set `max_tokens` explicitly to keep a tighter ceiling.
+
+#### Fixed
+- **llama.cpp prompt tokens were undercounted by the entire cached prefix.**
+  `LlmUsageParser::Llama` read `timings["prompt_n"]` as the prompt, but that
+  field counts only the tokens the request had to PROCESS; the reused prefix is
+  reported separately as `cache_n`. The prompt is their sum. The error compounds
+  across an agent loop: in a 30-turn run the recorded prompt fell to ~500 tokens
+  while the real context was ~37k, and 127 of 169 recorded turns stored
+  `tokens_prompt_cached > tokens_prompt` — impossible if `prompt_n` were the
+  whole prompt. Any capacity planning done from these figures (context per task,
+  how many turns fit a KV budget) was off by roughly an order of magnitude.
+- **`tokens_prompt_cached` is clamped to the prompt at the persistence
+  boundary.** Cached tokens are a subset of the prompt; a provider reporting the
+  two on different bases could previously persist a cache figure larger than the
+  prompt it came from, so any derived hit rate exceeded 100%. Clamped in
+  `ResponseParsing` rather than in one parser, because the invariant belongs to
+  the row.
+- **`Message#tps` is now persisted for every dialect, not just llama.cpp.** Only
+  the llama parser reported a rate; the OpenAI, Anthropic and Gemini parsers
+  hardcoded `0.0`, so the column stayed zero and every SQL aggregate over it read
+  as "zero throughput" rather than "not measured" — silently, since 0.0 looks
+  like a number. `ResponseParsing` now derives the rate from the decode window
+  when the provider does not report one, and `Message#tps` prefers the persisted
+  column so a Ruby read and a SQL aggregate cannot disagree (it still derives for
+  rows written before this change). Derivation is guarded by
+  `Message::MIN_DECODE_WINDOW`: when a whole response arrives in one chunk the
+  decode window collapses toward zero and the naive quotient reached ~9200 tok/s
+  on real traffic, so such turns store 0.0 and are excluded from averages.
+- **`loop.error_message` is now redacted like the wire log.** `EventLogging`
+  ran its payloads through `redact_credentials` while `ErrorHandling` wrote the
+  raw exception message straight onto the loop. Harmless for header-auth
+  dialects, but the Gemini dialect carries the API key in the URL query
+  (`?key=…`) and a Faraday error message embeds the URL — so the key reached
+  `error_message`, the admin UI, and any host API surfacing it. The rules moved
+  to `SolidLoop::Redaction` and are now applied at every site that persists
+  error text (`ErrorHandling`, `ResponseParsing`, `LlmCompletionJob`,
+  `McpSessionInitializer`).
+- **The gem's dev-only rake task no longer leaks into host applications.**
+  `lib/tasks/coverage.rake` was auto-loaded into every host's Rake by
+  `Rails::Engine`. A host with its own `coverage:report` got both bodies
+  executed (Rake *merges* same-named tasks), and because a `namespace` block is
+  not a Ruby module, `GROUPS` and `CoverageReporter` were defined on `Object` —
+  colliding with the host's constants on every `rake`/`rails` invocation. Moved
+  to `tasks/coverage.rake` (loaded explicitly by the gem's own Rakefile, and
+  outside the packaged file list) with its constants under `SolidLoopDev`.
+- **README's OpenAI `base_url` example was wrong.** It showed
+  `https://api.openai.com/v1`, but `Dialects::OpenAi#completion_url` appends
+  `/v1/chat/completions` itself — following the README produced
+  `/v1/v1/chat/completions` and every request failed.
+- **`subject_resolver`'s documented example could not work, and its links were
+  unreadable.** The doc comment showed `main_app.user_path(...)`, but the
+  resolver is invoked plainly as `resolver.call(loop)` and never `instance_exec`'d
+  in a view, so `main_app` is not in its binding — the example is replaced with a
+  runnable one using `Rails.application.routes.url_helpers`, plus the two
+  properties a resolver must have: return nil for subjects it does not handle,
+  and never raise. The rendered link also carried no class, so it fell back to
+  the browser's default link blue, which is nearly unreadable on the dark admin
+  background (the muted colour on the wrapping element does not cascade into an
+  anchor).
+
+- **Admin dashboard: charts that told the truth badly.** Six defects, all in the
+  presentation layer, that together made the page harder to read than the raw
+  JSON behind it.
+
+  *Bar colour meant nothing.* `chartOptions.colors` carried three colours, and
+  Chartkick spreads a colour array across the BARS of a single-series chart, not
+  across series. So on LLM Calls 5 PM was blue, 6 PM green and 7 PM red — red,
+  the colour every other surface in this admin uses for failure, applied to an
+  hour purely because it was third in the list. Single-series charts now pin one
+  colour to the whole dataset and red is reserved for failure data.
+
+  *Time buckets were per-chart.* `date_trunc` only emits buckets that have rows,
+  so a quiet hour vanished from one panel and not from its neighbour: Tokens
+  showed 5/7/8 PM beside an LLM Calls showing 5–8 PM, and the two panels could
+  not be compared by eye at all. Every series is now zero-filled onto one
+  generated bucket list. That also surfaced a silent data bug: the window
+  `24.hours.ago` needs 25 hourly buckets, two of which format to the same label
+  ("9 PM"), and Chartkick keys a categorical series BY LABEL — the duplicate
+  collapsed and the current hour's bar was drawn on top of yesterday's, 24
+  columns from where it belonged. The window is now aligned down to a bucket
+  boundary: exactly 24/30/12 whole buckets, unique labels, and KPI totals that
+  equal the sum of the bars beneath them.
+
+  *Tokens was drawn sideways.* It was a horizontal `BarChart` between two
+  vertical `ColumnChart`s despite being the same value-per-time-bucket shape, it
+  printed raw six-figure counts on its axis ("111401"), and it carried a legend
+  for its one and only series. It is now a `ColumnChart` beside its siblings,
+  with compact axis ticks ("111.4k") and a tooltip that also gives the exact
+  count with thousands separators.
+
+  *Three panels were permanently $0.00.* Hosts running local inference
+  (llama.cpp) have no cost, so the Cost tile, the Cost line chart and Top Agents
+  by Cost were dead weight — the last with its axis helpfully scaled to $1
+  against three zero-length bars. When total cost for the window is zero those
+  panels are replaced by two that were never surfaced anywhere in the admin
+  despite the data being recorded all along: *Loops by status* (the first thing
+  an operator wants to know) and *Throughput* — average TPS and TTFT from
+  `solid_loop_messages.tps` / `.ttft`, the numbers that actually move when you
+  change model or hardware. Only rows that measured something are averaged, and
+  each metric reports its own sample count, because the two are not populated
+  together: `tps` comes from providers that report their own timings, `ttft`
+  only from the streaming path.
+
+  *There was no loading or empty state.* Until the XHR resolved the tiles read
+  "-" and four large boxes were blank — indistinguishable from a period with no
+  activity, and from a request that had failed. Loading, empty and error are now
+  three distinct, labelled states.
+
+  *And the KPI tiles never said what they counted.* "LLM CALLS 75" over what
+  window? The Hour/Day/Week toggle was invisible in the numbers it changed.
+  Every tile and panel now names its window, and the stats endpoint returns it.
+- **Middleware stacks are rebuilt on reload (`SolidLoop.reset_middlewares!`).**
+  `llm_middlewares` / `tool_middlewares` are memoized on the `SolidLoop` module,
+  which lives in `lib/` and is never reloaded, while the middleware classes live
+  in the engine's `app/` and ARE reloaded in development. The memo therefore
+  kept class objects from an earlier load, and since `Array#index` compares by
+  `==`, every positional `Builder` call against a current constant missed its
+  target. Combined with the silent fallback above this was invisible and
+  destructive: host middleware landed at position 0 and crashed on a nil
+  context, a host `to_prepare` that re-inserted on every reload accumulated
+  duplicate copies, and a tool middleware could stop running entirely — silently
+  dropping the data it was there to record. The Engine now resets the memo on
+  `to_prepare`, before host initializers re-apply their own customization.
+  Development-only in effect; production never reloads.
+- **The admin loop page showed a permanently-zero "Total Duration".** It read
+  `Loop#duration_total`, a column nothing has ever written (like `max_tokens`
+  above, a declared field with no producer). It now shows `work_duration`. The
+  vestigial column is left in place rather than dropped in a migration.
+- **`resume!` sweeps orphaned `processing` assistant shells**, mirroring the
+  cleanup `pause!` already did. A shell is born hidden + `processing` at the
+  start of a streaming turn; the graceful-error path only finalizes the shell
+  its own attempt created, and its token-fenced CAS no-ops once a resume has
+  rotated the generation — so a turn that died while (or just before) the loop
+  was resumed left its shell `processing` forever. Nothing else swept it: the
+  reaper only sweeps shells off paused/terminal loops. The shell stays hidden,
+  so this never affected the payload sent to the provider — it accumulated
+  phantom "in flight" rows in the admin UI and made `processing` stop meaning
+  "a turn is actually running".
+- **`max_tokens` reaches the provider, and only when you ask for it.**
+  `SolidLoop::Base#max_tokens` was a declared agent hook that nothing ever wrote
+  into the payload, so overriding it did nothing: the Anthropic dialect always
+  fell back to its own `8096` and the Gemini dialect dropped the key. It is now
+  written into the payload by `MessageBuilding#build_payload` — but only when
+  set. The default changed from `16 * 1024` to `nil`, meaning **no `max_tokens`
+  key is sent at all** unless an agent opts in, letting the provider apply its
+  own default rather than a silent gem-chosen cap. Agents that never overrode
+  the hook see byte-identical requests; agents that did now get the value they
+  asked for.
+
 ## [0.0.4] - 2026-07-16
 
 #### Fixed