solid_loop 0.0.4 → 0.0.5

data/README.md

@@ -6,10 +6,16 @@ Each agent turn (LLM call or tool execution) is a discrete background job. State
 
 ## Installation
 
-Add to your Gemfile (GitHub-only for now — pin a release tag):
+Add to your Gemfile:
 
 ```ruby
-gem "solid_loop", github: "ruslan/solid_loop", tag: "v0.0.4"
+gem "solid_loop", "~> 0.0.5"
+```
+
+Or track the repository directly, pinned to a release tag:
+
+```ruby
+gem "solid_loop", github: "ruslan/solid_loop", tag: "v0.0.5"
 ```
 
 Then run:
@@ -50,7 +56,9 @@ class MyAgent < SolidLoop::Base
 
   def llm_provider
     {
-      base_url: "https://api.openai.com/v1",
+      # Origin ONLY — the dialect appends its own path (`/v1/chat/completions`
+      # for open_ai). A base_url ending in /v1 would produce /v1/v1/... .
+      base_url: "https://api.openai.com",
       api_token: ENV["OPENAI_API_KEY"],
       model: "gpt-4o",         # used in the JSON payload (all dialects)
       # llm_model_name: "...", # used for URL construction in the Gemini dialect
@@ -196,8 +204,103 @@ agent.pause!
 agent.resume!
 ```
 
+`resume!` re-enters `init`, `paused`, `failed` **and `completed`** loops, returning
+`false` for anything else. Resuming a `completed` loop is deliberate — continuing
+a finished conversation is a normal thing to do — but it is the wrong default
+wherever a loop has already reported a final result, because the resumed turn
+appends to it. Narrow it with `from:`:
+
+```ruby
+agent.resume!(from: %i[paused failed])   # restart what stalled, leave finished runs alone
+```
+
+Passing a status that can never be resumed (`running`, `queued`) raises
+`ArgumentError` rather than silently never matching. The full set is
+`SolidLoop::Loop::RESUMABLE_STATUSES`.
+
 Loop status lifecycle: `init` → `queued` → `running` → `completed` / `failed` / `paused`.
 
+### Tools as typed output
+
+Some workloads use tools as a *typed output format* rather than as a
+conversation. A batch job hands the model twenty skeleton records and it answers
+with one turn containing twenty atomic tool calls that write them; a labelling
+pass emits one call per item; a codemod emits one call per file.
+
+When every call in such a turn succeeds, the model has nothing left to say — but
+the loop schedules another turn anyway, and that turn is a paid request whose
+entire content is the word "done". Over a run of a few hundred batches that adds
+up to a few hundred requests bought for nothing.
+
+A loop is normally finished by the model, by returning a turn with no tool calls.
+An agent that already knows the work is done can finish its own loop instead,
+with a middleware and no further request:
+
+```ruby
+class CompleteOnFullySuccessfulToolTurn
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    last  = env.loop.messages.where(role: "assistant").order(id: :desc).first
+    calls = last&.tool_calls.to_a
+
+    if calls.any? && calls.all?(&:is_success)
+      env.loop.transition_status(
+        from: :running,
+        to: :completed,
+        expected_execution_token: env.execution_token,
+        execution_token: nil,
+        lease_expires_at: nil
+      )
+      return
+    end
+
+    @app.call(env)
+  end
+end
+
+class BatchSeedAgent < SolidLoop::Base
+  def configure_llm_middlewares(builder)
+    builder.insert_after(
+      SolidLoop::Middlewares::AgentInitialization,
+      CompleteOnFullySuccessfulToolTurn
+    )
+  end
+end
+```
+
+Three details are load-bearing:
+
+- **Insert after `AgentInitialization`**, before `NetworkCalling`. The assistant
+  shell message is created in `NetworkCalling`; a middleware placed after it
+  would strand that shell in `processing` with nothing left to finish it.
+- **Return without calling `@app.call(env)`.** Returning is what skips the
+  request. The status transition alone would not.
+- **Keep `expected_execution_token:`.** It is not decoration: without it a worker
+  whose generation was already rotated away could complete a loop a newer
+  generation now owns.
+
+The result is a terminal state indistinguishable from a model-driven completion
+— same `completed` status, `execution_token` and `lease_expires_at` cleared,
+blank `error_message`, no orphaned shell, nothing for the reaper — reached one
+request sooner. `step_count` counts only the turns that actually happened. This
+is covered by `spec/integration/host_driven_completion_spec.rb`.
+
+Two things worth keeping:
+
+**Do not stop the loop by raising instead.** Raising `LimitExceededError` (or
+setting `max_steps 1`) also ends the turn, but lands the loop in `paused` — which
+`resume!(from: %i[paused failed])`, the documented "restart what stalled" sweep,
+is *supposed* to pick up. Every finished batch would then re-enter and spend the
+request the recipe existed to save. `completed` is not in that sweep.
+
+**Test `is_success`, not merely "did every call answer".** An MCP error result is
+persisted with `is_success: false` and remains an ordinary tool response
+precisely so the model can see it and correct itself. Ending the loop on "all
+calls resolved" would cut that short.
+
 ## Admin UI
 
 SolidLoop ships with a mountable admin UI for inspecting loops, messages, tool calls, MCP sessions/tools, events, and a lightweight dashboard.
@@ -299,8 +402,153 @@ class MyAgent < SolidLoop::Base
 end
 ```
 
+### Customizing the middleware stack
+
+`configure_llm_middlewares` / `configure_tool_middlewares` receive a
+`Pipeline::Builder`. Positional edits (`insert_before`, `insert_after`,
+`replace`) raise `Pipeline::Builder::UnknownMiddleware` if the named middleware
+is not in the stack — placement is the point, so a missed target is an error
+rather than a guess. `delete` is lenient and no-ops when the target is absent.
+
+```ruby
+def configure_tool_middlewares(builder)
+  builder.insert_after(SolidLoop::ToolMiddlewares::ToolExecution, MyMiddleware)
+end
+```
+
+Order matters: anything inserted before `AgentInitialization` runs against an
+unpopulated context. The engine rebuilds the stacks on every reload, so a host
+`to_prepare` block that customizes them re-applies onto a fresh stack rather
+than accumulating duplicates.
+
+### Extra payload parameters
+
+SolidLoop builds a deliberately small payload — `model`, `messages`, `stream`,
+and `tools`. Anything else the provider accepts comes from the agent's
+`llm_params`, deep-merged over that payload as the last step before the dialect
+renders it:
+
+```ruby
+class MyAgent < SolidLoop::Base
+  def llm_params
+    { reasoning_effort: "low", temperature: 0.2, max_tokens: 8192 }
+  end
+end
+```
+
+Two knobs have first-class hooks because they need per-dialect translation:
+`reasoning_effort` and `max_tokens`.
+
+```ruby
+class MyAgent < SolidLoop::Base
+  def reasoning_effort = "low"   # nil (default) sends nothing
+end
+```
+
+| Dialect | Wire shape |
+|---------|------------|
+| `open_ai` | `reasoning_effort: "low"` |
+| `anthropic` | `output_config: { effort: "low" }` |
+| `gemini` | `generationConfig.thinkingConfig.thinkingLevel: "LOW"` |
+
+Accepted levels differ by provider, so SolidLoop passes the value through rather
+than validating it. Note that `llm_params` cannot substitute for this hook on
+the `anthropic` and `gemini` dialects: both rebuild the payload in
+`render_payload` and drop keys they do not recognize.
+
+`max_tokens` has its own hook (`SolidLoop::Base#max_tokens`) and defaults to
+`nil` — no cap is sent and the provider applies its own default. Override it to
+opt in, or set it through `llm_params` like any other key.
+
+Because the merge happens last, `llm_params` can also override a key the gem
+set. Under the `open_ai` dialect the keys reach the wire verbatim; the
+`anthropic` and `gemini` dialects re-render the payload, so only the keys those
+dialects read survive.
+
 The native `anthropic` and `gemini` dialects are still useful for non-streaming production use (background agents, batch jobs) where you control the provider directly without an extra hop.
 
+### Reasoning from earlier turns
+
+Most providers treat reasoning as output-only: they hand back a `<think>` block
+or a `reasoning_content` field, and the next request has to decide what to do
+with it. Drop it and the model forgets its own plan; send it back the wrong way
+and you pay for it on every turn from then on.
+
+`SolidLoop::Base#reasoning_strategies` picks the shape. It defaults to `nil`,
+which means "let the dialect choose":
+
+| 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 |
+
+```ruby
+class MyAgent < SolidLoop::Base
+  def reasoning_strategies
+    [ "reasoning_content" ]        # an explicit field
+    # [:xml]                       # weld into content — works anywhere
+    # [:xml!]                      # weld even alongside a native strategy
+    # [:gemini_signed]             # signed thought part
+    # [:anthropic_signed]          # signed thinking block
+    # []                           # send no reasoning back at all
+  end
+end
+```
+
+**`:xml` is not free.** It welds every past thought into the assistant message
+body, so it is billed as prompt tokens on every subsequent turn and compounds
+over the run. Measured on vLLM's `/tokenize` against the Qwen3 chat template,
+the same six-message conversation cost **1438** prompt tokens welded and **108**
+in `reasoning_content` — and 108 with the reasoning omitted entirely, because
+that template drops the field from history exactly as the model's own guidance
+asks ("historical model output should only include the final output part").
+
+Note what that equality means: the two options are not the same request with a
+different encoding. Welding puts the old thoughts in front of the model as
+ordinary text; the field, on this template, does not. So `:xml` buys re-showing
+the model its own past reasoning, and on Qwen3 it costs ~13x the tokens for
+something the model's authors advise against — and a long loop can end up
+spending a large fraction of its context window on it. Prefer the field where
+the provider has one; keep `:xml` where the provider strips it, or where you
+have measured that the model does better for having its old thoughts back.
+
+**The signed strategies need their signature.** Anthropic and Gemini both issue
+one alongside the reasoning and verify it when the reasoning comes back; the
+dialects capture it into `message.metadata["thought_signature"]`. A message
+without one — anything written before 0.0.5, or by a model that returns no
+signature — sends **no reasoning at all** rather than a shape the provider would
+reject. Pair with `:xml` (`[:anthropic_signed, :xml]`) if you would rather weld
+the unsigned ones into the body than lose them: the `:xml` fallback fires
+exactly when the signed strategy could not.
+
+Both signed shapes are built from the providers' published documentation and
+covered by unit tests, but neither has been exercised against a live key — see
+[docs/validation.md](docs/validation.md). On `anthropic` or `gemini`, set
+`reasoning_strategies` to `[:xml]` to keep the pre-0.0.5 behaviour while you
+evaluate.
+
+**Do not trim reasoning turn by turn.** It is the obvious idea and it is a trap:
+a sliding retained window rewrites the prompt in the *middle* every turn, so the
+prefix cache diverges at the message that just aged out and everything after it
+is prefilled again. Measured on llama.cpp (Qwen3.8-27B Q6_K, prefix caching on)
+over an 8-step agent chain — keeping the newest 2 turns' reasoning cost **1847
+ms** of prefill per turn against **910 ms** for the untrimmed history it was
+meant to be cheaper than, and 500 ms for sending none. Trimming is not the
+problem; *sliding* is. A stable rule (always all, or always none) keeps the
+prompt monotonically extending and the cache intact.
+
+So there are two honest positions: carry the reasoning and let the cache pay for
+it, or send none. When a run genuinely outgrows its window, the answer is
+compaction — summarise the old history once, keep a recent tail, resume
+extending — not a per-turn trim. codex and opencode both do exactly this, and
+SolidLoop does not have it yet.
+
+Whatever the strategy, the cost is recorded. Each assistant message's `metadata`
+carries a `reasoning_carried` entry describing what that request's prompt spent
+on earlier reasoning — `messages`, `chars`, `inline_chars` (the part welded into
+`content`) and `tokens_est`.
+
 ## Read Timeout
 
 `read_timeout` controls how long to wait for data from the LLM before aborting. It is set per-agent via `llm_provider` and defaults to 10 minutes.
@@ -366,7 +614,7 @@ SolidLoop routes its jobs onto three fixed queues. A host that runs a worker wit
 | --- | --- | --- |
 | `solid_loop_llm` | `LlmCompletionJob` (LLM turns) | loops never advance |
 | `solid_loop_tool` | `ToolExecutionJob` (tool calls) | tool phases never resolve |
-| `solid_loop_maintenance` | `ReaperJob` (recovery sweep) | **hard-kill recovery is lost** — dead turns/tools are never reclaimed, and reaper jobs accumulate unrun |
+| `solid_loop_maintenance` | `ReaperJob` (recovery sweep), `JanitorJob` (retention sweep) | **hard-kill recovery is lost** — dead turns/tools are never reclaimed, and maintenance jobs accumulate unrun |
 
 The `ReaperJob` queue name (`solid_loop_maintenance`) is a **permanent, stable contract**. For example, a GoodJob worker that allowlists queues must include all three:
 
@@ -386,9 +634,55 @@ SolidLoop.configure do |c|
   c.config.default_tool_timeout  = 600  # ceiling for an in-process/custom tool's lease (raise above your slowest such tool)
   c.config.lease_leak_grace      = 300  # grace (s) added on top of an agent's max_duration to form the renewer's leak ceiling — a leak-safety backstop; must be > 0
   c.config.default_max_duration  = 7200 # fallback max_duration (s) sizing the leak ceiling when a registration omits one (mirrors SolidLoop::Base#max_duration)
+
+  # Transient LLM failures (see below)
+  c.config.llm_retries           = 2    # re-sends on top of the first attempt; 0 disables
+  c.config.llm_retry_base_delay  = 1.0  # backoff base (s); delay for attempt N is base * 2**(N-1)
+  c.config.llm_retry_max_delay   = 60.0 # ceiling on any single wait, `Retry-After` included
+  c.config.llm_retry_statuses    = [408, 409, 429, 500, 502, 503, 504]
+
+  # Retention (see below) — nil means keep forever, which is the default
+  c.config.event_retention               = nil # e.g. 90.days
+  c.config.mcp_inbound_session_retention = nil # e.g. 30.days
+  c.config.janitor_batch_size            = 1000
 end
 ```
 
+### Transient provider failures
+
+A 429 or 5xx from a hosted provider is routine, and providers often say exactly how long to wait. The adapter re-sends such a response up to `llm_retries` times before the turn is allowed to fail, honouring the response's `Retry-After` (both delta-seconds and HTTP-date forms) over its own exponential backoff, capped by `llm_retry_max_delay`. Deterministic statuses — 400/401/403/404/422 — are never retried; repeating them only burns quota.
+
+Two boundaries are deliberate:
+
+- **A read timeout is not retried.** By the time it fires the full `read_timeout` has already elapsed and the request may well have been served; repeating it would multiply the turn's wall clock. Only a response with a retryable status, or a connection that never established (`Faraday::ConnectionFailed`), is re-sent.
+- **A stream that has already emitted is not retried.** Once a chunk reaches the caller the assistant message shell holds partial content, and re-sending would concatenate two generations. The latch is set at the point content is handed over, not merely when bytes arrive — so a streamed *error body* stays retryable.
+
+Backoff waits are cancellation-aware: a pause or stop issued during the wait is honoured within a second rather than after the full delay. Retries are recorded in the turn's wire log; `ttft` and `duration` describe the attempt that produced the answer.
+
+### Retention
+
+`solid_loop_events` (one row per LLM turn, tool call and inbound MCP request) and `solid_loop_mcp_inbound_sessions` grow without bound. Retention is **off by default** — silently deleting a host's audit trail on upgrade would be the wrong default — and is opted into per table:
+
+```ruby
+SolidLoop.configure do |c|
+  c.config.event_retention               = 90.days
+  c.config.mcp_inbound_session_retention = 30.days
+end
+```
+
+Install the recurrence like the reaper's; unlike the reaper this is a daily concern, not a per-minute one:
+
+```ruby
+config.good_job.cron = {
+  solid_loop_reaper:  { cron: "* * * * *",  class: "SolidLoop::ReaperJob" },
+  solid_loop_janitor: { cron: "17 4 * * *", class: "SolidLoop::JanitorJob" }
+}
+```
+
+`SolidLoop.prune!` deletes in batches of `janitor_batch_size` so a sweep never takes one long lock on a table being written to concurrently. It is 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; a doomed session's events are removed with it even when `event_retention` is unset, so no event is left pointing at a deleted session. `SolidLoop.last_pruned_at` is the liveness signal, mirroring `last_reaped_at` (**process-local**).
+
+The first sweep after enabling retention on an existing install may have years of backlog to clear and can run long — either let the recurring job chip away at it, or do the initial bulk delete out of band.
+
 The invariant `lease_margin > 0` guarantees `lease > read_timeout` (LLM) and `lease > tool timeout` (tools) per claim; the heartbeat then keeps a healthy LLM turn's lease alive for its full duration. The `default_read_timeout` knob is the **single coherent source** for BOTH the derived LLM lease and the HTTP client's fallback read timeout, so the two can never diverge.
 
 ### The LLM lease renewer (one shared background thread)
@@ -479,5 +773,12 @@ loop_record = TestAgent.start!(
 )
 ```
 
+### What it has actually run against
+
+The suite stubs every provider. For the other half of the picture — the models,
+inference servers and hardware SolidLoop has been exercised on before a release,
+and the paths that are still untested against a live key — see
+[docs/validation.md](docs/validation.md).
+
 ## License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -5,7 +5,8 @@ load "rails/tasks/engine.rake"
 
 require "bundler/gem_tasks"
 
-# Top-level alias so `rake coverage:report` works alongside `rake app:coverage:report`
-namespace :coverage do
-  task(:report, [:sort, :filter, :git]) { |t, args| Rake::Task["app:coverage:report"].invoke(*args.to_a) }
-end
+# Development-only tasks live OUTSIDE lib/tasks/ so `Rails::Engine` never loads
+# them into a host application's Rake (where same-named tasks merge and
+# top-level constants collide). They are the gem's own tooling and are not
+# packaged — see the gemspec's file list.
+Dir[File.expand_path("tasks/*.rake", __dir__)].sort.each { |f| load f }

data/app/controllers/solid_loop/application_controller.rb

@@ -2,6 +2,12 @@ module SolidLoop
   class ApplicationController < ActionController::Base
     layout "solid_loop/admin"
 
+    # `SolidLoop::ApplicationHelper` is picked up by Rails' name convention
+    # (ApplicationController -> ApplicationHelper); anything else has to be
+    # declared, because an isolated engine's `app/helpers` is not added to the
+    # host application's helpers path.
+    helper SolidLoop::MetricsHelper
+
     private
 
     def paginate(scope, per_page: 50)

data/app/controllers/solid_loop/dashboard_controller.rb

@@ -1,26 +1,40 @@
 module SolidLoop
   class DashboardController < ApplicationController
+    PERIODS = %w[hour day week].freeze
+
+    # Operational order: what is happening now first, what is done last.
+    LOOP_STATUS_ORDER = %w[running queued init paused completed failed].freeze
+
     def index
-      @period = params[:period] || "hour"
+      @period = normalize_period(params[:period])
+      @window_label = window_label(@period)
     end
 
     def stats
-      period = params[:period] || "hour"
+      period = normalize_period(params[:period])
 
       render json: {
         period: period,
-        llm_calls: llm_calls_by_period(period),
-        tool_calls: tool_calls_by_period(period),
-        cost: cost_by_period(period),
+        window_label: window_label(period),
+        buckets: buckets(period),
+        llm_calls: fill_buckets(llm_calls_by_period(period), period),
+        tool_calls: fill_buckets(tool_calls_by_period(period), period),
+        cost: fill_buckets(cost_by_period(period), period, default: 0.0),
         tokens: tokens_by_period(period),
         top_agents: top_agents_by_cost(period),
-        failed: failed_by_period(period),
+        failed: fill_buckets(failed_by_period(period), period),
+        loop_statuses: loop_statuses(period),
+        throughput: throughput(period),
         summary: summary_stats(period)
       }
     end
 
     private
 
+    def normalize_period(value)
+      PERIODS.include?(value) ? value : "hour"
+    end
+
     def sql_period(period)
       case period
       when "day" then "date_trunc('day', created_at)"
@@ -29,40 +43,125 @@ module SolidLoop
       end
     end
 
+    # Start of the reporting window, aligned DOWN to a bucket boundary.
+    #
+    # A raw `24.hours.ago` opens the window mid-bucket, which costs twice: the
+    # oldest column is a partial hour drawn next to whole ones, and the axis
+    # needs 25 hourly buckets to cover 24 hours — two of which format to the
+    # same label ("9 PM"). Chartkick keys its categorical series BY LABEL, so
+    # the duplicate silently collapsed and the current hour's bar was drawn on
+    # top of yesterday's, 24 columns to the left of where it belongs.
+    #
+    # Aligned, the window is exactly 24 / 30 / 12 whole buckets with unique
+    # labels, and the KPI totals equal the sum of the bars beneath them.
     def interval(period)
+      now = Time.current.utc
+
       case period
-      when "day" then 30.days.ago
-      when "week" then 12.weeks.ago
-      else 24.hours.ago
+      when "day" then bucket_floor("day", now) - 29.days
+      when "week" then bucket_floor("week", now) - 11.weeks
+      else bucket_floor("hour", now) - 23.hours
+      end
+    end
+
+    # Human name for the window `interval` opens, so every number on the page can
+    # say what it is counting instead of leaving the reader to guess.
+    def window_label(period)
+      case period
+      when "day" then "last 30 days"
+      when "week" then "last 12 weeks"
+      else "last 24 hours"
+      end
+    end
+
+    # --- Shared time axis -------------------------------------------------
+    #
+    # Every series is grouped with `date_trunc`, which only emits buckets that
+    # actually have rows. Charts drawn from those hashes therefore each get their
+    # OWN x-axis: Tokens would show 5PM/7PM/8PM while LLM Calls showed 5–9PM, and
+    # the two panels could not be compared by eye. We generate the full bucket
+    # list for the selected window once and left-join every series onto it, so a
+    # quiet hour renders as a visible zero and all panels share one axis.
+
+    def bucket_step(period)
+      case period
+      when "day" then 1.day
+      when "week" then 1.week
+      else 1.hour
+      end
+    end
+
+    def bucket_floor(period, time)
+      case period
+      when "day" then time.beginning_of_day
+      # Postgres `date_trunc('week', ...)` is ISO: weeks start Monday. Pin the
+      # Ruby side to Monday too rather than inheriting a host's
+      # `Date.beginning_of_week`, or generated keys would miss the data keys.
+      when "week" then time.beginning_of_week(:monday)
+      else time.beginning_of_hour
+      end
+    end
+
+    # Canonical string form of a bucket. Matches how Rails serializes the Time
+    # keys `group(date_trunc(...))` returns, so generated and queried buckets
+    # collide exactly ("2026-08-18T21:00:00.000Z") and the browser can parse it.
+    def bucket_key(value)
+      time = value.is_a?(String) ? Time.zone.parse(value) : value
+      time.to_time.getutc.iso8601(3)
+    end
+
+    def buckets(period)
+      @buckets ||= {}
+      @buckets[period] ||= begin
+        step = bucket_step(period)
+        cursor = bucket_floor(period, interval(period).utc)
+        last = bucket_floor(period, Time.current.utc)
+
+        keys = []
+        while cursor <= last
+          keys << bucket_key(cursor)
+          cursor += step
+        end
+        keys
       end
     end
 
+    def fill_buckets(hash, period, default: 0)
+      normalized = hash.each_with_object({}) do |(key, value), acc|
+        acc[bucket_key(key)] = value
+      end
+
+      buckets(period).index_with { |key| normalized.fetch(key, default) }
+    end
+
+    # --- Series -----------------------------------------------------------
+
     def llm_calls_by_period(period)
-      SolidLoop::Event.where(name: "llm_completion").where("created_at > ?", interval(period))
+      SolidLoop::Event.where(name: "llm_completion").where("created_at >= ?", interval(period))
                       .group(sql_period(period)).count
     end
 
     def tool_calls_by_period(period)
-      SolidLoop::Event.where(name: "mcp_tool_call").where("created_at > ?", interval(period))
+      SolidLoop::Event.where(name: "mcp_tool_call").where("created_at >= ?", interval(period))
                       .group(sql_period(period)).count
     end
 
     def cost_by_period(period)
-      SolidLoop::Loop.where("created_at > ?", interval(period))
+      SolidLoop::Loop.where("created_at >= ?", interval(period))
                      .group(sql_period(period)).sum(:cost)
+                     .transform_values(&:to_f)
     end
 
     def tokens_by_period(period)
-      # Simulating stacked token counts
-      loops = SolidLoop::Loop.where("created_at > ?", interval(period))
+      loops = SolidLoop::Loop.where("created_at >= ?", interval(period))
                              .group(sql_period(period))
                              .sum(:tokens_total)
-      # Not fully stacked without separate prompt/completion, but good enough for now
-      [{ name: "Tokens", data: loops }]
+
+      [ { name: "Tokens", data: fill_buckets(loops, period) } ]
     end
 
     def top_agents_by_cost(period)
-      SolidLoop::Loop.where("created_at > ?", interval(period))
+      SolidLoop::Loop.where("created_at >= ?", interval(period))
                      .group(:agent_class_name)
                      .order(Arel.sql("sum_cost DESC"))
                      .limit(5)
@@ -70,17 +169,63 @@ module SolidLoop
     end
 
     def failed_by_period(period)
-      SolidLoop::Loop.where(status: "failed").where("created_at > ?", interval(period))
+      SolidLoop::Loop.where(status: "failed").where("created_at >= ?", interval(period))
                      .group(sql_period(period)).count
     end
 
+    # Loop population by lifecycle state. Never surfaced anywhere in the admin
+    # before, yet it is the first question an operator asks ("is anything stuck
+    # running? is the queue draining?"). Always returns every status, including
+    # the ones at zero, so the shape of the row does not jump around between
+    # polls and an absent status reads as "none" rather than "not measured".
+    def loop_statuses(period)
+      counts = SolidLoop::Loop.where("created_at >= ?", interval(period)).group(:status).count
+      LOOP_STATUS_ORDER.index_with { |status| counts[status].to_i }
+    end
+
+    # Generation throughput: tokens per second and time to first token, the two
+    # numbers that actually differ when you swap a model or a GPU. Both are
+    # recorded per message (`tps`, `ttft`) and were never shown anywhere.
+    #
+    # Only rows that actually measured something are averaged — a `system`,
+    # `user` or `tool` message stores 0.0 for both, and folding those zeros into
+    # the mean would report a throughput no model ever achieved. Each metric
+    # carries its own sample count because they are not populated together:
+    # `tps` is now written for every dialect (the provider's own rate when it
+    # reports one, else derived at commit time — see Message.derive_tps), while
+    # `ttft` is only measured on the streaming path.
+    #
+    # The `NULLIF(tps, 0)` filter stays load-bearing. A zero means "the decode
+    # window was too short to measure", not "this turn achieved zero throughput",
+    # and folding those into the mean would understate the panel. The explosive
+    # case this once guarded against — a window collapsing toward zero and the
+    # quotient reaching the thousands — is now excluded at write time by
+    # Message::MIN_DECODE_WINDOW, so such a turn stores 0.0 and is skipped here.
+    def throughput(period)
+      scope = SolidLoop::Message.where("created_at >= ?", interval(period))
+
+      avg_tps, tps_samples, avg_ttft, ttft_samples = scope.pick(
+        Arel.sql("AVG(NULLIF(tps, 0))"),
+        Arel.sql("COUNT(*) FILTER (WHERE tps > 0)"),
+        Arel.sql("AVG(NULLIF(ttft, 0))"),
+        Arel.sql("COUNT(*) FILTER (WHERE ttft > 0)")
+      )
+
+      {
+        tps: avg_tps && avg_tps.to_f.round(2),
+        tps_samples: tps_samples.to_i,
+        ttft: avg_ttft && avg_ttft.to_f.round(3),
+        ttft_samples: ttft_samples.to_i
+      }
+    end
+
     def summary_stats(period)
       failed_counts = failed_split(period)
 
       {
-        llm_calls: SolidLoop::Event.where(name: "llm_completion").where("created_at > ?", interval(period)).count,
-        tool_calls: SolidLoop::Event.where(name: "mcp_tool_call").where("created_at > ?", interval(period)).count,
-        cost: SolidLoop::Loop.where("created_at > ?", interval(period)).sum(:cost).to_f.round(3),
+        llm_calls: SolidLoop::Event.where(name: "llm_completion").where("created_at >= ?", interval(period)).count,
+        tool_calls: SolidLoop::Event.where(name: "mcp_tool_call").where("created_at >= ?", interval(period)).count,
+        cost: SolidLoop::Loop.where("created_at >= ?", interval(period)).sum(:cost).to_f.round(3),
         failed: failed_counts[:agent] + failed_counts[:infra],
         failed_agent: failed_counts[:agent],
         failed_infra: failed_counts[:infra]
@@ -93,7 +238,7 @@ module SolidLoop
     def failed_split(period)
       messages = SolidLoop::Loop
                  .where(status: "failed")
-                 .where("created_at > ?", interval(period))
+                 .where("created_at >= ?", interval(period))
                  .pluck(:error_message)
 
       messages.each_with_object(agent: 0, infra: 0) do |msg, acc|

data/app/controllers/solid_loop/events_controller.rb

@@ -1,8 +1,16 @@
 module SolidLoop
   class EventsController < ApplicationController
+    # The list only needs enough of an event to say what it was, how long it
+    # took and whether it worked. `log` and `request_data` are the two fattest
+    # columns on the table (tens of KB per row for a streamed completion), so a
+    # 50-row page was hauling megabytes of payload to render a badge. Narrowed
+    # AFTER pagination: the paginator still counts on the unrestricted relation,
+    # where a multi-column select would turn `count` into COUNT(a, b, ...).
+    LIST_COLUMNS = %i[id name loop_id duration response_data created_at].freeze
+
     def index
       @pagination = paginate(SolidLoop::Admin::EventsQuery.new(params).call)
-      @events = @pagination[:records]
+      @events = @pagination[:records].select(*LIST_COLUMNS)
     end
 
     def show