opencode-plugboard 0.16.0 → 0.18.0

package/index.ts

@@ -25,10 +25,12 @@ import { errorMessage, logError } from "./src/log.js"
 import { withFallbacks } from "./src/fallback.js"
 import { withLimits } from "./src/limits.js"
 import { createOpenAiRoute } from "./src/openai/route.js"
-import { ensureBackend, ensurePump, loadServingCatalog, processLimits, processMetrics, registerGeneration, sessionStore, withResponseCache } from "./src/runtime.js"
+import { ensureBackend, ensurePump, loadServingCatalog, processLimits, processMetrics, processUsage, registerGeneration, sessionStore, withResponseCache } from "./src/runtime.js"
 import { createSessionCaller } from "./src/session/caller.js"
 import { installSessionHooks } from "./src/session/context.js"
-import { createHistoryPort, createSessionPort, loadCatalog } from "./src/session/host.js"
+import { createHistoryPort, createSessionPort, createStoragePort, loadCatalog } from "./src/session/host.js"
+import { usageHandlers, UsageRpc } from "./src/rpc.js"
+import { createUsageRecorder, withUsage } from "./src/usage.js"
 
 export default Plugin.define({
   id: "opencode-plugboard",
@@ -67,26 +69,42 @@ export default Plugin.define({
         return loadServingCatalog(ownCatalog)
       }
       const limits = options.limits
+      // Usage (src/usage.ts): built from closures only; it reads and writes storage from request handling.
+      const usage = options.usage.enabled
+        ? createUsageRecorder({ state: processUsage(), storage: createStoragePort(ctx), loadCatalog: servingCatalog, retentionDays: options.usage.retentionDays })
+        : undefined
       const handle = createOpenAiRoute({
         options,
-        // Caps are outermost, so one request takes one slot even when it falls back (src/limits.ts).
+        // Usage is outermost, so it records the answer the client gets (src/usage.ts).
+        // Caps are outside the fallbacks, so one request takes one slot even when it falls back (src/limits.ts).
         // Aliases written as a list retry the next target before the first output (src/fallback.ts).
-        // Limits are outermost (one slot per request, refused calls never reach anything); the response
-        // cache sits outside the fallbacks, so a hit never reaches a provider (src/limits.ts, src/cache.ts).
-        caller: withLimits(
-          withResponseCache(
-            withFallbacks(createSessionCaller(callerDeps), {
+        // The response cache sits outside the fallbacks, so a hit never reaches a provider (src/cache.ts).
+        caller: withUsage(
+          withLimits(
+            withResponseCache(
+              withFallbacks(createSessionCaller(callerDeps), {
+                options,
+                loadCatalog: servingCatalog,
+                onFallback: (app) => {
+                  if (options.metrics) processMetrics().fallback(app)
+                  usage?.fallback(app)
+                },
+              }),
               options,
-              loadCatalog: servingCatalog,
-              onFallback: options.metrics ? (app) => processMetrics().fallback(app) : undefined,
-            }),
-            options,
+            ),
+            () => limits,
+            processLimits(),
+            {
+              onLimited: (app, reason) => {
+                if (options.metrics) processMetrics().limited(app, reason)
+                usage?.limited(app)
+              },
+            },
           ),
-          () => limits,
-          processLimits(),
-          { onLimited: options.metrics ? (app, reason) => processMetrics().limited(app, reason) : undefined },
+          usage,
         ),
         loadCatalog: servingCatalog,
+        usage,
       })
       const registration = registerGeneration({
         listen: options.listen,
@@ -113,6 +131,13 @@ export default Plugin.define({
       // ---- a rejected generation (different options or `listen`, foreign runtime) serves nothing and installs nothing.
       if (!registration.accepted) return
 
+      // ---- the usage RPC (src/rpc.ts): a synchronous registration; its handler reads the store from request time only.
+      // Its error channel is `unknown` in the host, so a failed registration is logged and the plugin keeps loading.
+      if (usage)
+        yield* ctx.rpc.register(UsageRpc, usageHandlers(usage)).pipe(
+          Effect.catch((error) => Effect.sync(() => logError("rpc.register_failed", { rpc: UsageRpc.id, error: errorMessage(error) }))),
+        )
+
       // ---- the context hook, the agent deny and the seed tools. Ownership of the Location is only
       // known after an asynchronous check (`ensureBackend`), so all three are no-ops until
       // `registration.confirmed()`: in real projects nothing is ever added or rewritten.

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "opencode-plugboard",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "type": "module",
   "license": "MIT",
-  "description": "Use the ChatGPT, Claude, Copilot and OpenCode Go logins in your OpenCode server from any app. An OpenCode V2 plugin serving OpenAI-compatible Chat Completions, Responses and model endpoints.",
+  "description": "Use the ChatGPT, Claude, Copilot and OpenCode Go logins in your OpenCode server from any app: an OpenCode V2 plugin serving OpenAI, Anthropic and Gemini compatible APIs.",
   "keywords": ["opencode", "opencode-plugin", "openai", "openai-compatible", "chat-completions", "responses-api", "llm-gateway", "llm-proxy"],
   "repository": {
     "type": "git",
@@ -14,14 +14,26 @@
   },
   "homepage": "https://github.com/jjjermiah/opencode-plugboard#readme",
   "main": "./index.ts",
+  "types": "./index.ts",
   "exports": {
-    ".": "./index.ts"
+    ".": { "types": "./index.ts", "default": "./index.ts" },
+    "./rpc": { "types": "./rpc.ts", "default": "./rpc.ts" },
+    "./tui": { "types": "./tui.ts", "default": "./tui.ts" }
+  },
+  "files": ["index.ts", "rpc.ts", "tui.ts", "src/", "README.md", "LICENSE"],
+  "engines": {
+    "bun": ">=1.4.2"
   },
-  "files": ["index.ts", "src/", "README.md", "LICENSE"],
   "scripts": {
-    "typecheck": "tsc --noEmit && tsc --noEmit -p test",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.tui.json && tsc --noEmit -p test",
     "test": "bun test",
+    "bench": "bun test/bench/request.bench.ts",
+    "mutations": "bun .github/scripts/mutation-check.ts",
+    "flake-hunt": "bun .github/scripts/flake-hunt.ts",
+    "coverage-manifest": "bun .github/scripts/coverage-manifest.ts",
     "smoke:pack": "bun .github/scripts/smoke-pack.ts",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
     "release": "bun .github/scripts/release.ts"
   },
   "dependencies": {
@@ -31,7 +43,8 @@
     "lru-cache": "11.5.3",
     "p-queue": "9.3.5",
     "pino": "10.4.0",
-    "safe-stable-stringify": "2.5.0"
+    "safe-stable-stringify": "2.5.0",
+    "uplot": "1.6.32"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "4.0.78",
@@ -46,11 +59,15 @@
     "@langchain/google-genai": "2.3.2",
     "@langchain/openai": "1.6.2",
     "@opencode/plugin": "2.0.26",
+    "@opentui/core": "0.5.17",
+    "@opentui/solid": "0.5.17",
     "@types/bun": "1.4.2",
     "@types/escape-html": "^1.0.4",
     "@types/lcov-parse": "1.0.2",
     "@types/node": "^26.6.2",
+    "@types/semver": "7.8.0",
     "ai": "7.0.137",
+    "ajv": "8.20.0",
     "conventional-commits-parser": "7.1.3",
     "effect": "4.0.0-rc.112",
     "eventsource-parser": "4.1.1",
@@ -58,11 +75,23 @@
     "fast-xml-parser": "5.11.2",
     "lcov-parse": "1.0.0",
     "lefthook": "2.2.1",
+    "mitata": "1.0.34",
     "openai": "7.32.0",
-    "typescript": "^5.9.3"
+    "semver": "7.8.5",
+    "solid-js": "1.9.15",
+    "typescript": "^5.9.3",
+    "vitepress": "1.6.4"
   },
   "peerDependencies": {
     "@opencode/plugin": ">=2.0.26 <2.1",
-    "effect": "4.0.0-rc.112"
+    "@opentui/core": ">=0.5.17",
+    "@opentui/solid": ">=0.5.17",
+    "effect": "4.0.0-rc.112",
+    "solid-js": ">=1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentui/core": { "optional": true },
+    "@opentui/solid": { "optional": true },
+    "solid-js": { "optional": true }
   }
 }

package/rpc.ts

@@ -0,0 +1,3 @@
+// The `./rpc` entrypoint, at the package root for the same reason as `tui.ts`: a plugin configured
+// by local path is resolved as `<directory>/rpc`, without `exports`.
+export * from "./src/rpc.ts"

package/src/anthropic/request.ts

@@ -336,7 +336,7 @@ export function parseMessagesRequest(body: unknown, options: PlugboardOptions):
   }
   return {
     request,
-    exchange: { model: body.model, stream: body.stream === true, thinking: thinking.enabled },
+    exchange: { model: body.model, stream: body.stream === true, thinking: thinking.enabled, stop: generation.stop },
     ...(thinking.effort ? { reasoningEffort: thinking.effort } : {}),
     topKIgnored: body.top_k != null,
   }

package/src/anthropic/response.ts

@@ -17,6 +17,8 @@ export interface MessagesExchange {
   readonly stream: boolean
   /** `thinking` was enabled or adaptive: reasoning text is returned as thinking blocks. */
   readonly thinking: boolean
+  /** The request's `stop_sequences`. The host reports a stop without the sequence that caused it, so the end of the text is checked. */
+  readonly stop?: ReadonlyArray<string>
 }
 
 /** A stream event as emitted: `type` is also the SSE event name. */
@@ -74,6 +76,10 @@ const STOP_REASON: Record<Exclude<PlugFinish, "error">, string> = {
   "content-filter": "refusal",
 }
 
+/** The longest stop sequence the text ends with, if any. */
+const stopTail = (tail: string, stops: ReadonlyArray<string>): string | undefined =>
+  stops.filter((stop) => tail.endsWith(stop)).sort((a, b) => b.length - a.length)[0]
+
 const noFinish = (): PlugError => ({ status: 500, kind: "server", message: "Model stream ended without a finish event" })
 const failedRun = (): PlugError => ({ status: 500, kind: "server", message: "Model run failed" })
 
@@ -121,6 +127,10 @@ export async function runMessage(
   let finish: Exclude<PlugFinish, "error"> | undefined
   let usage: PlugUsage | undefined
   let failure: PlugError | undefined
+  // Text is held back by the longest stop sequence (`holdback` characters), so a sequence at the end of
+  // the answer can be found and removed before it is sent. Without stop sequences nothing is held.
+  const holdback = Math.max(0, ...(exchange.stop ?? []).map((stop) => stop.length))
+  let held = ""
 
   const message = (extra: Record<string, unknown>) => ({
     id,
@@ -147,9 +157,25 @@ export async function runMessage(
   const close = () => {
     if (!open) return
     emit({ type: "content_block_stop", index: open.index })
+    // The signature is always empty: the host does not expose the provider's thinking signature (#146), so a
+    // replayed thinking block cannot carry the real one. Clients that replay thinking are told by the docs.
     content.push(open.kind === "text" ? { type: "text", text: open.text } : { type: "thinking", thinking: open.text, signature: "" })
     open = undefined
   }
+  const releaseHeld = () => {
+    const out = held
+    held = ""
+    delta("text", out)
+  }
+  const text = (chunk: string) => {
+    if (holdback === 0) return delta("text", chunk)
+    held += chunk
+    if (held.length > holdback) {
+      const out = held.slice(0, held.length - holdback)
+      held = held.slice(out.length)
+      delta("text", out)
+    }
+  }
   const delta = (kind: "text" | "thinking", text: string) => {
     if (text.length === 0) return
     start()
@@ -172,6 +198,7 @@ export async function runMessage(
   }
   /** Tool calls arrive whole, so each goes out as one `input_json_delta` holding the full input. */
   const toolCall = (call: ToolCall) => {
+    releaseHeld()
     start()
     close()
     const index = nextIndex++
@@ -197,8 +224,9 @@ export async function runMessage(
       continue
     }
     if (event.type === "reasoning-delta") {
+      releaseHeld()
       if (exchange.thinking) delta("thinking", event.text)
-    } else if (event.type === "text-delta") delta("text", event.text)
+    } else if (event.type === "text-delta") text(event.text)
     else toolCall(event)
   }
 
@@ -206,16 +234,23 @@ export async function runMessage(
   if (failure) {
     if (!started) return { failure, started }
     // The stream is already committed: close what is open and end with an `error` event (no `message_stop`).
+    releaseHeld()
     close()
     emit(encodeError(failure))
     return { failure, started }
   }
+  // A plain stop with no tool calls that ends on a stop sequence: the sequence is not part of the answer.
+  const matched = holdback > 0 && finish === "stop" && calls === 0 ? stopTail(held, exchange.stop ?? []) : undefined
+  if (matched !== undefined) held = held.slice(0, held.length - matched.length)
+  releaseHeld()
   start()
   close()
   ping()
   const reason = finish === "stop" && calls > 0 ? "tool-calls" : (finish ?? "stop")
-  const final = message({ stop_reason: STOP_REASON[reason as Exclude<PlugFinish, "error">], usage: encodeUsage(usage) })
-  emit({ type: "message_delta", delta: { stop_reason: final.stop_reason, stop_sequence: null }, usage: final.usage })
+  const stopReason = matched !== undefined ? "stop_sequence" : STOP_REASON[reason as Exclude<PlugFinish, "error">]
+  const stopSequence = matched ?? null
+  const final = message({ stop_reason: stopReason, stop_sequence: stopSequence, usage: encodeUsage(usage) })
+  emit({ type: "message_delta", delta: { stop_reason: stopReason, stop_sequence: stopSequence }, usage: final.usage })
   emit({ type: "message_stop" })
   return { started, message: final }
 }

package/src/anthropic/route.ts

@@ -1,5 +1,5 @@
 /**
- * `POST /v1/messages` (and a clear 404 for `POST /v1/messages/count_tokens`): the Anthropic
+ * `POST /v1/messages` and `POST /v1/messages/count_tokens` (an estimate, see `tokens.ts`): the Anthropic
  * Messages front-end's half of the route. `src/openai/route.ts` hands every request for these
  * paths over before it does anything else, because this route differs from the OpenAI ones in
  * three ways: errors use Anthropic's body shape from the first check on, `x-api-key` authenticates
@@ -13,6 +13,7 @@
 
 import type { IncomingMessage, ServerResponse } from "node:http"
 import { authenticate } from "../config.js"
+import { liveOptions } from "../runtime.js"
 import { isPlugError, type PlugError, type PlugRequest } from "../contract.js"
 import {
   BodyError,
@@ -33,8 +34,11 @@ import { reportPolicy } from "../policy.js"
 import { dropRejected } from "../openai/sampling.js"
 import type { RouteHost } from "../openai/route.js"
 import { parseMessagesRequest } from "./request.js"
+import { estimateTokens } from "./tokens.js"
 import { encodeError, runMessage, sseFrame } from "./response.js"
 
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value)
+
 const SESSION_HEADER = "x-plugboard-session"
 const DROPPED_HEADER = "x-plugboard-dropped-params"
 const MESSAGES = "/v1/messages"
@@ -59,9 +63,10 @@ const header = (request: IncomingMessage, name: string): string | undefined => {
 
 /** `Authorization: Bearer` first (Claude Code with ANTHROPIC_AUTH_TOKEN), then `x-api-key` (the Anthropic SDKs). One key store. */
 const authenticateRequest = (host: RouteHost, request: IncomingMessage) => {
-  const bearer = authenticate(host.options, request.headers.authorization)
+  const options = liveOptions(host.options)
+  const bearer = authenticate(options, request.headers.authorization)
   const apiKey = header(request, "x-api-key")
-  return isPlugError(bearer) && apiKey ? authenticate(host.options, `Bearer ${apiKey}`) : bearer
+  return isPlugError(bearer) && apiKey ? authenticate(options, `Bearer ${apiKey}`) : bearer
 }
 
 export async function serveMessages(host: RouteHost, call: MessagesCall): Promise<void> {
@@ -93,18 +98,20 @@ export async function serveMessages(host: RouteHost, call: MessagesCall): Promis
     info.app = auth.app
     if (request.method !== "POST")
       return fail({ status: 405, kind: "invalid_request", code: "method_not_allowed", message: `Method ${request.method} is not allowed for ${path}; use POST` })
-    if (path === COUNT_TOKENS)
-      return fail({ status: 404, kind: "not_found", code: "not_found", message: "count_tokens is not supported by plugboard" })
     const unsupported = checkJsonContentType(request)
     if (unsupported) return fail(unsupported)
 
     const body = await readJsonBody(request, scope.signal)
-    const parsed = parseMessagesRequest(body, host.options)
+    // count_tokens takes the message body without max_tokens; the parser needs one, so a placeholder stands in
+    // (the count never uses it). A max_tokens the client did send is still validated.
+    const sized = path === COUNT_TOKENS && isRecord(body) && body.max_tokens === undefined ? { ...body, max_tokens: Number.MAX_SAFE_INTEGER } : body
+    const parsed = parseMessagesRequest(sized, host.options)
     if (isPlugError(parsed)) return fail(parsed)
     const catalog = await scope.race(host.loadCatalog())
     const ref = resolveModel(host.options, parsed.request.model, catalog, parsed.reasoningEffort)
     if (isPlugError(ref)) return fail(ref)
     info.model = `${ref.providerID}/${ref.id}${ref.variant ? `#${ref.variant}` : ""}`
+    if (path === COUNT_TOKENS) return sendJson(response, 200, { input_tokens: estimateTokens(parsed.request) })
     // Sampling parameters the model is known to reject are dropped; `top_k` has no neutral
     // equivalent and is always dropped. Both are reported before any response bytes.
     const sampled = host.options.dropUnsupportedParams ? dropRejected(ref, parsed.request.generation) : undefined

package/src/anthropic/tokens.ts

@@ -0,0 +1,42 @@
+/**
+ * Token counts for `count_tokens` (Anthropic #143) and `countTokens` (Gemini #144).
+ *
+ * plugboard has no tokenizer, and the host does not expose the provider's counter, so the count is
+ * an estimate, not the provider's exact number: characters / 4 over everything the model would
+ * read (system prompt, message text, tool-call and tool-result payloads, tool names, descriptions
+ * and JSON schemas), plus a fixed cost per image or file. Real tokenizers differ by model and
+ * language, so the number can be off either way. It is for sizing and budgeting, not billing.
+ */
+import type { PlugPart, PlugRequest } from "../contract.js"
+
+/** Tokens charged for each image or file part, whatever its size (the real cost depends on the size). */
+export const MEDIA_TOKENS = 1600
+const CHARS_PER_TOKEN = 4
+
+const jsonLength = (value: unknown): number => (JSON.stringify(value) ?? "").length
+
+const partChars = (part: PlugPart): number => {
+  switch (part.type) {
+    case "text":
+      return part.text.length
+    case "tool-call":
+      return part.name.length + jsonLength(part.input)
+    case "tool-result":
+      return part.name.length + part.result.length
+    case "media":
+      return 0
+  }
+}
+
+/** The estimated input tokens of a resolved request. Ceiling of characters / 4, plus `MEDIA_TOKENS` per media part. */
+export function estimateTokens(request: Pick<PlugRequest, "system" | "messages" | "tools">): number {
+  let chars = request.system.join("").length
+  let media = 0
+  for (const message of request.messages)
+    for (const part of message.content) {
+      if (part.type === "media") media++
+      else chars += partChars(part)
+    }
+  for (const tool of request.tools) chars += tool.name.length + tool.description.length + jsonLength(tool.parameters)
+  return Math.ceil(chars / CHARS_PER_TOKEN) + media * MEDIA_TOKENS
+}

package/src/config.ts

@@ -2,7 +2,7 @@
 
 import { createHash, timingSafeEqual } from "node:crypto"
 import type { CacheConfig } from "./cache.js"
-import type { PlugError } from "./contract.js"
+import { isPlugError, type PlugError } from "./contract.js"
 import { allowedBy, parseModelRef } from "./models.js"
 import { parseAllowEntry, type RemoteImages } from "./session/media.js"
 import type { HistoryLimits } from "./session/prune.js"
@@ -52,6 +52,16 @@ export interface PlugboardOptions {
   readonly limits?: Limits
   /** Opt-in exact-match response cache (see `src/cache.ts`). Absent: off. */
   readonly cache?: CacheConfig
+  /** Per-app usage statistics (see `src/usage.ts`): recorded and served by `GET /v1/usage` and the RPC. */
+  readonly usage: UsageConfig
+  /** A key that may read every app's usage on `GET /v1/usage`. Compared like app keys; must differ from every one of them. */
+  readonly adminKey?: string
+}
+
+/** Option `usage` after defaults: on, and days of history kept. */
+export interface UsageConfig {
+  readonly enabled: boolean
+  readonly retentionDays: number
 }
 
 export type SystemMode = "prepend" | "append" | "replace"
@@ -99,7 +109,11 @@ const DEFAULTS = {
   requestTimeoutMs: 600_000,
 } as const
 
-const KNOWN = new Set(["listen", "keys", "apps", "models", "aliases", "maxTools", "maxN", "requestTimeoutMs", "remoteImages", "history", "dropUnsupportedParams", "logFormat", "metrics", "modelIds", "limits", "cache"])
+const KNOWN = new Set(["listen", "keys", "adminKey", "apps", "models", "aliases", "maxTools", "maxN", "requestTimeoutMs", "remoteImages", "history", "dropUnsupportedParams", "logFormat", "metrics", "modelIds", "limits", "cache", "usage"])
+const USAGE_KNOWN = new Set(["enabled", "retentionDays"])
+const USAGE_DEFAULTS = { enabled: true, retentionDays: 90 } as const
+/** Ten years: keeps a day-keyed store bounded and a range query well inside its limits. */
+const MAX_RETENTION_DAYS = 3650
 const LIMITS_KNOWN = new Set(["maxConcurrent", "perApp", "apps"])
 const LIMIT_CAP_KNOWN = new Set(["maxConcurrent", "requestsPerMinute"])
 /** Largest cap accepted: far above any provider's limit, and keeps the error messages short. */
@@ -260,6 +274,18 @@ export function appPolicy(options: Pick<PlugboardOptions, "apps">, app: string):
   return Object.hasOwn(options.apps, app) ? options.apps[app] : undefined
 }
 
+function parseUsage(value: unknown): UsageConfig {
+  if (value === undefined) return { ...USAGE_DEFAULTS }
+  if (!isRecord(value)) throw new Error("plugboard option `usage` must be an object")
+  for (const key of Object.keys(value))
+    if (!USAGE_KNOWN.has(key)) throw new Error(`Unknown plugboard option \`usage.${key}\` (known: ${[...USAGE_KNOWN].join(", ")})`)
+  if (value.enabled !== undefined && typeof value.enabled !== "boolean") throw new Error("plugboard option `usage.enabled` must be a boolean")
+  return {
+    enabled: value.enabled !== false,
+    retentionDays: positiveInt(value.retentionDays, "usage.retentionDays", USAGE_DEFAULTS.retentionDays, MAX_RETENTION_DAYS),
+  }
+}
+
 function parseCache(value: unknown, keys: Readonly<Record<string, string>>): CacheConfig | undefined {
   if (value === undefined) return undefined
   if (!isRecord(value)) throw new Error("plugboard option `cache` must be an object with `ttlSeconds`")
@@ -313,6 +339,10 @@ export function parseOptions(raw: unknown): PlugboardOptions {
   digestsOf(keys)
   if (keyEntries.length === 0 && !isLoopbackHost(host))
     throw new Error(`plugboard refuses to listen on non-loopback host \`${host}\` without \`keys\``)
+  if (input.adminKey !== undefined) {
+    if (typeof input.adminKey !== "string" || input.adminKey.length === 0) throw new Error("plugboard option `adminKey` must be a non-empty string (is its {env:VAR} set?)")
+    if (keyEntries.some(([, key]) => key === input.adminKey)) throw new Error("plugboard option `adminKey` must differ from every app key")
+  }
 
   const models = input.models ?? []
   if (!Array.isArray(models)) throw new Error("plugboard option `models` must be an array of strings")
@@ -366,6 +396,7 @@ export function parseOptions(raw: unknown): PlugboardOptions {
 
   const limits = parseLimits(input.limits, keys)
   const cache = parseCache(input.cache, keys)
+  const usage = parseUsage(input.usage)
 
   return {
     listen: { host, port: port ?? DEFAULTS.port },
@@ -385,6 +416,8 @@ export function parseOptions(raw: unknown): PlugboardOptions {
     modelIds: (input.modelIds as ModelIds | undefined) ?? "canonical",
     ...(limits === undefined ? {} : { limits }),
     ...(cache ? { cache } : {}),
+    usage,
+    ...(typeof input.adminKey === "string" ? { adminKey: input.adminKey } : {}),
   }
 }
 
@@ -410,6 +443,18 @@ function digestsOf(keys: Readonly<Record<string, string>>): ReadonlyArray<readon
   return digests
 }
 
+/** Who may read `GET /v1/usage`: the admin key (every app), or one app (`default` when keyless). */
+export type UsageScope = { readonly admin: true } | { readonly admin: false; readonly app: string }
+
+/** The admin key is checked first; any other valid key (or keyless mode) is an app, as `authenticate` decides. */
+export function authenticateUsage(options: PlugboardOptions, authorization: string | undefined): UsageScope | PlugError {
+  const bearer = /^Bearer\s+(\S+)\s*$/i.exec(authorization ?? "")?.[1]
+  if (options.adminKey !== undefined && bearer !== undefined && timingSafeEqual(sha256(bearer), sha256(options.adminKey))) return { admin: true }
+  const auth = authenticate(options, authorization)
+  if (isPlugError(auth)) return auth
+  return { admin: false, app: auth.app }
+}
+
 /** No keys -> app `default`; with keys every request needs `Authorization: Bearer <key>`. */
 export function authenticate(options: PlugboardOptions, authorization: string | undefined): { app: string } | PlugError {
   const entries = digestsOf(options.keys)