opencode-plugboard 0.15.0 → 0.17.0

package/README.md

@@ -30,7 +30,7 @@ export PLUGBOARD_KEY_MY_APP=choose-a-long-random-string
 {
   "plugins": [
     {
-      "package": "opencode-plugboard@0.15.0",
+      "package": "opencode-plugboard@0.17.0",
       "options": {
         "keys": { "my-app": "{env:PLUGBOARD_KEY_MY_APP}" },
         "models": ["anthropic/claude-sonnet-4-6", "github-copilot/*", "opencode-go/glm-5.3-flash"],

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,6 +1,6 @@
 {
   "name": "opencode-plugboard",
-  "version": "0.15.0",
+  "version": "0.17.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.",
@@ -15,7 +15,8 @@
   "homepage": "https://github.com/jjjermiah/opencode-plugboard#readme",
   "main": "./index.ts",
   "exports": {
-    ".": "./index.ts"
+    ".": "./index.ts",
+    "./rpc": "./src/rpc.ts"
   },
   "files": ["index.ts", "src/", "README.md", "LICENSE"],
   "scripts": {
@@ -37,16 +38,21 @@
     "@ai-sdk/anthropic": "4.0.78",
     "@ai-sdk/google": "4.0.93",
     "@ai-sdk/openai": "4.0.91",
+    "@ai-sdk/openai-compatible": "3.0.67",
     "@anthropic-ai/sdk": "0.133.0",
     "@commitlint/cli": "21.2.3",
     "@commitlint/config-conventional": "21.2.3",
     "@google/genai": "2.28.0",
+    "@langchain/anthropic": "1.5.12",
+    "@langchain/google-genai": "2.3.2",
+    "@langchain/openai": "1.6.2",
     "@opencode/plugin": "2.0.26",
     "@types/bun": "1.4.2",
     "@types/escape-html": "^1.0.4",
     "@types/lcov-parse": "1.0.2",
     "@types/node": "^26.6.2",
     "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",

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,
@@ -21,6 +22,7 @@ import {
   checkJsonContentType,
   checkOrigin,
   readJsonBody,
+  sendError,
   sendJson,
   sseWriter,
   type RequestScope,
@@ -32,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"
@@ -58,14 +63,15 @@ 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> {
   const { path, request, response, scope, info } = call
-  const fail = (error: PlugError, close = false) => sendJson(response, error.status, encodeError(error), { close })
+  const fail = (error: PlugError, close = false) => sendError(response, error, encodeError(error), { close })
   if (request.method === "POST") info.route = `POST ${path}`
   response.setHeader("request-id", `req_${crypto.randomUUID().replaceAll("-", "")}`)
 
@@ -84,25 +90,28 @@ export async function serveMessages(host: RouteHost, call: MessagesCall): Promis
   }
 
   async function serve(): Promise<void> {
-    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` })
     const rejected = checkOrigin(request, host.options)
     if (rejected) return fail(rejected)
+    // Authenticate before the method check, so an unauthenticated caller cannot map this path (#137).
     const auth = authenticateRequest(host, request)
     if (isPlugError(auth)) return fail(auth)
     info.app = auth.app
-    if (path === COUNT_TOKENS)
-      return fail({ status: 404, kind: "not_found", code: "not_found", message: "count_tokens is not supported by plugboard" })
+    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` })
     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/completions/response.ts

@@ -44,7 +44,7 @@ const encodeUsage = (usage: PlugUsage) => {
 const prefixOf = (exchange: CompletionsExchange, index: number) => exchange.echo?.[Math.floor(index / exchange.perPrompt)] ?? ""
 
 /** One choice as a complete body: `choices[0]` carries the text, `usage` the totals. */
-async function collectText(events: AsyncIterable<PlugEvent>, exchange: CompletionsExchange, index: number): Promise<{ status: number; body: object }> {
+async function collectText(events: AsyncIterable<PlugEvent>, exchange: CompletionsExchange, index: number): Promise<{ status: number; body: object; retryAfterSeconds?: number }> {
   let text = ""
   let finish: Exclude<PlugFinish, "error"> | undefined
   let usage: PlugUsage | undefined
@@ -63,7 +63,7 @@ async function collectText(events: AsyncIterable<PlugEvent>, exchange: Completio
   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 }
   }
   return {
     status: 200,

package/src/completions/route.ts

@@ -12,7 +12,7 @@
 import type { ServerResponse } from "node:http"
 import { isPlugError, type PlugError, type PlugRequest } from "../contract.js"
 import type { ServedInfo } from "../fallback.js"
-import { sendJson, type RequestScope } from "../http.js"
+import { sendError, type RequestScope } from "../http.js"
 import { resolveModel } from "../models.js"
 import { serveChoices } from "../openai/fanout.js"
 import { encodeError } from "../openai/response.js"
@@ -33,7 +33,7 @@ export interface CompletionsCall {
 }
 
 export async function serveCompletions(host: RouteHost, { app, body, response, scope, info }: CompletionsCall): Promise<void> {
-  const fail = (error: PlugError) => sendJson(response, error.status, encodeError(error))
+  const fail = (error: PlugError) => sendError(response, error, encodeError(error))
 
   const parsed = parseCompletionsRequest(body, host.options)
   if (isPlugError(parsed)) return fail(parsed)

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)

package/src/contract.ts

@@ -153,7 +153,7 @@ export interface PlugError {
   readonly message: string
   readonly code?: string
   readonly param?: string
-  /** Seconds to wait before a retry, for a `Retry-After` header. Set by the limiter (`src/limits.ts`); no route reads it yet. */
+  /** Seconds to wait before a retry, sent as the `Retry-After` header (`sendError` in `src/http.ts`). Set by the limiter (`src/limits.ts`). */
   readonly retryAfterSeconds?: number
 }
 

package/src/discovery.ts

@@ -58,16 +58,34 @@ export interface Endpoint {
   readonly description: string
 }
 
-function endpoints(options: PlugboardOptions): 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). `/v1/usage` and `/metrics` are added only when their options are on.
+ */
+export const ENDPOINTS: ReadonlyArray<Endpoint> = [
+  { method: "GET", path: "/", auth: false, description: "This page." },
+  { method: "GET", path: "/v1", auth: false, description: "This page as JSON." },
+  { method: "GET", path: "/healthz", auth: false, description: "Liveness: {\"ok\":true}." },
+  { method: "GET", path: "/v1/models", auth: true, description: "Models this app may call (OpenAI shape)." },
+  { method: "GET", path: "/v1/models/{id}", auth: true, description: "One model." },
+  { method: "POST", path: "/v1/chat/completions", auth: true, description: "OpenAI Chat Completions." },
+  { 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 [
-    { method: "GET", path: "/", auth: false, description: "This page." },
-    { method: "GET", path: "/v1", auth: false, description: "This page as JSON." },
-    { method: "GET", path: "/healthz", auth: false, description: "Liveness: {\"ok\":true}." },
-    { method: "GET", path: "/v1/models", auth: true, description: "Models this app may call." },
-    { method: "GET", path: "/v1/models/{id}", auth: true, description: "One model." },
-    { method: "POST", path: "/v1/chat/completions", auth: true, description: "OpenAI Chat Completions." },
-    { method: "POST", path: "/v1/responses", auth: true, description: "OpenAI Responses (stateless)." },
-    { method: "GET", path: "/v1/status", auth: true, description: "Runtime status: generations, address, model count, uptime." },
+    ...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." }] : []),
     ...(options.metrics ? [{ method: "GET", path: "/metrics", auth: true, description: "Prometheus metrics." }] : []),
   ]
 }