opencode-plugboard 0.17.0 → 0.19.0

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "opencode-plugboard",
-  "version": "0.17.0",
+  "version": "0.19.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,15 +14,26 @@
   },
   "homepage": "https://github.com/jjjermiah/opencode-plugboard#readme",
   "main": "./index.ts",
+  "types": "./index.ts",
   "exports": {
-    ".": "./index.ts",
-    "./rpc": "./src/rpc.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": {
@@ -32,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",
@@ -47,10 +59,13 @@
     "@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",
@@ -60,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/response.ts

@@ -7,6 +7,7 @@
  * no-op `emit`. Thinking blocks are produced only when the request asked for thinking.
  */
 import type { PlugError, PlugEvent, PlugFinish, PlugUsage } from "../contract.js"
+import { StopHoldback } from "../stop.js"
 
 type ToolCall = Extract<PlugEvent, { type: "tool-call" }>
 
@@ -76,10 +77,6 @@ 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" })
 
@@ -127,10 +124,9 @@ 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 = ""
+  // Text is held back by the longest stop sequence, so a sequence at the end of the answer can be
+  // found and removed before it is sent (src/stop.ts). Without stop sequences nothing is held.
+  const holdback = new StopHoldback(exchange.stop ?? [])
 
   const message = (extra: Record<string, unknown>) => ({
     id,
@@ -162,20 +158,8 @@ export async function runMessage(
     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 releaseHeld = () => delta("text", holdback.release())
+  const text = (chunk: string) => delta("text", holdback.push(chunk))
   const delta = (kind: "text" | "thinking", text: string) => {
     if (text.length === 0) return
     start()
@@ -240,9 +224,8 @@ export async function runMessage(
     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()
+  const { text: rest, matched } = holdback.finish(finish === "stop" && calls === 0)
+  delta("text", rest)
   start()
   close()
   ping()

package/src/anthropic/route.ts

@@ -31,6 +31,7 @@ import { reportServed, type ServedInfo } from "../fallback.js"
 import { resolveModel } from "../models.js"
 import { reportCache } from "../cache.js"
 import { reportPolicy } from "../policy.js"
+import { reportUsage } from "../usage-header.js"
 import { dropRejected } from "../openai/sampling.js"
 import type { RouteHost } from "../openai/route.js"
 import { parseMessagesRequest } from "./request.js"
@@ -135,6 +136,7 @@ export async function serveMessages(host: RouteHost, call: MessagesCall): Promis
         },
         onServed: reportServed(response, info, (served) => void (exchange.model = served.model)),
         onPolicy: reportPolicy(response),
+        onUsage: reportUsage(response, exchange.stream),
         onCache: reportCache(response),
       }),
       scope,

package/src/budgets.ts

@@ -0,0 +1,200 @@
+/**
+ * Per-app budgets (option `budgets`): a `ModelCaller` wrapper that refuses a call with 429
+ * `budget_exceeded` once its app has used a ceiling for the current window.
+ *
+ * Windows are UTC: a calendar day, an ISO week (Monday start) and a calendar month. The check reads
+ * what the usage records already hold for the window (`UsageRecorder.spent`, src/usage.ts): requests
+ * on the model routes that were not refused by a limit or a budget, the tokens of answered calls and
+ * their cost at list prices. A call that crosses a ceiling is still served; the next one is refused.
+ * Calls in flight are not counted until they end, so a burst can pass a ceiling by the calls it
+ * admitted. A call that finds the records unreadable is refused with 503 `budget_unavailable` rather
+ * than let through.
+ *
+ * The check runs before anything else is taken: a refused call holds no concurrency slot and spends
+ * no requests-per-minute count. `index.ts` puts this wrapper outside `withLimits` for that reason.
+ * Crossing 80% of a ceiling logs `budget.warning` once per app, budget and window (and again in the
+ * next window). The warning state lives on the process runtime, so a plugin generation keeps it.
+ */
+
+import type { Budget, BudgetMetric, BudgetWindow, Budgets } from "./config.js"
+import type { CallContext, ModelCaller, PlugError, PlugEvent, PlugRequest } from "./contract.js"
+import { errorMessage, log, logError, logWarn } from "./log.js"
+import { totalTokens, utcDate, type BudgetStatus, type DayRecord, type UsageRecorder } from "./usage.js"
+
+/** What the warnings already logged: `app|metric|window` -> the window's first day. The process-wide state (src/runtime.ts). */
+export interface BudgetState {
+  readonly warned: Map<string, string>
+}
+
+export const createBudgetState = (): BudgetState => ({ warned: new Map() })
+
+export interface BudgetOptions {
+  /** Clock in epoch ms. Tests inject one; the default is `Date.now`. */
+  readonly now?: () => number
+  /** Called once for each refused call (metrics, usage). */
+  readonly onRefused?: (app: string) => void
+}
+
+const DAY_MS = 86_400_000
+const WARN_AT = 0.8
+const METRICS: ReadonlyArray<BudgetMetric> = ["requests", "tokens", "costUsd"]
+const WINDOWS: ReadonlyArray<BudgetWindow> = ["day", "week", "month"]
+const LABEL: Record<BudgetMetric, string> = { requests: "requests", tokens: "tokens", costUsd: "cost (USD)" }
+
+/** The window that holds `at`: its first UTC day (`start`) and the instant the next one begins (`resetsAt`, epoch ms). */
+export function windowAt(window: BudgetWindow, at: number): { readonly start: string; readonly resetsAt: number } {
+  const now = new Date(at)
+  const year = now.getUTCFullYear()
+  const month = now.getUTCMonth()
+  const today = Date.UTC(year, month, now.getUTCDate())
+  if (window === "day") return { start: utcDate(today), resetsAt: today + DAY_MS }
+  if (window === "week") {
+    // getUTCDay counts from Sunday; Monday is 0 here.
+    const monday = today - ((now.getUTCDay() + 6) % 7) * DAY_MS
+    return { start: utcDate(monday), resetsAt: monday + 7 * DAY_MS }
+  }
+  return { start: utcDate(Date.UTC(year, month, 1)), resetsAt: Date.UTC(year, month + 1, 1) }
+}
+
+/** The budget that applies to `app`: `perApp`, with the app's `apps` entry replacing each metric it sets. Undefined when neither sets a metric. */
+export function budgetFor(budgets: Budgets, app: string): Budget | undefined {
+  const own = budgets.apps && Object.hasOwn(budgets.apps, app) ? budgets.apps[app] : undefined
+  const merged: Budget = { ...budgets.perApp, ...own }
+  return METRICS.some((metric) => merged[metric] !== undefined) ? merged : undefined
+}
+
+interface Ceiling {
+  readonly metric: BudgetMetric
+  readonly window: BudgetWindow
+  readonly limit: number
+}
+
+/** Every ceiling the budget sets, in a fixed order: metric, then window. */
+function ceilingsOf(budget: Budget): Ceiling[] {
+  const out: Ceiling[] = []
+  for (const metric of METRICS)
+    for (const window of WINDOWS) {
+      const limit = budget[metric]?.[window]
+      if (limit !== undefined) out.push({ metric, window, limit })
+    }
+  return out
+}
+
+/** What a window's records count against a ceiling. Requests leave out refusals, which `limited` counts. */
+function usedOf(day: DayRecord, metric: BudgetMetric): number {
+  if (metric === "requests") return day.requests - day.limited
+  if (metric === "tokens") return totalTokens(day.tokens)
+  return day.costUsd
+}
+
+interface Spent {
+  readonly day: DayRecord
+  readonly resetsAt: number
+  /** First UTC day of the window. */
+  readonly start: string
+}
+
+/** The records of the window holding `at`, from its first day to today. Memoized per call, so each window is read once. */
+function spentFor(usage: UsageRecorder, app: string, at: number): (window: BudgetWindow) => Promise<Spent> {
+  const seen = new Map<BudgetWindow, Promise<Spent>>()
+  return (window) => {
+    let found = seen.get(window)
+    if (!found) {
+      const { start, resetsAt } = windowAt(window, at)
+      seen.set(window, (found = usage.spent(app, start, utcDate(at)).then((day) => ({ day, resetsAt, start }))))
+    }
+    return found
+  }
+}
+
+/** The state of every ceiling of `budget` for `app` now: what the current window has used, and when it resets. */
+export async function budgetStatus(usage: UsageRecorder, budget: Budget, app: string, at: number): Promise<BudgetStatus[]> {
+  const spent = spentFor(usage, app, at)
+  const rows: BudgetStatus[] = []
+  for (const { metric, window, limit } of ceilingsOf(budget)) {
+    const current = await spent(window)
+    rows.push({ metric, window, limit, used: usedOf(current.day, metric), resetsAt: new Date(current.resetsAt).toISOString() })
+  }
+  return rows
+}
+
+/** The refusal for a call now, or undefined. Logs the warnings the ceilings cross (once each per window). */
+async function check(budget: Budget, app: string, usage: UsageRecorder, state: BudgetState, at: number): Promise<PlugError | undefined> {
+  const spent = spentFor(usage, app, at)
+  const exceeded: string[] = []
+  let resetsAt = 0
+  for (const { metric, window, limit } of ceilingsOf(budget)) {
+    const current = await spent(window)
+    const used = usedOf(current.day, metric)
+    if (used >= limit * WARN_AT) warnOnce(state, app, metric, window, current.start, { used, limit, resetsAt: current.resetsAt })
+    if (used >= limit) {
+      exceeded.push(`${LABEL[metric]} ${window}`)
+      resetsAt = Math.max(resetsAt, current.resetsAt)
+    }
+  }
+  if (exceeded.length === 0) return undefined
+  const retryAfterSeconds = Math.max(1, Math.ceil((resetsAt - at) / 1000))
+  log("request.budget_exceeded", { app, budgets: exceeded.join(", "), retryAfterSeconds })
+  return { status: 429, kind: "rate_limit", code: "budget_exceeded", message: `Budget for ${app} exceeded: ${exceeded.join(", ")}`, retryAfterSeconds }
+}
+
+function warnOnce(
+  state: BudgetState,
+  app: string,
+  metric: BudgetMetric,
+  window: BudgetWindow,
+  start: string,
+  figures: { readonly used: number; readonly limit: number; readonly resetsAt: number },
+): void {
+  const key = `${app}|${metric}|${window}`
+  if (state.warned.get(key) === start) return
+  state.warned.set(key, start)
+  logWarn("budget.warning", { app, budget: metric, window, used: figures.used, limit: figures.limit, resetsAt: new Date(figures.resetsAt).toISOString() })
+}
+
+/**
+ * The budget caller: each call of an app with a budget is checked first. With no budget for the app,
+ * no usage recorder, or no budgets at all, the caller is returned as it is. `budgets` is the parsed option.
+ */
+export function withBudgets(
+  inner: ModelCaller,
+  budgets: Budgets | undefined,
+  usage: UsageRecorder | undefined,
+  state: BudgetState,
+  options: BudgetOptions = {},
+): ModelCaller {
+  const now = options.now ?? Date.now
+  return {
+    stream(request, context) {
+      const budget = budgets === undefined ? undefined : budgetFor(budgets, context.app)
+      if (!usage || !budget) return inner.stream(request, context)
+      return admit(inner, budget, usage, state, now, options.onRefused, request, context)
+    },
+  }
+}
+
+async function* admit(
+  inner: ModelCaller,
+  budget: Budget,
+  usage: UsageRecorder,
+  state: BudgetState,
+  now: () => number,
+  onRefused: BudgetOptions["onRefused"],
+  request: PlugRequest,
+  context: CallContext,
+): AsyncGenerator<PlugEvent> {
+  const app = context.app
+  let refusal: PlugError | undefined
+  try {
+    refusal = await check(budget, app, usage, state, now())
+  } catch (error) {
+    logError("budget.check_failed", { app, error: errorMessage(error) })
+    refusal = { status: 503, kind: "server", code: "budget_unavailable", message: "Could not read the usage records for the budget check" }
+  }
+  if (refusal) {
+    if (refusal.status === 429) onRefused?.(app)
+    yield { type: "error", error: refusal }
+    return
+  }
+  for await (const event of inner.stream(request, context)) yield event
+}

package/src/completions/request.ts

@@ -97,6 +97,7 @@ export function parseCompletionsRequest(body: unknown, options: PlugboardOptions
       includeUsage: streamOptions.include_usage === true,
       perPrompt: n,
       ...(body.echo === true ? { echo: prompts } : {}),
+      ...(generation.stop ? { stop: generation.stop } : {}),
     },
     ...(typeof body.reasoning_effort === "string" ? { reasoningEffort: body.reasoning_effort } : {}),
   }

package/src/completions/response.ts

@@ -8,6 +8,7 @@
 import type { PlugError, PlugEvent, PlugFinish, PlugUsage } from "../contract.js"
 import type { ChoiceCodec } from "../openai/fanout.js"
 import { encodeError, type StreamChoice, type StreamResult } from "../openai/response.js"
+import { StopHoldback, stripStopTail } from "../stop.js"
 
 /** What the encoders need besides the model events; the request decoder produces it, the model call never sees it. */
 export interface CompletionsExchange {
@@ -20,6 +21,8 @@ export interface CompletionsExchange {
   readonly perPrompt: number
   /** `echo`: each prompt, written ahead of the text of its choices. */
   readonly echo?: ReadonlyArray<string>
+  /** The request's `stop`. A plain stop whose text ends with one of these leaves the sequence out (src/stop.ts). */
+  readonly stop?: ReadonlyArray<string>
 }
 
 const FINISH_REASONS: Record<Exclude<PlugFinish, "error">, string> = {
@@ -65,6 +68,7 @@ async function collectText(events: AsyncIterable<PlugEvent>, exchange: Completio
     const error = failure ?? noFinish()
     return { status: error.status, body: encodeError(error), retryAfterSeconds: error.retryAfterSeconds }
   }
+  if (finish === "stop") text = stripStopTail(text, exchange.stop ?? []).text
   return {
     status: 200,
     body: {
@@ -106,6 +110,8 @@ async function streamText(
     const prefix = prefixOf(exchange, choice.index)
     if (prefix.length > 0) chunk(prefix)
   }
+  // A stop sequence is held back until the finish decides it (src/stop.ts).
+  const holdback = new StopHoldback(exchange.stop ?? [])
   let finish: Exclude<PlugFinish, "error"> | undefined
   let usage: PlugUsage | undefined
   let failure: PlugError | undefined
@@ -120,12 +126,15 @@ async function streamText(
       else finish = event.reason
     } else if (event.type === "text-delta" && event.text.length > 0) {
       start()
-      chunk(event.text)
+      const out = holdback.push(event.text)
+      if (out.length > 0) chunk(out)
     }
   }
   failure ??= finish ? undefined : noFinish()
   if (failure) return { failure, started }
   start()
+  const rest = holdback.finish(finish === "stop").text
+  if (rest.length > 0) chunk(rest)
   chunk("", FINISH_REASONS[finish!])
   return { started, ...(usage ? { usage } : {}) }
 }

package/src/config.ts

@@ -50,6 +50,8 @@ export interface PlugboardOptions {
   readonly modelIds: ModelIds
   /** Concurrency caps and requests per minute per app (see `src/limits.ts`). Absent: unlimited. */
   readonly limits?: Limits
+  /** Per-app budgets (see `src/budgets.ts`): ceilings on requests, tokens and cost per UTC day, week or month. Needs `usage`. Absent: no budgets. */
+  readonly budgets?: Budgets
   /** 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. */
@@ -99,6 +101,34 @@ export interface Limits {
   readonly apps?: Readonly<Record<string, LimitCaps>>
 }
 
+/** What a budget counts: HTTP requests on the model routes (refusals by `limits` or budgets left out), tokens, or cost in USD. */
+export type BudgetMetric = "requests" | "tokens" | "costUsd"
+/** The windows a budget resets on: a UTC calendar day, an ISO week (Monday start) or a calendar month (UTC). */
+export type BudgetWindow = "day" | "week" | "month"
+
+/** Ceilings per window. A window that is not set has no ceiling. */
+export interface BudgetWindows {
+  readonly day?: number
+  readonly week?: number
+  readonly month?: number
+}
+
+/** One set of ceilings. A metric that is not set is unlimited. `costUsd` is an estimate at list prices. */
+export interface Budget {
+  readonly requests?: BudgetWindows
+  readonly tokens?: BudgetWindows
+  readonly costUsd?: BudgetWindows
+}
+
+/**
+ * Option `budgets`. `perApp` applies to every app; `apps.<name>` replaces `perApp` metric by metric for
+ * that app (its `requests` replaces `perApp.requests`, the other metrics still come from `perApp`).
+ */
+export interface Budgets {
+  readonly perApp?: Budget
+  readonly apps?: Readonly<Record<string, Budget>>
+}
+
 export const APP_NAME_PATTERN = /^[a-z0-9-]+$/
 export const DEFAULT_APP = "default"
 const DEFAULTS = {
@@ -109,7 +139,7 @@ const DEFAULTS = {
   requestTimeoutMs: 600_000,
 } as const
 
-const KNOWN = new Set(["listen", "keys", "adminKey", "apps", "models", "aliases", "maxTools", "maxN", "requestTimeoutMs", "remoteImages", "history", "dropUnsupportedParams", "logFormat", "metrics", "modelIds", "limits", "cache", "usage"])
+const KNOWN = new Set(["listen", "keys", "adminKey", "apps", "models", "aliases", "maxTools", "maxN", "requestTimeoutMs", "remoteImages", "history", "dropUnsupportedParams", "logFormat", "metrics", "modelIds", "limits", "budgets", "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. */
@@ -304,6 +334,68 @@ function parseCache(value: unknown, keys: Readonly<Record<string, string>>): Cac
   return { ttlSeconds, maxEntries, maxBytes, apps: [...new Set(value.apps as string[])] }
 }
 
+const BUDGET_METRICS: ReadonlyArray<BudgetMetric> = ["requests", "tokens", "costUsd"]
+const BUDGET_WINDOWS: ReadonlyArray<BudgetWindow> = ["day", "week", "month"]
+/** The most days a window can span: a month is up to 31. Retention must keep at least that many, or a budget would count from pruned records. */
+const WINDOW_DAYS: Readonly<Record<BudgetWindow, number>> = { day: 1, week: 7, month: 31 }
+
+/** The longest window any ceiling of `budgets` uses, in days (0 without budgets). */
+function widestWindowDays(budgets: Budgets | undefined): number {
+  let most = 0
+  for (const budget of [budgets?.perApp, ...Object.values(budgets?.apps ?? {})])
+    for (const metric of [budget?.requests, budget?.tokens, budget?.costUsd])
+      for (const window of Object.keys(metric ?? {}) as BudgetWindow[]) most = Math.max(most, WINDOW_DAYS[window])
+  return most
+}
+
+/**
+ * Validates `budgets`: `{ perApp?, apps? }`, each a budget of `requests`, `tokens` and `costUsd`, each of
+ * those a map of window (`day`, `week`, `month`) to a positive limit. Counts are integers, costs any positive
+ * number of USD. An `apps` entry must name a configured app, as in `limits`.
+ */
+function parseBudgets(raw: unknown, keys: Readonly<Record<string, string>>): Budgets | undefined {
+  if (raw === undefined) return undefined
+  if (!isRecord(raw)) throw new Error("plugboard option `budgets` must be an object")
+  for (const key of Object.keys(raw))
+    if (key !== "perApp" && key !== "apps") throw new Error(`Unknown plugboard option \`budgets.${key}\` (known: perApp, apps)`)
+
+  const budget = (value: unknown, at: string): Budget => {
+    if (!isRecord(value)) throw new Error(`plugboard option \`${at}\` must be an object`)
+    for (const key of Object.keys(value))
+      if (!BUDGET_METRICS.includes(key as BudgetMetric)) throw new Error(`Unknown plugboard option \`${at}.${key}\` (known: ${BUDGET_METRICS.join(", ")})`)
+    const parsed: Record<string, Record<string, number>> = {}
+    for (const metric of BUDGET_METRICS) {
+      const windows = value[metric]
+      if (windows === undefined) continue
+      const field = `${at}.${metric}`
+      if (!isRecord(windows)) throw new Error(`plugboard option \`${field}\` must be an object of window (${BUDGET_WINDOWS.join(", ")}) to limit`)
+      const limits: Record<string, number> = {}
+      for (const window of Object.keys(windows)) {
+        if (!BUDGET_WINDOWS.includes(window as BudgetWindow)) throw new Error(`Unknown plugboard option \`${field}.${window}\` (known: ${BUDGET_WINDOWS.join(", ")})`)
+        const limit = windows[window]
+        if (limit === undefined) continue
+        if (metric === "costUsd") {
+          if (typeof limit !== "number" || !Number.isFinite(limit) || limit <= 0) throw new Error(`plugboard option \`${field}.${window}\` must be a positive number of USD`)
+          limits[window] = limit
+        } else limits[window] = positiveInt(limit, `${field}.${window}`, 0, Number.MAX_SAFE_INTEGER)
+      }
+      parsed[metric] = limits
+    }
+    return parsed as Budget
+  }
+
+  const perApp = raw.perApp === undefined ? undefined : budget(raw.perApp, "budgets.perApp")
+  if (raw.apps !== undefined && !isRecord(raw.apps)) throw new Error("plugboard option `budgets.apps` must be an object of app name -> budget")
+  const apps: Record<string, Budget> = {}
+  for (const [app, value] of Object.entries(isRecord(raw.apps) ? raw.apps : {})) {
+    const at = `budgets.apps.${app}`
+    const configured = app === DEFAULT_APP ? Object.keys(keys).length === 0 : Object.hasOwn(keys, app)
+    if (!configured) throw new Error(`plugboard option \`${at}\` must name a configured app (a key in \`keys\`; \`${DEFAULT_APP}\` only without keys)`)
+    apps[app] = budget(value, at)
+  }
+  return { ...(perApp === undefined ? {} : { perApp }), ...(raw.apps === undefined ? {} : { apps }) }
+}
+
 /** Validates raw plugin options and applies defaults. Throws `Error` with an actionable message. */
 export function parseOptions(raw: unknown): PlugboardOptions {
   if (raw !== undefined && raw !== null && !isRecord(raw)) throw new Error("plugboard options must be an object")
@@ -397,6 +489,10 @@ export function parseOptions(raw: unknown): PlugboardOptions {
   const limits = parseLimits(input.limits, keys)
   const cache = parseCache(input.cache, keys)
   const usage = parseUsage(input.usage)
+  const budgets = parseBudgets(input.budgets, keys)
+  if (budgets !== undefined && !usage.enabled) throw new Error("plugboard option `budgets` needs `usage` enabled: budgets are counted from the usage records")
+  if (budgets !== undefined && usage.retentionDays < widestWindowDays(budgets))
+    throw new Error(`plugboard option \`usage.retentionDays\` must be at least ${widestWindowDays(budgets)} for the budget windows in use (a month is 31 days, a week 7): older days are deleted and would stop counting`)
 
   return {
     listen: { host, port: port ?? DEFAULTS.port },
@@ -417,6 +513,7 @@ export function parseOptions(raw: unknown): PlugboardOptions {
     ...(limits === undefined ? {} : { limits }),
     ...(cache ? { cache } : {}),
     usage,
+    ...(budgets === undefined ? {} : { budgets }),
     ...(typeof input.adminKey === "string" ? { adminKey: input.adminKey } : {}),
   }
 }

package/src/contract.ts

@@ -186,6 +186,20 @@ export interface CallContext {
   readonly onCache?: (result: "hit" | "miss") => void
   /** Bypass the response cache for this call. Fan-out sets it: each choice of `n` above 1 repeats one request and must be a fresh sample. */
   readonly noCache?: boolean
+  /**
+   * Called once per answered call, before its finish event, when usage recording is on (`withUsage`,
+   * src/usage.ts): the call's tokens and USD cost. Front-ends set `x-plugboard-usage` from it while the
+   * headers are open, so a stream (headers sent first) never gets it.
+   */
+  readonly onUsage?: (totals: CallTotals) => void
+}
+
+/** One answered call's totals for the caller: `inputTokens` and `outputTokens` as the response body reports them (cache reads inside input, reasoning inside output), and `costUsd` when the model has a price. */
+export interface CallTotals {
+  readonly inputTokens: number
+  readonly outputTokens: number
+  readonly cacheReadTokens: number
+  readonly costUsd?: number
 }
 
 /** The target of an alias that answered: `provider/model[#variant]`, and the targets tried before it. */