opencode-plugboard 0.16.0 → 0.18.0

package/src/dashboard/assets.ts

@@ -0,0 +1,72 @@
+/**
+ * Serves the usage dashboard (`src/dashboard/page.ts`): the page, the page's own script and
+ * stylesheet, and uPlot's browser build and stylesheet from its npm package. Files are read on the
+ * first request and kept in memory. Setup does no filesystem work (I3). The bytes never change
+ * while plugboard runs, so the ETag is their hash and a revalidation answers 304.
+ */
+import { createHash } from "node:crypto"
+import { readFile } from "node:fs/promises"
+import type { IncomingMessage, ServerResponse } from "node:http"
+import { createRequire } from "node:module"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { sendText } from "../discovery.js"
+import { DASHBOARD_HEADERS, DASHBOARD_PAGE } from "./page.js"
+
+const PAGE_PREFIX = "GET /dashboard/"
+const here = dirname(fileURLToPath(import.meta.url))
+const resolveFrom = createRequire(import.meta.url)
+
+interface AssetFile {
+  readonly path: () => string
+  readonly contentType: string
+}
+
+/** The asset named by the last segment of `/dashboard/<name>`. */
+const ASSETS: Readonly<Record<string, AssetFile>> = {
+  "app.js": { path: () => join(here, "app.js"), contentType: "text/javascript; charset=utf-8" },
+  "app.css": { path: () => join(here, "app.css"), contentType: "text/css; charset=utf-8" },
+  "uplot.js": { path: () => resolveFrom.resolve("uplot/dist/uPlot.iife.min.js"), contentType: "text/javascript; charset=utf-8" },
+  "uplot.css": { path: () => resolveFrom.resolve("uplot/dist/uPlot.min.css"), contentType: "text/css; charset=utf-8" },
+}
+
+interface Asset {
+  readonly body: string
+  readonly contentType: string
+  readonly etag: string
+}
+
+const loaded = new Map<string, Promise<Asset>>()
+
+async function load(name: string): Promise<Asset> {
+  const file = ASSETS[name]
+  if (!file) throw new Error(`no dashboard asset ${name}`)
+  const body = await readFile(file.path(), "utf8")
+  const digest = createHash("sha256").update(body).digest("hex").slice(0, 32)
+  return { body, contentType: file.contentType, etag: `"${digest}"` }
+}
+
+/** The asset's bytes, read once per process. A failed read is not kept, so the next request tries again. */
+function asset(name: string): Promise<Asset> {
+  let pending = loaded.get(name)
+  if (!pending) {
+    pending = load(name)
+    loaded.set(name, pending)
+    pending.catch(() => loaded.delete(name))
+  }
+  return pending
+}
+
+/** Answers one dashboard route (`DASHBOARD_ROUTES`, already matched by the caller). */
+export async function serveDashboard(request: IncomingMessage, response: ServerResponse, route: string): Promise<void> {
+  if (route === "GET /dashboard") return sendText(response, 200, "text/html; charset=utf-8", DASHBOARD_PAGE, DASHBOARD_HEADERS)
+  const found = await asset(route.slice(PAGE_PREFIX.length))
+  // Assets revalidate on every use: a plugboard upgrade changes them, and the ETag makes that check free.
+  const headers = { ...DASHBOARD_HEADERS, "cache-control": "no-cache", etag: found.etag }
+  if (request.headers["if-none-match"] === found.etag) {
+    if (!response.headersSent && !response.destroyed) response.writeHead(304, headers)
+    response.end()
+    return
+  }
+  return sendText(response, 200, found.contentType, found.body, headers)
+}

package/src/dashboard/page.ts

@@ -0,0 +1,87 @@
+/**
+ * The usage dashboard page (`GET /dashboard`, #141): static HTML, its headers and the routes that
+ * serve it. The page holds no data. It asks for a key, then reads `GET /v1/usage` from the same
+ * origin with that key (the data never reaches the page's HTML). No inline script or style: the
+ * script and stylesheets are plugboard's own files under `/dashboard/`, served by `src/dashboard/assets.ts`.
+ */
+
+/** Scripts and styles from this origin only; nothing else may load, frame or submit. */
+export const DASHBOARD_CSP = "default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self' data:; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
+
+/** Headers of every dashboard response; the assets get them too. */
+export const DASHBOARD_HEADERS: Readonly<Record<string, string>> = {
+  "content-security-policy": DASHBOARD_CSP,
+  "x-frame-options": "DENY",
+  "referrer-policy": "no-referrer",
+}
+
+/** Routes of the dashboard: the page and its four files. Served only when option `usage` is on. */
+export const DASHBOARD_ROUTES: ReadonlySet<string> = new Set([
+  "GET /dashboard",
+  "GET /dashboard/app.js",
+  "GET /dashboard/app.css",
+  "GET /dashboard/uplot.js",
+  "GET /dashboard/uplot.css",
+])
+
+export const DASHBOARD_PAGE = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="referrer" content="no-referrer">
+<title>plugboard usage</title>
+<link rel="stylesheet" href="/dashboard/uplot.css">
+<link rel="stylesheet" href="/dashboard/app.css">
+<script src="/dashboard/uplot.js" defer></script>
+<script src="/dashboard/app.js" defer></script>
+</head>
+<body>
+<header class="top">
+<h1>plugboard usage</h1>
+<p class="muted">Requests, tokens and estimated cost per app, per UTC day. Cost uses the catalog's list prices.</p>
+</header>
+<main>
+<section id="signin" class="card" hidden>
+<form id="key-form">
+<label for="key">API key</label>
+<div class="row">
+<input id="key" name="key" type="password" autocomplete="off" autocapitalize="off" spellcheck="false">
+<button type="submit" class="primary">Show usage</button>
+</div>
+<p class="muted">The admin key shows every app. An app key shows only its own. The key is kept in this tab's session storage and sent only to this server.</p>
+</form>
+<p id="auth-error" class="error" role="alert" hidden></p>
+</section>
+<section id="panel" hidden>
+<div class="toolbar">
+<div class="ranges" role="group" aria-label="Range">
+<button type="button" data-days="1">Today</button>
+<button type="button" data-days="7">7 days</button>
+<button type="button" data-days="30">30 days</button>
+<button type="button" data-days="90">90 days</button>
+</div>
+<div class="row">
+<button type="button" id="refresh">Refresh</button>
+<button type="button" id="sign-out">Sign out</button>
+</div>
+</div>
+<p id="status" class="muted" aria-live="polite"></p>
+<h2>Totals</h2>
+<div id="totals" class="cards"></div>
+<h2>Apps</h2>
+<div class="scroll"><table id="apps"></table></div>
+<h2>Requests per day</h2>
+<div id="chart-requests" class="chart"></div>
+<h2>Estimated cost per day (USD)</h2>
+<div id="chart-cost" class="chart"></div>
+<h2>Tokens per day</h2>
+<div id="chart-tokens" class="chart"></div>
+<h2>Models</h2>
+<p id="models-note" class="muted"></p>
+<div class="scroll"><table id="models"></table></div>
+</section>
+</main>
+</body>
+</html>
+`

package/src/discovery.ts

@@ -61,7 +61,7 @@ export interface Endpoint {
 /**
  * Every endpoint plugboard serves, in the order the document lists them. Dispatch lives in
  * `src/openai/route.ts` and the front-end routes; `test/http/discovery.test.ts` probes each served
- * route and fails when this list omits one (#136). `/metrics` is added only when option `metrics` is on.
+ * route and fails when this list omits one (#136). `/v1/usage`, `/dashboard` and `/metrics` are added only when their options are on.
  */
 export const ENDPOINTS: ReadonlyArray<Endpoint> = [
   { method: "GET", path: "/", auth: false, description: "This page." },
@@ -73,15 +73,26 @@ export const ENDPOINTS: ReadonlyArray<Endpoint> = [
   { method: "POST", path: "/v1/completions", auth: true, description: "Legacy OpenAI completions." },
   { method: "POST", path: "/v1/responses", auth: true, description: "OpenAI Responses (stateless)." },
   { method: "POST", path: "/v1/messages", auth: true, description: "Anthropic Messages (x-api-key or Bearer)." },
+  { method: "POST", path: "/v1/messages/count_tokens", auth: true, description: "Anthropic token count (an estimate, not the provider's exact count)." },
   { method: "GET", path: "/v1beta/models", auth: true, description: "Gemini model list." },
   { method: "GET", path: "/v1beta/models/{model}", auth: true, description: "One Gemini model." },
   { method: "POST", path: "/v1beta/models/{model}:generateContent", auth: true, description: "Gemini generateContent." },
   { method: "POST", path: "/v1beta/models/{model}:streamGenerateContent", auth: true, description: "Gemini streamGenerateContent, with ?alt=sse." },
+  { method: "POST", path: "/v1beta/models/{model}:countTokens", auth: true, description: "Gemini token count (an estimate)." },
   { method: "GET", path: "/v1/status", auth: true, description: "Runtime status: generations, address, model count, uptime." },
 ]
 
 function endpoints(options: PlugboardOptions): ReadonlyArray<Endpoint> {
-  return options.metrics ? [...ENDPOINTS, { method: "GET", path: "/metrics", auth: true, description: "Prometheus metrics." }] : ENDPOINTS
+  return [
+    ...ENDPOINTS,
+    ...(options.usage.enabled
+      ? [
+          { method: "GET", path: "/v1/usage", auth: true, description: "Per-app usage by day: requests, tokens, cost, latency. The admin key reads every app." },
+          { method: "GET", path: "/dashboard", auth: false, description: "Usage dashboard page. Its data needs a key (`/v1/usage`)." },
+        ]
+      : []),
+    ...(options.metrics ? [{ method: "GET", path: "/metrics", auth: true, description: "Prometheus metrics." }] : []),
+  ]
 }
 
 type ModelsState = "ready" | "no_models_configured" | "none_available" | "catalog_unavailable"
@@ -232,6 +243,7 @@ export function renderDiscoveryHtml(doc: Discovery): string {
     const more = doc.catalog.moreProviders ? `<p>${escapeHtml(doc.catalog.moreProviders)} more providers not listed.</p>` : ""
     sections.push(`<h2>Catalog</h2><table><tr><th>Provider</th><th>Models</th><th>Examples</th></tr>${rows}</table>${more}`)
   }
+  if (doc.endpoints.some((endpoint) => endpoint.path === "/dashboard")) sections.push(`<p><a href="/dashboard">Usage dashboard</a></p>`)
   sections.push(`<h2>Try it</h2>${pre(doc.example.curl)}`)
   sections.push(
     `<h2>Endpoints</h2><table><tr><th>Method</th><th>Path</th><th>Key</th><th></th></tr>${doc.endpoints

package/src/gemini/route.ts

@@ -1,6 +1,6 @@
 /**
  * The Gemini front-end's half of the route: `GET /v1beta/models`, `GET /v1beta/models/{model}`,
- * `POST /v1beta/models/{model}:generateContent` and `:streamGenerateContent?alt=sse` (and the
+ * `POST /v1beta/models/{model}:generateContent`, `:streamGenerateContent?alt=sse` and `:countTokens` (an estimate, #144) (and the
  * `POST /v1/models/{model}:...` spelling). `src/openai/route.ts` matches the path
  * (`matchGeminiRoute`), checks the origin, authenticates (`geminiAuthorization` supplies the
  * credential) and hands over here; errors on these routes use Google's body (`encodeGeminiError`).
@@ -23,6 +23,7 @@ import { reportCache } from "../cache.js"
 import { reportPolicy } from "../policy.js"
 import type { RouteHost } from "../openai/route.js"
 import { dropRejected } from "../openai/sampling.js"
+import { estimateTokens } from "../anthropic/tokens.js"
 import { parseGeminiRequest } from "./request.js"
 import { encodeGeminiError, encodeGeminiModel, encodeGeminiModelList, runGenerate, sseChunk } from "./response.js"
 
@@ -33,9 +34,14 @@ export type GeminiMatch =
   | { readonly op: "list"; readonly route: string }
   | { readonly op: "get"; readonly route: string; readonly model: string }
   | { readonly op: "generate"; readonly route: string; readonly model: string; readonly stream: boolean }
+  | { readonly op: "count"; readonly route: string; readonly model: string }
   /** A method on a model that plugboard does not serve (`countTokens`, `embedContent`, ...). */
   | { readonly op: "unsupported"; readonly route: string; readonly verb: string }
 
+/** `countTokens` takes the request's contents at the top level, or wrapped as `generateContentRequest`. */
+const countBody = (body: unknown): unknown =>
+  typeof body === "object" && body !== null && "generateContentRequest" in body ? (body as { generateContentRequest: unknown }).generateContentRequest : body
+
 const decode = (raw: string): string | undefined => {
   try {
     return decodeURIComponent(raw)
@@ -66,6 +72,7 @@ export function matchGeminiRoute(method: string | undefined, path: string): Gemi
     if (!/^[A-Za-z]+$/.test(verb) || model === undefined) return undefined
     if (verb === "generateContent" || verb === "streamGenerateContent")
       return { op: "generate", route: `POST ${prefix.slice(0, -1)}/{model}:${verb}`, model: model.startsWith("models/") ? model.slice(7) : model, stream: verb === "streamGenerateContent" }
+    if (verb === "countTokens") return { op: "count", route: `POST ${prefix.slice(0, -1)}/{model}:countTokens`, model: model.startsWith("models/") ? model.slice(7) : model }
     // The client's verb never becomes a metric or log label: every other verb is `unknown` (#135).
     return { op: "unsupported", route: "unknown", verb }
   }
@@ -98,7 +105,20 @@ export async function serveGemini(host: RouteHost, { match, request, url, app, r
   const fail = (error: PlugError) => sendError(response, error, encodeGeminiError(error))
 
   if (match.op === "unsupported")
-    return fail({ status: 404, kind: "not_found", code: "method_not_supported", message: `Method ${match.verb} is not supported; plugboard serves generateContent and streamGenerateContent` })
+    return fail({ status: 404, kind: "not_found", code: "method_not_supported", message: `Method ${match.verb} is not supported; plugboard serves generateContent, streamGenerateContent and countTokens` })
+
+  if (match.op === "count") {
+    const unsupported = checkJsonContentType(request)
+    if (unsupported) return fail(unsupported)
+    const parsed = parseGeminiRequest(match.model, false, countBody(await readJsonBody(request, scope.signal)), host.options)
+    if (isPlugError(parsed)) return fail(parsed)
+    const catalog = await scope.race(host.loadCatalog())
+    const ref = resolveModel(host.options, match.model, catalog, parsed.reasoningEffort)
+    if (isPlugError(ref)) return fail(ref)
+    info.model = `${ref.providerID}/${ref.id}${ref.variant ? `#${ref.variant}` : ""}`
+    // An estimate, not the provider's count (see src/anthropic/tokens.ts).
+    return sendJson(response, 200, { totalTokens: estimateTokens(parsed.request) })
+  }
 
   if (match.op === "list" || match.op === "get") {
     const listed = listAvailableModels(host.options, await scope.race(host.loadCatalog()), app)

package/src/openai/route.ts

@@ -3,7 +3,8 @@
  * `POST /v1/chat/completions` (`n` > 1 through `./fanout.ts`), and the dispatch of `POST /v1/responses`
  * and `POST /v1/completions` to `src/responses/route.ts` and `src/completions/route.ts`.
  * Observability and first-run routes (`src/discovery.ts`, `src/metrics.ts`): `GET /` and `GET /v1`
- * (keyless discovery), the authenticated `GET /v1/status`, and `GET /metrics` (option `metrics`).
+ * (keyless discovery), the authenticated `GET /v1/status`, `GET /metrics` (option `metrics`), and the
+ * usage dashboard `GET /dashboard` with its assets (option `usage`, `src/dashboard/`).
  *
  * The flow is: establish cancellation and the deadline, check origin, authenticate, parse, resolve
  * the model, call the ModelCaller, encode. Parsing, policy and encoding are imported directly;
@@ -20,7 +21,7 @@
  */
 
 import type { IncomingMessage, ServerResponse } from "node:http"
-import { DEFAULT_APP, authenticate, type PlugboardOptions } from "../config.js"
+import { DEFAULT_APP, authenticate, authenticateUsage, type PlugboardOptions } from "../config.js"
 import { isPlugError, type CatalogModel, type ModelCaller, type PlugError, type PlugRequest } from "../contract.js"
 import { buildDiscovery, buildStatus, renderDiscoveryHtml, sendText } from "../discovery.js"
 import {
@@ -48,7 +49,10 @@ import { reportPolicy } from "../policy.js"
 import { isMessagesPath, serveMessages } from "../anthropic/route.js"
 import { serveCompletions } from "../completions/route.js"
 import { serveResponses } from "../responses/route.js"
-import { processMetrics, processStatus, type RuntimeStatus } from "../runtime.js"
+import { liveOptions, processMetrics, processStatus, type RuntimeStatus } from "../runtime.js"
+import type { UsageRecorder } from "../usage.js"
+import { DASHBOARD_ROUTES } from "../dashboard/page.js"
+import { serveDashboard } from "../dashboard/assets.js"
 import { chatCodec, serveChoices } from "./fanout.js"
 import { parseChatRequest } from "./request.js"
 import { collectCompletion, encodeError, encodeModelList, streamCompletion } from "./response.js"
@@ -64,6 +68,8 @@ export interface RouteHost {
   readonly metrics?: Metrics
   /** Runtime facts for `/v1/status` and `/metrics`; the process runtime's by default. */
   readonly status?: () => RuntimeStatus
+  /** Per-app usage (`src/usage.ts`): fed from the request log point, and served by `GET /v1/usage` when present. */
+  readonly usage?: UsageRecorder
 }
 
 const SESSION_HEADER = "x-plugboard-session"
@@ -116,7 +122,11 @@ export function createOpenAiRoute(routeHost: RouteHost) {
   const runtimeStatus = routeHost.status ?? processStatus
   const host: RouteHost = metrics ? { ...routeHost, caller: metered(routeHost.caller, metrics) } : routeHost
   /** Routes with a handler of their own. `GET /metrics` exists only when enabled; otherwise it is an unknown path. */
-  const known = (route: string) => KNOWN_ROUTES.includes(route) || DISCOVERY_ROUTES.includes(route) || (metrics !== undefined && route === "GET /metrics")
+  const known = (route: string) =>
+    KNOWN_ROUTES.includes(route) ||
+    DISCOVERY_ROUTES.includes(route) ||
+    (metrics !== undefined && route === "GET /metrics") ||
+    (host.usage !== undefined && (route === "GET /v1/usage" || DASHBOARD_ROUTES.has(route)))
   /** Responses to Gemini routes: errors there use Google's body. */
   const googleErrors = new WeakSet<ServerResponse>()
   const fail = (response: ServerResponse, error: PlugError, close = false) =>
@@ -162,7 +172,7 @@ export function createOpenAiRoute(routeHost: RouteHost) {
       const keyed = Object.keys(host.options.keys).length > 0
       let app: string | undefined = keyed ? undefined : DEFAULT_APP
       if (keyed && request.headers.authorization !== undefined) {
-        const auth = authenticate(host.options, request.headers.authorization)
+        const auth = authenticate(liveOptions(host.options), request.headers.authorization)
         if (isPlugError(auth)) return fail(response, auth)
         app = auth.app
       }
@@ -172,9 +182,15 @@ export function createOpenAiRoute(routeHost: RouteHost) {
       return sendText(response, 200, "text/html; charset=utf-8", renderDiscoveryHtml(doc), PAGE_HEADERS)
     }
 
+    // The usage dashboard (#141): a page and its files, keyless like the discovery pages. Its data comes from `GET /v1/usage`, behind a key.
+    if (host.usage && DASHBOARD_ROUTES.has(route)) return serveDashboard(request, response, route)
+
+    // Usage has its own credentials: the admin key reads every app, any other key only its own app (`authenticateUsage`).
+    if (route === "GET /v1/usage" && host.usage) return serveUsage(request, response, url, host.usage, info)
+
     // Authenticate before anything reveals which routes exist: an unauthenticated caller sees 401 for every path but /healthz and the first-run pages.
     // Gemini clients also send the key as `x-goog-api-key` or `?key=` (see `geminiAuthorization`).
-    const auth = authenticate(host.options, gemini ? geminiAuthorization(request, url) : request.headers.authorization)
+    const auth = authenticate(liveOptions(host.options), gemini ? geminiAuthorization(request, url) : request.headers.authorization)
     if (isPlugError(auth)) return fail(response, auth)
     info.app = auth.app
 
@@ -286,6 +302,25 @@ export function createOpenAiRoute(routeHost: RouteHost) {
     sendJson(response, result.status, result.body, { retryAfterSeconds: result.retryAfterSeconds })
   }
 
+  /** `GET /v1/usage?from=&to=&app=`. An app key may name only its own app (another one is a 403); the admin key may name any app or none. */
+  async function serveUsage(request: IncomingMessage, response: ServerResponse, url: URL, usage: UsageRecorder, info: RequestInfo): Promise<void> {
+    const who = authenticateUsage(liveOptions(host.options), request.headers.authorization)
+    if (isPlugError(who)) return fail(response, who)
+    const app = url.searchParams.get("app") ?? undefined
+    if (!who.admin) {
+      if (app !== undefined && app !== who.app)
+        return fail(response, { status: 403, kind: "permission", code: "app_forbidden", message: "This key cannot read the usage of another app" })
+      info.app = who.app
+    }
+    const report = await usage.query({
+      from: url.searchParams.get("from") ?? undefined,
+      to: url.searchParams.get("to") ?? undefined,
+      app: who.admin ? app : who.app,
+    })
+    if (isPlugError(report)) return fail(response, report)
+    return sendJson(response, 200, report)
+  }
+
   /** Never rejects: every failure ends in a response (or a closed socket) and one log line. */
   return async function handle(request: IncomingMessage, response: ServerResponse): Promise<void> {
     // Generated here, never taken from the client: the id is echoed and logged, so it must not be attacker-controlled text.
@@ -339,6 +374,7 @@ export function createOpenAiRoute(routeHost: RouteHost) {
       } catch {}
       const ms = Date.now() - started
       metrics?.requestFinished({ app: info.app ?? NO_APP, route: info.route, status: response.statusCode, outcome: outcomeLabel(outcome, response.statusCode), ms })
+      if (info.app !== undefined) host.usage?.request({ app: info.app, route: info.route, status: response.statusCode, outcome: outcomeLabel(outcome, response.statusCode), ms })
       // Probes and scrapes that succeed are not worth a line each.
       if ((info.route !== "GET /healthz" && info.route !== "GET /metrics") || outcome !== "ok") {
         const fields = { id, route: info.route, app: info.app, model: info.model, served: info.served, fallbacks: info.fallbacks, dropped: info.dropped, status: response.statusCode, ms, outcome, error }

package/src/rpc.ts

@@ -0,0 +1,65 @@
+/**
+ * The usage RPC, `opencode-plugboard.usage` (package entry `./rpc`): the report `GET /v1/usage` serves,
+ * for OpenCode's own clients. A TUI plugin reads it with `client.rpc(UsageRpc).get({ ... })` over the
+ * server's password-authenticated API, so the method sees every app.
+ *
+ * The server plugin registers the handler in every accepted generation (`index.ts`). Registration is
+ * synchronous and touches no storage; the handler reads the same store as the route, from request
+ * time only. Input and output are JSON Schema (the host's `Rpc.define`): the input is the query
+ * (`from`, `to`, `app`, all optional), the output is the `UsageReport` as documented in `src/usage.ts`.
+ * A bad query is the declared error `invalid_query` with `{ param }`, naming the parameter.
+ */
+
+import { Rpc } from "@opencode/plugin/rpc"
+import type { RpcHandlers } from "@opencode/plugin/effect/rpc"
+import { Effect } from "effect"
+import { isPlugError, type PlugError } from "./contract.js"
+import type { UsageQuery, UsageReport } from "./usage.js"
+
+export const UsageRpc = Rpc.define({
+  id: "opencode-plugboard.usage",
+  methods: {
+    get: {
+      input: {
+        type: "object",
+        properties: {
+          from: { type: "string", description: "First UTC day, YYYY-MM-DD. Default: 29 days before `to`." },
+          to: { type: "string", description: "Last UTC day, YYYY-MM-DD. Default: today." },
+          app: { type: "string", description: "One app name. Default: every app." },
+        },
+        additionalProperties: false,
+      },
+      output: {
+        type: "object",
+        description: "A UsageReport (see src/usage.ts).",
+        additionalProperties: true,
+      },
+      errors: {
+        invalid_query: {
+          type: "object",
+          properties: { param: { type: "string", description: "The query parameter that is wrong: from, to or app." } },
+          required: ["param"],
+          additionalProperties: false,
+        },
+      },
+    },
+  },
+  events: {},
+})
+
+/** The query fields of an RPC input. The input was validated against JSON Schema by the host; anything else is ignored. */
+function queryOf(input: unknown): UsageQuery {
+  const record: Record<string, unknown> = typeof input === "object" && input !== null ? (input as Record<string, unknown>) : {}
+  const text = (value: unknown) => (typeof value === "string" ? value : undefined)
+  return { from: text(record.from), to: text(record.to), app: text(record.app) }
+}
+
+/** The handlers for `UsageRpc`, reading the given usage query (the generation's recorder). */
+export function usageHandlers(usage: { query(input: UsageQuery): Promise<UsageReport | PlugError> }): RpcHandlers<typeof UsageRpc> {
+  return {
+    get: (input, context) =>
+      Effect.promise(() => usage.query(queryOf(input))).pipe(
+        Effect.flatMap((result) => (isPlugError(result) ? Effect.fail(context.error("invalid_query", result.message, { param: result.param ?? "query" })) : Effect.succeed(result))),
+      ),
+  }
+}

package/src/runtime.ts

@@ -25,8 +25,10 @@
  *  - the metrics registry (src/metrics.ts) and the runtime start time, so counters and uptime
  *     outlive any one generation. `processMetrics` / `processStatus` read them for `/metrics`,
  *     `/v1/status` and the discovery pages;
- *   - the request limiter's queues and rate windows (src/limits.ts), so a cap holds across
- *     generations. `processLimits` reads them.
+  *   - the request limiter's queues and rate windows (src/limits.ts), so a cap holds across
+ *     generations. `processLimits` reads them;
+  *   - the usage store's live days (src/usage.ts), so the in-memory aggregates survive a generation.
+ *     `processUsage` reads them.
  *
  * Registration is explicit: `registerGeneration` returns whether the generation was accepted. A
  * rejected one (different `listen`, options that differ from the live ones, foreign runtime) never
@@ -60,6 +62,7 @@ import { ensureAppDir } from "./session/history.js"
 import type { HistoryPort } from "./session/host.js"
 import { recordSession, sweepHistory, type HistoryLimits } from "./session/prune.js"
 import { createSessionStore, type SessionStore } from "./session/state.js"
+import { createUsageState, type UsageState } from "./usage.js"
 
 export type Handler = (request: IncomingMessage, response: ServerResponse) => void
 
@@ -112,8 +115,8 @@ const BACKEND_POLL_MS = 25
 const BIND_RETRY_MS = 15_000
 const BIND_REMINDER_MS = 5 * 60_000
 
-/** 10: the response cache store (`src/cache.ts`) lives here too. 9: the request limiter state (`src/limits.ts`) lives here, so the concurrency caps and rate windows survive a generation. 8: `Metrics.render` is async and the registry is @prometheus-io/client's. 7: the options fingerprint comes from safe-stable-stringify, so it must not be compared with an older one. 6: the listener retries a failed bind (new fields on `Listener`). 5: adds the metrics registry and the start time. 4: the history sweep state and the session store's register hook. 3: confirmed directories and rejected generations. */
-const VERSION = 10
+/** 12: the live key set (`keys`, `Runtime.keys`) that a stricter newer generation replaces at once (#90). 11: the usage store's live days (`src/usage.ts`) live here too. 10: the response cache store (`src/cache.ts`) lives here too. 9: the request limiter state (`src/limits.ts`) lives here, so the concurrency caps and rate windows survive a generation. 8: `Metrics.render` is async and the registry is @prometheus-io/client's. 7: the options fingerprint comes from safe-stable-stringify, so it must not be compared with an older one. 6: the listener retries a failed bind (new fields on `Listener`). 5: adds the metrics registry and the start time. 4: the history sweep state and the session store's register hook. 3: confirmed directories and rejected generations. */
+const VERSION = 12
 const KEY = Symbol.for("opencode-plugboard.runtime")
 
 interface Listener {
@@ -167,8 +170,16 @@ interface Runtime {
   readonly limits: LimitState
   /** When this runtime was created, epoch ms. */
   readonly startedAt: number
+  /**
+   * The app keys authentication checks (app name -> key), once a generation has registered. Replaced
+   * when a newer generation only revokes or rotates keys (`registerGeneration`, #90). Absent means
+   * the handler's own options are used.
+   */
+  keys?: Readonly<Record<string, string>>
   /** The response cache store (src/cache.ts) and the fingerprint of the config and `apps` policy it was built for. */
   cache?: { readonly fingerprint: string; readonly store: CacheStore }
+  /** The usage store's live days and retention clock (src/usage.ts). */
+  readonly usage: UsageState
   listener?: Listener
   /** Present while a fiber is subscribed to the server event bus. */
   pump?: Pump
@@ -181,6 +192,7 @@ const detachedSessions = createSessionStore()
 const detachedMetrics = createMetrics()
 const detachedStartedAt = Date.now()
 const detachedLimits = createLimitState()
+const detachedUsage = createUsageState()
 let foreignVersionLogged = false
 
 /** The process runtime, created on first use; undefined when a different version already owns the process. */
@@ -197,6 +209,7 @@ function runtime(): Runtime | undefined {
       sweep: { nextAt: 0, running: false },
       metrics: createMetrics(),
       limits: createLimitState(),
+      usage: createUsageState(),
       startedAt: Date.now(),
     }
     slot[KEY] = created
@@ -275,6 +288,18 @@ export const processMetrics = (): Metrics => runtime()?.metrics ?? detachedMetri
 /** The request limiter's state shared by every generation in the process (detached under a foreign-version runtime). */
 export const processLimits = (): LimitState => runtime()?.limits ?? detachedLimits
 
+/** The usage store's live days shared by every generation in the process (detached under a foreign-version runtime). */
+export const processUsage = (): UsageState => runtime()?.usage ?? detachedUsage
+
+/**
+ * The options authentication reads: `keys` is the live key set, not the serving generation's own
+ * (a generation that is still live after a key revocation keeps its old keys otherwise, #90).
+ */
+export function liveOptions(options: PlugboardOptions): PlugboardOptions {
+  const keys = runtime()?.keys
+  return keys === undefined || keys === options.keys ? options : { ...options, keys }
+}
+
 /**
  * Wraps `caller` with the response cache when option `cache` is set (a no-op without it). The store
  * lives on the runtime, so it survives plugin generations. It is replaced when the cache option or
@@ -423,6 +448,12 @@ function closeListener(rt: Runtime, listener: Listener): void {
  * generation's options are adopted. A different `listen` needs a server restart and is rejected.
  * A rejected generation is not in the generation list: it never serves, supplies no catalog, and
  * the caller must not install hooks or seeds for it.
+ *
+ * The key set (`keys`) has one more rule (#90). While generations are live, a newer generation whose
+ * keys only revoke or rotate those of apps the listener already has (no app added, at least one
+ * left) replaces `Runtime.keys` at once, so a Location still on an older generation stops accepting
+ * a removed key. Any other key change is rejected like any other option difference. The listener's
+ * `fingerprint` covers the options without `keys`.
  */
 export function registerGeneration(input: GenerationInput): Registration {
   const rt = runtime()
@@ -444,7 +475,8 @@ export function registerGeneration(input: GenerationInput): Registration {
       },
     }
   }
-  const fingerprint = canonicalJson(input.options)
+  const fingerprint = canonicalJson({ ...(input.options as Record<string, unknown>), keys: undefined })
+  const keys = (input.options as { readonly keys?: Readonly<Record<string, string>> } | null)?.keys ?? {}
   const listener = (rt.listener ??= startListener(rt, listen, fingerprint))
   if (listener.listen.host !== listen.host || listener.listen.port !== listen.port) {
     if (!listener.mismatchLogged) {
@@ -457,16 +489,28 @@ export function registerGeneration(input: GenerationInput): Registration {
     }
     return reject()
   }
-  if (listener.fingerprint !== fingerprint) {
-    if (rt.generations.length > 0) {
-      if (!listener.mismatchLogged) {
-        listener.mismatchLogged = true
-        logError("listener.options_mismatch", { action: "this Location is rejected; global config is authoritative" })
-      }
-      return reject()
+  const rejectOptions = (): Registration => {
+    if (!listener.mismatchLogged) {
+      listener.mismatchLogged = true
+      logError("listener.options_mismatch", { action: "this Location is rejected; global config is authoritative" })
     }
+    return reject()
+  }
+  if (listener.fingerprint !== fingerprint) {
+    if (rt.generations.length > 0) return rejectOptions()
     listener.fingerprint = fingerprint
     listener.mismatchLogged = false
+    rt.keys = keys
+  } else if (canonicalJson(keys) !== canonicalJson(rt.keys ?? {})) {
+    const live = rt.keys ?? {}
+    if (rt.generations.length === 0) rt.keys = keys
+    else if (revokesOrRotatesOnly(live, keys)) {
+      log("listener.keys_updated", {
+        removed: Object.keys(live).filter((app) => !Object.hasOwn(keys, app)).length,
+        rotated: Object.keys(keys).filter((app) => Object.hasOwn(live, app) && live[app] !== keys[app]).length,
+      })
+      rt.keys = keys
+    } else return rejectOptions()
   }
   if (listener.graceTimer) clearTimeout(listener.graceTimer)
   listener.graceTimer = undefined
@@ -510,6 +554,12 @@ export function registerGeneration(input: GenerationInput): Registration {
   }
 }
 
+/** #90: `next` names no app that `live` lacks, and names at least one app: it only removes or changes keys. */
+function revokesOrRotatesOnly(live: Readonly<Record<string, string>>, next: Readonly<Record<string, string>>): boolean {
+  const apps = Object.keys(next)
+  return apps.length > 0 && apps.every((app) => Object.hasOwn(live, app))
+}
+
 /**
  * Start the process-wide event pump if it is not running. The bus is server-wide, so the store
  * drops everything that is not a registered request session before it is buffered. The pump is

package/src/session/host.ts

@@ -129,6 +129,30 @@ export function createHistoryPort(ctx: HostContext): HistoryPort {
   }
 }
 
+/**
+ * `ctx.storage` as a Promise port for string values (the usage store keeps one JSON string per app
+ * and day). Same host table and namespace as `HistoryPort`; the keys never overlap (`usage/` vs `history/`).
+ */
+export interface StoragePort {
+  get(key: string): Promise<string | undefined>
+  put(key: string, value: string): Promise<void>
+  drop(key: string): Promise<void>
+  scan(input: { readonly prefix: string; readonly after?: string; readonly limit: number }): Promise<{ readonly keys: ReadonlyArray<string>; readonly next?: string }>
+}
+
+export function createStoragePort(ctx: HostContext): StoragePort {
+  return {
+    get: (key) => Effect.runPromise(ctx.storage.get(key)).then((value) => (typeof value === "string" ? value : undefined)),
+    put: (key, value) => Effect.runPromise(ctx.storage.set(key, value)),
+    drop: (key) => Effect.runPromise(ctx.storage.remove(key)),
+    scan: (input) =>
+      Effect.runPromise(ctx.storage.scan(input)).then((result) => ({
+        keys: result.entries.map((entry) => entry.key),
+        ...(result.next === undefined ? {} : { next: result.next }),
+      })),
+  }
+}
+
 const record = (value: unknown): Record<string, unknown> | undefined =>
   typeof value === "object" && value !== null ? (value as Record<string, unknown>) : undefined