mcp_logs 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1a15a9653e6f24c9989d2a82579dbb31f50a5d2f49e3b164cad181135a0eb3b7
+  data.tar.gz: f150b3e7c2bc5df9ecd58a883354ca4c5d77748757e40adadeb975114f18ab2f
+SHA512:
+  metadata.gz: caf9e8db40d29ba9deeec6a8f36125421d0034b7fa7fbce203ce9ab66d6b10a34981c82be56017b04468ff56c701d400ce50d3b5525630dab0a12767212bd33a
+  data.tar.gz: d87d082c24baf8257eb3c5e944373b0ed350fee4aa25687ab5f990652692cf99a85ffd1ce17e7710f51c8e6ac8b0e80a2fbb78dec7a9e0e02772f2a379e437d9

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,274 @@
+# McpLogs
+
+Mountable Rails engine that records every Model Context Protocol (MCP) request
+a Rails app serves, and renders the host's tool contract as documentation —
+live, from the server object itself.
+
+Every JSON-RPC request coming through an `MCP::Server` is logged as it starts
+and completed once it finishes, so long-running tool calls are visible while
+they run rather than only after they return. A docs page reads the server's
+tools, params and descriptions directly and pairs each one with how often it's
+actually been called.
+
+## Installation
+
+Add the gem, then run the installer:
+
+```ruby
+# Gemfile
+gem "mcp_logs"
+```
+
+```sh
+bundle install
+rails generate mcp_logs:install
+rails db:migrate
+```
+
+The generator writes `config/initializers/mcp_logs.rb`, mounts the engine at
+`/mcp_logs` in `config/routes.rb`, and copies the `mcp_logs_calls` migration
+into your app.
+
+### Then gate the pages — this step is not optional
+
+The generated initializer contains one line you must change:
+
+```ruby
+config.base_controller_class = "CHANGE_ME"
+```
+
+`mcp_logs` ships **no authentication of its own**. Its controllers descend from
+a controller of yours and inherit whatever that controller enforces. The three
+pages render every argument and every response your MCP server has recorded, so
+until you point this at a controller that requires a signed-in operator, those
+pages are as reachable as the rest of your app:
+
+```ruby
+config.base_controller_class = "Admin::BaseController"
+```
+
+There is no default, and `CHANGE_ME` raises on the first request to `/mcp_logs`,
+so an app cannot reach production having skipped this by accident. Set it to
+`"ActionController::Base"` only if you genuinely intend the log to be public.
+
+`mcp_logs` does not depend on the `mcp` gem — the host supplies it. Add
+`gem "mcp"` to your own Gemfile if you haven't already.
+
+## Wiring capture
+
+Two things need wiring: the server needs an `around_request` hook, and the
+controller that serves requests needs to hand the recorder the HTTP request.
+
+```ruby
+# wherever you build the server
+MCP::Server.new(..., configuration: MCP::Configuration.new(
+  around_request: McpLogs.around_request(server_name: "my-app")
+))
+
+# in the controller that serves it
+McpLogs.with_context(request) { server.handle_json(request.body.read) }
+```
+
+**Build a fresh `MCP::Server` per request.** In `mcp` 1.0.0, the data an
+`around_request` hook writes into during a call — tool name, tool arguments,
+error — is not per-request: it's `@instrumentation_data`, a plain instance
+variable on the `MCP::Server` object, reassigned to `{}` at the top of every
+`instrument_call`. If one server instance serves two concurrent requests,
+request B's reassignment can land while request A is still mid-handler, so
+A's later writes end up in B's hash instead of A's. `McpLogs::Recorder` has no
+way to detect or correct for a shared server — it only holds the reference
+it's handed and trusts it describes the request in progress. Memoizing or
+sharing a server across requests will silently cross-contaminate logged tool
+names, arguments and errors between them.
+
+### Two things `mcp` 1.0.0 does not let this gem see
+
+`notifications/cancelled` returns before `instrument_call` runs, so a cancelled
+request is never handed to `around_request` and records no row at all.
+
+Every notification the server does not handle records `rpc_method` as the
+literal `"unsupported_method"` rather than the method the client actually sent —
+the gem passes that string in place of the real one. So an `unsupported_method`
+row means "some notification this server has no handler for", not a client
+calling a method by that name.
+
+Neither is something the recorder can correct for; both are noted here so a row
+that looks wrong can be recognised as upstream behaviour.
+
+### Client identity
+
+`client_name` and `client_version` come from the `clientInfo` a client sends with
+`initialize`. Under stateless Streamable HTTP, where a fresh `MCP::Server` is built
+per request, that information lives only for the duration of the `initialize` call —
+so later calls record no client. Use `McpLogs.with_context(request, actor: ...)` to
+attach an identity of your own that survives every request.
+
+## Configuration
+
+`config/initializers/mcp_logs.rb`, generated by the installer:
+
+```ruby
+McpLogs.setup do |config|
+  # REQUIRED — the pages have no authentication except the controller you name
+  # here. See "Then gate the pages" above.
+  config.base_controller_class = "CHANGE_ME"
+
+  # Master switch. When false, nothing is recorded and calls run untouched.
+  # config.enabled = true
+
+  # A lambda returning your MCP::Server. Read by the docs page only.
+  # config.server = -> { Mcp::Registry.server }
+
+  # Group the docs page by tool name. Anything unlisted renders under "Ungrouped".
+  # config.tool_sections = { "Read" => %w[search_apps get_app], "Write" => %w[edit_app] }
+
+  # Payloads are filtered through Rails' filter_parameters, then this lambda,
+  # then capped at max_payload_bytes.
+  # config.record_payloads = true
+  # config.max_payload_bytes = 64_000
+  # config.payload_filter = ->(payload) { payload }
+
+  # Used by McpLogs::PurgeJob and `rake mcp_logs:purge`. Schedule one of them.
+  # config.retention_days = 30
+
+  # The same job settles rows stranded in "running". Set above your slowest tool.
+  # config.abandoned_after_hours = 24
+
+  # config.page_size = 50
+end
+```
+
+- **`enabled`** — master switch. When `false`, `McpLogs.around_request` calls
+  the handler straight through and nothing is written.
+- **`server`** — a lambda returning your `MCP::Server`. Only the docs page
+  calls it; capture never builds or touches a server.
+- **`base_controller_class`** — **required.** A String, constantized on first
+  autoload of the engine's `ApplicationController` (i.e. after your app's
+  initializers have run). The engine's controllers descend from it and inherit
+  its authentication; there is no default, and leaving it unset or unresolvable
+  raises `McpLogs::ConfigurationError` rather than serving the log ungated.
+- **`tool_sections`** — `{ "Section title" => ["tool_name", ...] }`. Tool
+  names, not classes, so the gem never references a host constant. Anything
+  not listed renders under "Ungrouped" on the docs page.
+- **`record_payloads`** — when `false`, `arguments` and `response` are never
+  stored, regardless of size.
+- **`max_payload_bytes`** — payloads larger than this (after filtering) are
+  replaced with a `{ "truncated" => true, "bytes" => ..., "preview" => ... }`
+  wrapper, and the corresponding `*_truncated` column is set.
+- **`payload_filter`** — a lambda run on every payload after Rails'
+  `filter_parameters`, before the size cap. Use it for redaction
+  `filter_parameters` doesn't already cover. It is also the way to stop storing
+  a payload you don't want kept — return `nil` and the column stays empty. The
+  usual candidate is the `tools/list` result: it is your entire contract,
+  byte-identical on every client reconnect, so it produces the largest rows in
+  the table carrying the least information. The lambda sees only the payload, so
+  match on its shape: `->(payload) { payload.key?("tools") ? nil : payload }`.
+- **`retention_days`** — how far back `McpLogs::Call.purge!`,
+  `McpLogs::PurgeJob` and `rake mcp_logs:purge` reach when called with no
+  explicit argument. Default 30.
+- **`abandoned_after_hours`** — how long a call may sit in `running` before
+  `McpLogs::Call.sweep_abandoned!` settles it. Default 24. See "Abandoned
+  calls" below; set it above your slowest tool call, so a genuinely long call
+  is never mistaken for a dead one.
+- **`page_size`** — rows per page on the calls index.
+
+## What gets recorded
+
+Each row in `mcp_logs_calls` is one JSON-RPC request:
+
+| Column | Notes |
+| --- | --- |
+| `server_name` | the `server_name:` passed to `McpLogs.around_request` |
+| `rpc_method` | the JSON-RPC method, e.g. `tools/call` |
+| `tool_name` | present for `tools/call` requests |
+| `arguments` | jsonb; filtered and size-capped |
+| `response` | jsonb; filtered and size-capped |
+| `status` | `running`, `ok`, or `error` |
+| `tool_error` | true when the tool returned `isError: true` — a successful JSON-RPC response carrying a tool-level failure, not a transport error |
+| `cancelled` | true when the request was cancelled |
+| `error_type` | exception class, or the gem's own error code |
+| `error_message` | capped at 2,000 bytes; not redacted, since exception messages routinely echo attribute values or an entire failing SQL statement |
+| `duration_ms` | wall time of the handler itself |
+| `client_name`, `client_version` | from the client's `initialize` `clientInfo` — see "Client identity" above |
+| `protocol_version`, `session_id` | from the `Mcp-Protocol-Version` / `Mcp-Session-Id` headers |
+| `actor`, `ip`, `user_agent` | from the request, or from `McpLogs.with_context`'s `actor:` option |
+| `arguments_truncated`, `response_truncated`, `error_message_truncated` | one flag per payload, set independently, so the detail page can say exactly which payload was capped |
+| `started_at`, `completed_at` | a row is inserted as `running` at start and updated at finish, so a long call is visible while it's in flight |
+
+Payloads are always run through Rails' `filter_parameters`, then
+`config.payload_filter`, then capped at `config.max_payload_bytes` before
+being stored.
+
+Every string column above is `varchar(255)` and truncated to match at capture
+time. `tool_name` in particular is not validated input — `mcp` 1.0.0 reads it
+from `params.name` and hands it to the hook *before* looking the tool up, so an
+unknown tool records whatever the client sent — and `session_id`,
+`protocol_version` and `user_agent` are raw request headers. The calls page's
+filter dropdowns are bounded for the same reason.
+
+## Pages
+
+Mounted at `/mcp_logs` (or wherever you routed it):
+
+- **Calls** (`/mcp_logs`) — paginated index of every logged call, filterable
+  by method, tool, status and session.
+- **Call detail** (`/mcp_logs/calls/:id`) — one call's full arguments,
+  response, error and timing.
+- **Docs** (`/mcp_logs/docs`) — the host's tool contract, read live from
+  `config.server`, grouped by `config.tool_sections`, with each tool's call
+  count linking back to the calls index.
+
+## Abandoned calls
+
+A row is inserted `running` when a request starts and updated when it finishes.
+If that update never lands — the container restarts mid-call for a deploy, or
+the log write itself fails — nothing retries it. Left alone, the row would claim
+to be running for the whole retention window, so an operator asking "what is the
+agent doing right now" gets a permanent false positive.
+
+`McpLogs::Call.sweep_abandoned!` settles those rows: anything still `running`
+past `config.abandoned_after_hours` becomes `status: "error"` with
+`error_type: "abandoned"` and an `error_message` saying no completion was ever
+recorded. `completed_at` and `duration_ms` stay `nil` — the sweep knows the call
+did not finish, not when it stopped.
+
+It runs as part of `McpLogs::PurgeJob` and `rake mcp_logs:purge` below, so
+scheduling either one covers both. Set `abandoned_after_hours` above your
+slowest tool call: until the sweep runs, a long call and a dead one are
+genuinely indistinguishable — the recorder cannot tell them apart, and neither
+can the page.
+
+## Retention
+
+Logged calls accumulate; nothing prunes them automatically. Two ways to run
+`McpLogs::Call.purge!(McpLogs.retention_days)` and
+`McpLogs::Call.sweep_abandoned!` on a schedule:
+
+```ruby
+McpLogs::PurgeJob.perform_later
+```
+
+```sh
+rake mcp_logs:purge
+```
+
+With `solid_queue`'s `config/recurring.yml`:
+
+```yaml
+mcp_logs_purge:
+  class: McpLogs::PurgeJob
+  schedule: every day at 3am
+```
+
+## Requirements
+
+- Ruby >= 3.3
+- Rails ~> 8.0
+- PostgreSQL (the `arguments`/`response` columns are `jsonb`)
+- An asset pipeline — Propshaft or `sprockets-rails`. The pages are styled by
+  the engine's own `mcp_logs.css`, and the engine ships
+  `app/assets/config/mcp_logs_manifest.js` declaring it, which is what Sprockets
+  needs to precompile an engine asset. Nothing to configure either way; without
+  a pipeline at all, the pages render unstyled.
+- The `mcp` gem, supplied by the host — `mcp_logs` only depends on `rails`
+  and `pagy`

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/app/assets/config/mcp_logs_manifest.js

@@ -0,0 +1 @@
+//= link mcp_logs.css

data/app/assets/stylesheets/mcp_logs.css

@@ -0,0 +1,138 @@
+/* mcp_logs — all styling for the engine's pages.
+   Plain CSS on purpose: a host's Tailwind build scans its own root and never
+   these files, so anything utility-class based would render unstyled. */
+
+:root {
+  color-scheme: light dark;
+
+  --mcpl-font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
+  --mcpl-font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+
+  --mcpl-bg: #f9fafb;
+  --mcpl-panel: #ffffff;
+  --mcpl-border: #e5e7eb;
+  --mcpl-text: #111827;
+  --mcpl-muted: #6b7280;
+  --mcpl-link: #2563eb;
+  --mcpl-nav-bg: #111827;
+  --mcpl-nav-text: #e5e7eb;
+  --mcpl-ok: #047857;
+  --mcpl-error: #b91c1c;
+  --mcpl-warn: #b45309;
+  --mcpl-running: #1d4ed8;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --mcpl-bg: #030712;
+    --mcpl-panel: #111827;
+    --mcpl-border: #1f2937;
+    --mcpl-text: #f3f4f6;
+    --mcpl-muted: #9ca3af;
+    --mcpl-link: #93c5fd;
+    --mcpl-nav-bg: #000000;
+    --mcpl-ok: #34d399;
+    --mcpl-error: #f87171;
+    --mcpl-warn: #fbbf24;
+    --mcpl-running: #93c5fd;
+  }
+}
+
+body.mcpl {
+  background: var(--mcpl-bg);
+  color: var(--mcpl-text);
+  font-family: var(--mcpl-font-sans);
+  font-size: 14px;
+  margin: 0;
+}
+
+.mcpl a { color: var(--mcpl-link); }
+
+.mcpl-nav {
+  background: var(--mcpl-nav-bg);
+  color: var(--mcpl-nav-text);
+  padding: 0.75rem 1.5rem;
+}
+.mcpl-nav-inner { align-items: center; display: flex; gap: 1.5rem; margin: 0 auto; max-width: 80rem; }
+.mcpl-nav strong { color: #fff; }
+.mcpl-nav a { color: var(--mcpl-nav-text); text-decoration: none; }
+.mcpl-nav a:hover, .mcpl-nav a[aria-current="page"] { color: #fff; text-decoration: underline; }
+
+.mcpl-main { margin: 0 auto; max-width: 80rem; padding: 1.5rem; }
+
+.mcpl-panel {
+  background: var(--mcpl-panel);
+  border: 1px solid var(--mcpl-border);
+  border-radius: 0.5rem;
+  margin-bottom: 1.5rem;
+}
+.mcpl-panel > h2 {
+  border-bottom: 1px solid var(--mcpl-border);
+  font-size: 0.75rem;
+  letter-spacing: 0.05em;
+  margin: 0;
+  padding: 0.75rem 1rem;
+  text-transform: uppercase;
+}
+.mcpl-panel-body { padding: 1rem; }
+
+.mcpl-table { border-collapse: collapse; width: 100%; }
+.mcpl-table th {
+  color: var(--mcpl-muted);
+  font-size: 0.75rem;
+  letter-spacing: 0.03em;
+  text-align: left;
+  text-transform: uppercase;
+}
+.mcpl-table th, .mcpl-table td {
+  border-bottom: 1px solid var(--mcpl-border);
+  padding: 0.5rem 1rem;
+  vertical-align: top;
+}
+.mcpl-table td.mcpl-mono, .mcpl-mono { font-family: var(--mcpl-font-mono); }
+
+.mcpl-muted { color: var(--mcpl-muted); }
+
+.mcpl-badge {
+  border-radius: 999px;
+  font-size: 0.75rem;
+  padding: 0.1rem 0.5rem;
+  border: 1px solid currentColor;
+}
+.mcpl-badge--ok { color: var(--mcpl-ok); }
+.mcpl-badge--error { color: var(--mcpl-error); }
+.mcpl-badge--warn { color: var(--mcpl-warn); }
+.mcpl-badge--running { color: var(--mcpl-running); }
+
+.mcpl-filters { align-items: flex-end; display: flex; flex-wrap: wrap; gap: 0.75rem; }
+.mcpl-filters label { color: var(--mcpl-muted); display: block; font-size: 0.75rem; }
+.mcpl-filters select, .mcpl-filters input {
+  background: var(--mcpl-panel);
+  border: 1px solid var(--mcpl-border);
+  border-radius: 0.25rem;
+  color: var(--mcpl-text);
+  padding: 0.25rem 0.5rem;
+}
+
+.mcpl-pagination { align-items: center; display: flex; gap: 1rem; justify-content: space-between; padding: 0.75rem 1rem; }
+
+.mcpl-json {
+  background: var(--mcpl-bg);
+  border: 1px solid var(--mcpl-border);
+  border-radius: 0.375rem;
+  font-family: var(--mcpl-font-mono);
+  font-size: 0.8125rem;
+  overflow-x: auto;
+  padding: 0.75rem;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.mcpl-meta { display: grid; gap: 0.5rem 1.5rem; grid-template-columns: repeat(auto-fit, minmax(14rem, 1fr)); }
+.mcpl-meta dt { color: var(--mcpl-muted); font-size: 0.75rem; }
+.mcpl-meta dd { font-family: var(--mcpl-font-mono); margin: 0 0 0.5rem; }
+
+.mcpl-tool { border-top: 1px solid var(--mcpl-border); padding-top: 1rem; }
+.mcpl-tool:first-child { border-top: 0; padding-top: 0; }
+.mcpl-tool h3 { font-family: var(--mcpl-font-mono); font-size: 1rem; margin: 0 0 0.25rem; }
+.mcpl-tool p { margin: 0 0 0.5rem; white-space: pre-line; }

data/app/controllers/mcp_logs/application_controller.rb

@@ -0,0 +1,12 @@
+module McpLogs
+  # Descends from whatever the host configured, so authentication, Current
+  # attributes and any other host-wide before_actions apply with no auth code in
+  # this gem. The constant is resolved when this file is first autoloaded, which
+  # is after the host's initializers have run.
+  #
+  # The layout is re-declared because the host's base controller almost certainly
+  # sets its own, and the engine's pages are styled by the engine's own CSS.
+  class ApplicationController < McpLogs.base_controller
+    layout "mcp_logs/application"
+  end
+end

data/app/controllers/mcp_logs/calls_controller.rb

@@ -0,0 +1,34 @@
+module McpLogs
+  class CallsController < ApplicationController
+    include Pagy::Method
+
+    def index
+      scope = Call.recent
+        .for_method(params[:method])
+        .for_tool(params[:tool])
+        .with_status(params[:status])
+        .for_session(params[:session])
+
+      @pagy, @calls = pagy(:offset, scope, limit: McpLogs.page_size)
+
+      # The filter dropdowns list what has actually been logged, so they can never
+      # offer a method or tool that would return an empty page.
+      @methods = filter_options(:rpc_method, params[:method])
+      @tools = filter_options(:tool_name, params[:tool])
+    end
+
+    def show
+      @call = Call.find(params[:id])
+    end
+
+    private
+
+    # Bounded by Call::FILTER_OPTIONS_LIMIT, with the active filter added back if
+    # the bound cut it — otherwise filtering by a tool past the cut would drop
+    # that tool out of the select, silently resetting it to "Any" on submit.
+    def filter_options(column, selected)
+      values = Call.filter_values(column)
+      selected.present? ? (values | [selected]).sort : values
+    end
+  end
+end

data/app/controllers/mcp_logs/docs_controller.rb

@@ -0,0 +1,9 @@
+module McpLogs
+  class DocsController < ApplicationController
+    def show
+      @server = McpLogs.server
+      @sections = Docs.sections(@server)
+      @counts = Call.tool_counts
+    end
+  end
+end

data/app/helpers/mcp_logs/calls_helper.rb

@@ -0,0 +1,27 @@
+module McpLogs
+  module CallsHelper
+    def mcpl_status_badge(call)
+      label = call.tool_error && call.status == "ok" ? "tool error" : call.status
+      modifier = call.tool_error && call.status == "ok" ? "warn" : call.status
+
+      tag.span(label, class: "mcpl-badge mcpl-badge--#{modifier}")
+    end
+
+    def mcpl_duration(call)
+      return "—" if call.duration_ms.nil?
+      return "#{call.duration_ms.round} ms" if call.duration_ms < 1000
+
+      "#{(call.duration_ms / 1000).round(2)} s"
+    end
+
+    def mcpl_value(value)
+      value.presence || tag.span("—", class: "mcpl-muted")
+    end
+
+    def mcpl_json(value)
+      return tag.p("None.", class: "mcpl-muted") if value.blank?
+
+      tag.pre(JSON.pretty_generate(value), class: "mcpl-json")
+    end
+  end
+end

data/app/jobs/mcp_logs/purge_job.rb

@@ -0,0 +1,14 @@
+module McpLogs
+  # Descends from ActiveJob::Base rather than the host's ApplicationJob: the gem
+  # has no business inheriting a host's retry policy or queue defaults.
+  class PurgeJob < ActiveJob::Base
+    # Retention alone never settles a row stranded in "running" — it stays that
+    # way until the day it is deleted. Both jobs of housekeeping run here so a
+    # host that schedules one thing gets both. Purge first: a stranded row past
+    # the retention window is deleted rather than swept.
+    def perform(retention_days = McpLogs.retention_days, abandoned_after_hours = McpLogs.abandoned_after_hours)
+      McpLogs::Call.purge!(retention_days)
+      McpLogs::Call.sweep_abandoned!(abandoned_after_hours)
+    end
+  end
+end

data/app/models/mcp_logs/application_record.rb

@@ -0,0 +1,5 @@
+module McpLogs
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/mcp_logs/call.rb

@@ -0,0 +1,70 @@
+module McpLogs
+  # One JSON-RPC request served by an MCP server. Inserted as "running" the
+  # moment the request starts, updated when it finishes — so a long tool call is
+  # visible while it runs rather than only after it returns.
+  class Call < ApplicationRecord
+    STATUSES = %w[running ok error].freeze
+
+    # error_type for a row whose finish never landed. Its own value rather than
+    # an exception class name, because no exception was raised here — the
+    # process that would have raised one is gone.
+    ABANDONED = "abandoned".freeze
+
+    ABANDONED_MESSAGE = "No completion was ever recorded for this call. Whatever was " \
+                        "serving it stopped first — a deploy, a crash, or a failed log " \
+                        "write — so its result and duration are unknown.".freeze
+
+    # How many distinct values a filter dropdown will offer. Bounded because
+    # tool_name is raw client input (see Recorder::STRING_LIMIT): the number of
+    # distinct values is capped by requests served, not by tools that exist, so
+    # an unbounded SELECT DISTINCT would let one looping client put an <option>
+    # per request on every render of the page opened to investigate it.
+    FILTER_OPTIONS_LIMIT = 200
+
+    validates :rpc_method, presence: true
+    validates :started_at, presence: true
+    validates :status, inclusion: { in: STATUSES }
+
+    scope :recent, -> { order(started_at: :desc, id: :desc) }
+
+    # Filters take request params straight from the controller, so a blank value
+    # means "no filter" rather than "match the empty string".
+    scope :for_method,  ->(value) { where(rpc_method: value) if value.present? }
+    scope :for_tool,    ->(value) { where(tool_name: value) if value.present? }
+    scope :with_status, ->(value) { where(status: value) if value.present? }
+    scope :for_session, ->(value) { where(session_id: value) if value.present? }
+
+    def self.filter_values(column)
+      where.not(column => nil).distinct.order(column).limit(FILTER_OPTIONS_LIMIT).pluck(column)
+    end
+
+    def self.tool_counts
+      where.not(tool_name: nil).group(:tool_name).count
+    end
+
+    def self.purge!(retention_days = McpLogs.retention_days)
+      where(started_at: ...retention_days.to_i.days.ago).delete_all
+    end
+
+    # A row is inserted "running" and updated when the request finishes. If that
+    # update never lands — the container restarted mid-call, or the write itself
+    # failed — nothing retries it, so the row would claim to be running for the
+    # entire retention window: a permanent false positive on the page an
+    # operator reads to answer "what is the agent doing right now", and an
+    # inflated count in tool_counts.
+    #
+    # completed_at and duration_ms stay nil on purpose. The sweep knows the call
+    # did not finish; it does not know when it stopped, and stamping "now" would
+    # invent a fact. Returns how many rows it settled.
+    def self.sweep_abandoned!(hours = McpLogs.abandoned_after_hours)
+      where(status: "running")
+        .where(started_at: ...hours.to_i.hours.ago)
+        .update_all(status: "error", error_type: ABANDONED, error_message: ABANDONED_MESSAGE,
+                    updated_at: Time.current)
+    end
+
+    def running? = status == "running"
+
+    def duration_seconds = duration_ms && duration_ms / 1000.0
+  end
+end