opencode-plugboard 0.15.0 → 0.17.0

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`).
@@ -17,12 +17,13 @@
 import type { IncomingMessage, ServerResponse } from "node:http"
 import { isPlugError, type PlugError, type PlugRequest } from "../contract.js"
 import { reportServed, type ServedInfo } from "../fallback.js"
-import { boundEvents, checkJsonContentType, readJsonBody, sendJson, sseWriter, type RequestScope } from "../http.js"
+import { boundEvents, checkJsonContentType, readJsonBody, sendError, sendJson, sseWriter, type RequestScope } from "../http.js"
 import { listAvailableModels, resolveModel } from "../models.js"
 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)
@@ -64,10 +70,11 @@ export function matchGeminiRoute(method: string | undefined, path: string): Gemi
     const verb = colon > 0 ? rest.slice(colon + 1) : ""
     const model = decode(rest.slice(0, colon))
     if (!/^[A-Za-z]+$/.test(verb) || model === undefined) return undefined
-    const label = `POST ${prefix.slice(0, -1)}/{model}:${verb}`
     if (verb === "generateContent" || verb === "streamGenerateContent")
-      return { op: "generate", route: label, model: model.startsWith("models/") ? model.slice(7) : model, stream: verb === "streamGenerateContent" }
-    return { op: "unsupported", route: label, verb }
+      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 }
   }
   return undefined
 }
@@ -95,10 +102,23 @@ export interface GeminiCall {
 }
 
 export async function serveGemini(host: RouteHost, { match, request, url, app, response, scope, info }: GeminiCall): Promise<void> {
-  const fail = (error: PlugError) => sendJson(response, error.status, encodeGeminiError(error))
+  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/http.ts

@@ -165,18 +165,29 @@ export function finishRequest(request: IncomingMessage, response: ServerResponse
   response.once("close", () => clearTimeout(timer))
 }
 
-/** `close`: also tell the client to drop the connection (after an unread or abandoned body). */
-export const sendJson = (response: ServerResponse, status: number, payload: unknown, options?: { close?: boolean }) => {
+/**
+ * `close`: also tell the client to drop the connection (after an unread or abandoned body).
+ * `retryAfterSeconds`: sent as `Retry-After` (a rate-limit refusal, see `PlugError.retryAfterSeconds`).
+ */
+export const sendJson = (response: ServerResponse, status: number, payload: unknown, options?: { close?: boolean; retryAfterSeconds?: number }) => {
   if (response.headersSent || response.destroyed) return
   const body = JSON.stringify(payload)
   response.writeHead(status, {
     "content-type": "application/json",
     "content-length": Buffer.byteLength(body),
     ...(options?.close ? { connection: "close" } : {}),
+    ...(options?.retryAfterSeconds !== undefined ? { "retry-after": String(options.retryAfterSeconds) } : {}),
   })
   response.end(body)
 }
 
+/**
+ * A `PlugError` answered in a front-end's own wire body, before any output. Every route's `fail` goes
+ * through here, so a refused call (`PlugError.retryAfterSeconds`) always carries `Retry-After`.
+ */
+export const sendError = (response: ServerResponse, error: PlugError, body: unknown, options?: { close?: boolean }) =>
+  sendJson(response, error.status, body, { ...options, retryAfterSeconds: error.retryAfterSeconds })
+
 /**
  * SSE response writer. Headers go out with the first chunk, so nothing is committed until there
  * is something to send; chunks after the client is gone are dropped. `write` is synchronous (the

package/src/openai/fanout.ts

@@ -25,7 +25,7 @@ import type { PlugError, PlugEvent, PlugRequest, PlugUsage } from "../contract.j
 import { reportServed, type ServedInfo } from "../fallback.js"
 import { reportCache } from "../cache.js"
 import { reportPolicy } from "../policy.js"
-import { RequestAborted, boundEvents, sendJson, sseWriter, type RequestScope } from "../http.js"
+import { RequestAborted, boundEvents, sendError, sendJson, sseWriter, type RequestScope } from "../http.js"
 import { chatUsageChunk, collectCompletion, encodeError, streamCompletion, type OpenAiExchange, type StreamChoice, type StreamResult } from "./response.js"
 import type { RouteHost } from "./route.js"
 
@@ -38,7 +38,7 @@ export interface ChoiceCodec {
   /** Prefix of the shared stream id (`chatcmpl-`, `cmpl-`). */
   readonly idPrefix: string
   /** One choice as a complete JSON body with `choices[0]` and `usage`. */
-  collect(events: AsyncIterable<PlugEvent>, index: number): Promise<{ status: number; body: object }>
+  collect(events: AsyncIterable<PlugEvent>, index: number): Promise<{ status: number; body: object; retryAfterSeconds?: number }>
   /** One choice of the shared stream: this choice's chunks only (see `StreamChoice`). */
   streamChoice(events: AsyncIterable<PlugEvent>, write: (chunk: string) => void, choice: StreamChoice): Promise<StreamResult>
   /** The final chunk with the summed usage (`include_usage`). */
@@ -155,7 +155,7 @@ const addUsage = (a: PlugUsage, b: PlugUsage): PlugUsage => {
 }
 
 export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls, response, scope, info, codec }: ChoicesCall): Promise<void> {
-  const fail = (error: PlugError) => sendJson(response, error.status, encodeError(error))
+  const fail = (error: PlugError) => sendError(response, error, encodeError(error))
   // Abandoned requests (client gone, deadline passed) must never reach the model caller.
   if (scope.signal.aborted) throw scope.signal.reason
 
@@ -190,8 +190,8 @@ export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls
     )
 
   if (!codec.stream) {
-    const results = await new Promise<Array<{ status: number; body: object }>>((resolve, reject) => {
-      const done: Array<{ status: number; body: object }> = []
+    const results = await new Promise<Array<{ status: number; body: object; retryAfterSeconds?: number }>>((resolve, reject) => {
+      const done: Array<{ status: number; body: object; retryAfterSeconds?: number }> = []
       let left = calls.length
       calls.forEach((_, index) => {
         codec.collect(open(index), index).then(
@@ -211,7 +211,7 @@ export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls
       })
     })
     const first = results[0]!
-    return sendJson(response, first.status, results.length === 1 ? first.body : mergeBodies(results.map((result) => result.body)))
+    return sendJson(response, first.status, results.length === 1 ? first.body : mergeBodies(results.map((result) => result.body)), { retryAfterSeconds: first.retryAfterSeconds })
   }
 
   const sse = sseWriter(response, scope.signal)

package/src/openai/response.ts

@@ -195,7 +195,7 @@ const now = () => Math.floor(Date.now() / 1000)
 export async function collectCompletion(
   events: AsyncIterable<PlugEvent>,
   exchange: OpenAiExchange,
-): Promise<{ status: number; body: object }> {
+): Promise<{ status: number; body: object; retryAfterSeconds?: number }> {
   let text = ""
   const calls: ToolCall[] = []
   let finish: Exclude<PlugFinish, "error"> | undefined
@@ -217,7 +217,7 @@ export async function collectCompletion(
   if (!failure && !finish) failure = noFinish()
   if (failure || !finish) {
     const error = failure ?? noFinish()
-    return { status: error.status, body: encodeError(error) }
+    return { status: error.status, body: encodeError(error), retryAfterSeconds: error.retryAfterSeconds }
   }
 
   const answer = calls.find((call) => structured.isAnswer(exchange, call))

package/src/openai/route.ts

@@ -20,7 +20,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 {
@@ -32,6 +32,7 @@ import {
   checkOrigin,
   finishRequest,
   readJsonBody,
+  sendError,
   sendJson,
   sseWriter,
   type RequestScope,
@@ -41,13 +42,14 @@ import { encodeGeminiError } from "../gemini/response.js"
 import { geminiAuthorization, matchGeminiRoute, serveGemini } from "../gemini/route.js"
 import { errorMessage, log, logError, withRequestId } from "../log.js"
 import { NO_APP, outcomeLabel, type Metrics } from "../metrics.js"
-import { listAvailableModels, resolveModel } from "../models.js"
+import { filterByCapability, listAvailableModels, parseCapability, resolveModel } from "../models.js"
 import { reportCache } from "../cache.js"
 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 { chatCodec, serveChoices } from "./fanout.js"
 import { parseChatRequest } from "./request.js"
 import { collectCompletion, encodeError, encodeModelList, streamCompletion } from "./response.js"
@@ -63,6 +65,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"
@@ -115,11 +119,12 @@ 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")
   /** Responses to Gemini routes: errors there use Google's body. */
   const googleErrors = new WeakSet<ServerResponse>()
   const fail = (response: ServerResponse, error: PlugError, close = false) =>
-    sendJson(response, error.status, googleErrors.has(response) ? encodeGeminiError(error) : encodeError(error), { close })
+    sendError(response, error, googleErrors.has(response) ? encodeGeminiError(error) : encodeError(error), { close })
 
   /** The catalog for a page that can do without it: a failure is logged and reported as absent; an abort still ends the request. */
   async function optionalCatalog(scope: RequestScope): Promise<ReadonlyArray<CatalogModel> | undefined> {
@@ -161,7 +166,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
       }
@@ -171,9 +176,12 @@ export function createOpenAiRoute(routeHost: RouteHost) {
       return sendText(response, 200, "text/html; charset=utf-8", renderDiscoveryHtml(doc), PAGE_HEADERS)
     }
 
+    // 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
 
@@ -198,8 +206,13 @@ export function createOpenAiRoute(routeHost: RouteHost) {
     }
 
     if (route === "GET /v1/models" || modelId !== undefined) {
+      // `?capability=vision|tools` filters the list (#61). Any other value is refused before the catalog loads.
+      const requested = modelId === undefined ? url.searchParams.get("capability") : null
+      const capability = requested === null ? undefined : parseCapability(requested)
+      if (requested !== null && capability === undefined)
+        return fail(response, { status: 400, kind: "invalid_request", code: "invalid_capability", param: "capability", message: "capability must be vision or tools" })
       const listed = listAvailableModels(host.options, await scope.race(host.loadCatalog()), auth.app)
-      if (modelId === undefined) return sendJson(response, 200, encodeModelList(listed))
+      if (modelId === undefined) return sendJson(response, 200, encodeModelList(capability ? filterByCapability(listed, capability) : listed))
       const item = listed.find((m) => m.id === modelId)
       if (!item) {
         return fail(response, {
@@ -277,7 +290,26 @@ export function createOpenAiRoute(routeHost: RouteHost) {
     }
 
     const result = await collectCompletion(events, exchange)
-    sendJson(response, result.status, result.body)
+    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. */
@@ -333,6 +365,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/responses/route.ts

@@ -11,7 +11,7 @@
 import type { ServerResponse } from "node:http"
 import { isPlugError, type PlugError, type PlugRequest } from "../contract.js"
 import { reportServed, type ServedInfo } from "../fallback.js"
-import { boundEvents, sendJson, sseWriter, type RequestScope } from "../http.js"
+import { boundEvents, sendError, sendJson, sseWriter, type RequestScope } from "../http.js"
 import { resolveModel } from "../models.js"
 import { reportCache } from "../cache.js"
 import { reportPolicy } from "../policy.js"
@@ -32,7 +32,7 @@ export interface ResponsesCall {
 }
 
 export async function serveResponses(host: RouteHost, { app, body, response, scope, info }: ResponsesCall): Promise<void> {
-  const fail = (error: PlugError) => sendJson(response, error.status, encodeError(error))
+  const fail = (error: PlugError) => sendError(response, error, encodeError(error))
 
   const parsed = parseResponsesRequest(body, host.options)
   if (isPlugError(parsed)) return fail(parsed)

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