opencode-plugboard 0.17.0 → 0.19.0

package/src/dashboard/assets.ts

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

package/src/dashboard/page.ts

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

package/src/discovery.ts

@@ -61,7 +61,7 @@ export interface Endpoint {
 /**
  * Every endpoint plugboard serves, in the order the document lists them. Dispatch lives in
  * `src/openai/route.ts` and the front-end routes; `test/http/discovery.test.ts` probes each served
- * route and fails when this list omits one (#136). `/v1/usage` and `/metrics` are added only when their options are on.
+ * route and fails when this list omits one (#136). `/v1/usage`, `/dashboard` and `/metrics` are added only when their options are on.
  */
 export const ENDPOINTS: ReadonlyArray<Endpoint> = [
   { method: "GET", path: "/", auth: false, description: "This page." },
@@ -85,7 +85,12 @@ export const ENDPOINTS: ReadonlyArray<Endpoint> = [
 function endpoints(options: PlugboardOptions): ReadonlyArray<Endpoint> {
   return [
     ...ENDPOINTS,
-    ...(options.usage.enabled ? [{ method: "GET", path: "/v1/usage", auth: true, description: "Per-app usage by day: requests, tokens, cost, latency. The admin key reads every app." }] : []),
+    ...(options.usage.enabled
+      ? [
+          { method: "GET", path: "/v1/usage", auth: true, description: "Per-app usage by day: requests, tokens, cost, latency. The admin key reads every app." },
+          { method: "GET", path: "/dashboard", auth: false, description: "Usage dashboard page. Its data needs a key (`/v1/usage`)." },
+        ]
+      : []),
     ...(options.metrics ? [{ method: "GET", path: "/metrics", auth: true, description: "Prometheus metrics." }] : []),
   ]
 }
@@ -238,6 +243,7 @@ export function renderDiscoveryHtml(doc: Discovery): string {
     const more = doc.catalog.moreProviders ? `<p>${escapeHtml(doc.catalog.moreProviders)} more providers not listed.</p>` : ""
     sections.push(`<h2>Catalog</h2><table><tr><th>Provider</th><th>Models</th><th>Examples</th></tr>${rows}</table>${more}`)
   }
+  if (doc.endpoints.some((endpoint) => endpoint.path === "/dashboard")) sections.push(`<p><a href="/dashboard">Usage dashboard</a></p>`)
   sections.push(`<h2>Try it</h2>${pre(doc.example.curl)}`)
   sections.push(
     `<h2>Endpoints</h2><table><tr><th>Method</th><th>Path</th><th>Key</th><th></th></tr>${doc.endpoints

package/src/gemini/request.ts

@@ -439,6 +439,7 @@ export function parseGeminiRequest(model: string, stream: boolean, body: unknown
       stream,
       ...(respond ? { structuredTool: RESPOND_TOOL, ...(format.wrap ? { wrapped: true } : {}), ...(withCallerTools ? { callerTools: true } : {}) } : {}),
       ...(format.instruction ? { jsonObject: true } : {}),
+      ...(generation.stop ? { stop: generation.stop } : {}),
     },
     ...(reasoningEffort ? { reasoningEffort } : {}),
   }

package/src/gemini/response.ts

@@ -9,6 +9,7 @@
 import type { PlugError, PlugErrorKind, PlugEvent, PlugFinish, PlugUsage } from "../contract.js"
 import type { ListedModel } from "../models.js"
 import { unfence } from "../openai/response.js"
+import { StopHoldback } from "../stop.js"
 import { WRAP_KEY } from "./request.js"
 
 type ToolCall = Extract<PlugEvent, { type: "tool-call" }>
@@ -30,6 +31,8 @@ export interface GeminiExchange {
   readonly callerTools?: boolean
   /** `responseMimeType: application/json` without a schema: a single code fence around JSON text is stripped. */
   readonly jsonObject?: boolean
+  /** The request's `generationConfig.stopSequences`. A plain stop whose text ends with one of these leaves the sequence out (src/stop.ts). Not applied to structured output. */
+  readonly stop?: ReadonlyArray<string>
 }
 
 /** How an exchange ended. Nothing was emitted when `failure` is set and `started` is false: the caller answers with a real HTTP error. */
@@ -160,10 +163,18 @@ export async function runGenerate(events: AsyncIterable<PlugEvent>, exchange: Ge
     else parts.push(part)
     emit(envelope([part]))
   }
+  // A stop sequence is held back until the finish decides it (src/stop.ts). Structured output has none.
+  const holdback = exchange.structuredTool === undefined ? new StopHoldback(exchange.stop ?? []) : undefined
   const text = (delta: string) => {
-    if (delta.length > 0) push({ text: delta })
+    const out = holdback ? holdback.push(delta) : delta
+    if (out.length > 0) push({ text: out })
+  }
+  const releaseHeld = () => {
+    const rest = holdback?.release() ?? ""
+    if (rest.length > 0) push({ text: rest })
   }
   const toolCall = (call: ToolCall) => {
+    releaseHeld()
     push({ functionCall: { name: call.name, args: argsOf(call.input) } })
     calls++
   }
@@ -221,6 +232,10 @@ export async function runGenerate(events: AsyncIterable<PlugEvent>, exchange: Ge
   failure ??= finish ? (passthrough ? undefined : structuredFailure(exchange, finish, answered)) : noFinish()
   if (failure) return { failure, started }
   flush()
+  if (holdback) {
+    const rest = holdback.finish(finish === "stop" && calls === 0).text
+    if (rest.length > 0) push({ text: rest })
+  }
   if (held && !passthrough) text(structuredText(exchange, held))
   const candidate = { finishReason: FINISH_REASONS[finish!] }
   const extra = usage ? { usageMetadata: encodeUsage(usage) } : {}

package/src/gemini/route.ts

@@ -21,6 +21,7 @@ import { boundEvents, checkJsonContentType, readJsonBody, sendError, sendJson, s
 import { listAvailableModels, resolveModel } from "../models.js"
 import { reportCache } from "../cache.js"
 import { reportPolicy } from "../policy.js"
+import { reportUsage } from "../usage-header.js"
 import type { RouteHost } from "../openai/route.js"
 import { dropRejected } from "../openai/sampling.js"
 import { estimateTokens } from "../anthropic/tokens.js"
@@ -162,6 +163,7 @@ export async function serveGemini(host: RouteHost, { match, request, url, app, r
       },
       onServed: reportServed(response, info, (served) => void (exchange.model = served.model)),
       onPolicy: reportPolicy(response),
+      onUsage: reportUsage(response, match.stream),
       onCache: reportCache(response),
     }),
     scope,

package/src/log.ts

@@ -142,5 +142,8 @@ export const log = (event: string, fields?: LogFields): void => state().logger.i
 
 export const logError = (event: string, fields?: LogFields): void => state().logger.error(record(event, fields))
 
+/** A line for something that needs attention but did not fail a request (a budget at 80%). Info-level destination, `warn` in the level field. */
+export const logWarn = (event: string, fields?: LogFields): void => state().logger.warn(record(event, fields))
+
 /** The message of a thrown value, without its stack or attached properties. */
 export const errorMessage = (error: unknown): string => (error instanceof Error ? error.message : String(error))

package/src/metrics.ts

@@ -62,8 +62,8 @@ export interface Metrics {
   dropped(params: ReadonlyArray<string>): void
   /** A model call failed before any output and was retried on the next target of its alias. */
   fallback(app: string): void
-  /** A call was refused with 429 by a concurrency cap (`concurrency`) or a requests-per-minute limit (`rate`). */
-  limited(app: string, reason: "concurrency" | "rate"): void
+  /** A call was refused with 429 by a concurrency cap (`concurrency`), a requests-per-minute limit (`rate`) or a budget (`budget`). */
+  limited(app: string, reason: "concurrency" | "rate" | "budget"): void
   /** A call the response cache applied to: a stored answer replayed (`hit`) or the model run (`miss`). */
   cache(app: string, result: "hit" | "miss"): void
   /** One history sweep ended. */
@@ -110,7 +110,7 @@ export function createMetrics(): Metrics {
   })
   const limited = new Counter({
     name: "plugboard_limited_total",
-    help: "Model calls refused with 429 by a concurrency cap or a requests-per-minute limit, by app and reason.",
+    help: "Model calls refused with 429 by a concurrency cap, a requests-per-minute limit or a budget, by app and reason.",
     labelNames: ["app", "reason"],
     registers: [registry],
   })

package/src/openai/fanout.ts

@@ -25,6 +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 { reportUsage } from "../usage-header.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"
@@ -169,6 +170,8 @@ export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls
     if (calls.length === 1) codec.setModel(s.model)
   })
   const policy = reportPolicy(response)
+  // One header for all choices: each answered call adds its tokens and cost (`x-plugboard-usage`, #52).
+  const usageHeader = reportUsage(response, codec.stream)
   // Each choice is a fresh sample: the response cache never serves or stores fan-out calls.
   const cache = reportCache(response)
   const open = (index: number) =>
@@ -183,6 +186,7 @@ export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls
         },
         onServed: served,
         onPolicy: policy,
+        onUsage: usageHeader,
         onCache: cache,
         noCache: calls.length > 1,
       }),

package/src/openai/request.ts

@@ -339,6 +339,7 @@ export function parseChatRequest(body: unknown, options: PlugboardOptions): Pars
       includeUsage: streamOptions.include_usage === true,
       ...(respond ? { structuredTool: RESPOND_TOOL, ...(withCallerTools ? { callerTools: true } : {}) } : {}),
       ...(format.instruction ? { jsonObject: true } : {}),
+      ...(generation.stop ? { stop: generation.stop } : {}),
     },
     ...(typeof body.reasoning_effort === "string" ? { reasoningEffort: body.reasoning_effort } : {}),
   }

package/src/openai/response.ts

@@ -6,6 +6,7 @@
  */
 import type { PlugError, PlugErrorKind, PlugEvent, PlugFinish, PlugUsage } from "../contract.js"
 import type { ListedModel } from "../models.js"
+import { StopHoldback, stripStopTail } from "../stop.js"
 
 type ToolCall = Extract<PlugEvent, { type: "tool-call" }>
 
@@ -33,6 +34,8 @@ export interface OpenAiExchange {
    * stripped from the content (`unfence`).
    */
   readonly jsonObject?: boolean
+  /** The request's `stop`. A plain stop whose text ends with one of these leaves the sequence out (src/stop.ts). Not applied to structured output. */
+  readonly stop?: ReadonlyArray<string>
 }
 
 /** How a streamed exchange ended. Nothing was written when `failure` is set and `started` is false: the caller answers with a real HTTP error. */
@@ -219,6 +222,7 @@ export async function collectCompletion(
     const error = failure ?? noFinish()
     return { status: error.status, body: encodeError(error), retryAfterSeconds: error.retryAfterSeconds }
   }
+  if (finish === "stop" && calls.length === 0 && exchange.structuredTool === undefined) text = stripStopTail(text, exchange.stop ?? []).text
 
   const answer = calls.find((call) => structured.isAnswer(exchange, call))
   const others = calls.filter((call) => !structured.isAnswer(exchange, call))
@@ -309,6 +313,12 @@ export async function streamCompletion(
     started = true
     chunk({ role: "assistant", content: "" })
   }
+  // A stop sequence is held back until the finish decides it (src/stop.ts). Structured output has none.
+  const holdback = exchange.structuredTool === undefined ? new StopHoldback(exchange.stop ?? []) : undefined
+  const send = (text: string) => {
+    const out = holdback ? holdback.push(text) : text
+    if (out.length > 0) chunk({ content: out })
+  }
   // json_object: text that opens with a backtick may be a fenced answer, so it waits (as `pending`)
   // until a tool call or the finish shows the whole text; anything else streams as it comes. A
   // fenced answer therefore arrives as one chunk.
@@ -319,7 +329,7 @@ export async function streamCompletion(
     const text = unfence(pending)
     pending = ""
     start()
-    chunk({ content: text })
+    send(text)
   }
 
   for await (const event of events) {
@@ -359,10 +369,14 @@ export async function streamCompletion(
       }
       continue
     }
-    if (event.type !== "text-delta") flush()
+    if (event.type !== "text-delta") {
+      flush()
+      const rest = holdback?.release() ?? ""
+      if (rest.length > 0) chunk({ content: rest })
+    }
     start()
     if (event.type === "text-delta") {
-      if (event.text.length > 0) chunk({ content: event.text })
+      send(event.text)
     } else {
       // Tool calls arrive whole, so each goes out as one chunk with the next index.
       chunk({ tool_calls: [{ index: calls++, id: event.id, type: "function", function: { name: event.name, arguments: args(event.input) } }] })
@@ -382,6 +396,10 @@ export async function streamCompletion(
   }
   flush()
   start()
+  if (holdback) {
+    const rest = holdback.finish(finish === "stop" && calls === 0).text
+    if (rest.length > 0) chunk({ content: rest })
+  }
   if (held && isStructured) chunk({ content: structured.content(held) })
   chunk({}, finishReason(finish!, calls, isStructured))
   if (choice) return { started, ...(usage ? { usage } : {}) }

package/src/openai/route.ts

@@ -3,7 +3,8 @@
  * `POST /v1/chat/completions` (`n` > 1 through `./fanout.ts`), and the dispatch of `POST /v1/responses`
  * and `POST /v1/completions` to `src/responses/route.ts` and `src/completions/route.ts`.
  * Observability and first-run routes (`src/discovery.ts`, `src/metrics.ts`): `GET /` and `GET /v1`
- * (keyless discovery), the authenticated `GET /v1/status`, and `GET /metrics` (option `metrics`).
+ * (keyless discovery), the authenticated `GET /v1/status`, `GET /metrics` (option `metrics`), and the
+ * usage dashboard `GET /dashboard` with its assets (option `usage`, `src/dashboard/`).
  *
  * The flow is: establish cancellation and the deadline, check origin, authenticate, parse, resolve
  * the model, call the ModelCaller, encode. Parsing, policy and encoding are imported directly;
@@ -45,11 +46,15 @@ import { NO_APP, outcomeLabel, type Metrics } from "../metrics.js"
 import { filterByCapability, listAvailableModels, parseCapability, resolveModel } from "../models.js"
 import { reportCache } from "../cache.js"
 import { reportPolicy } from "../policy.js"
+import { reportUsage } from "../usage-header.js"
 import { isMessagesPath, serveMessages } from "../anthropic/route.js"
 import { serveCompletions } from "../completions/route.js"
 import { serveResponses } from "../responses/route.js"
 import { liveOptions, processMetrics, processStatus, type RuntimeStatus } from "../runtime.js"
+import { budgetFor, budgetStatus } from "../budgets.js"
 import type { UsageRecorder } from "../usage.js"
+import { DASHBOARD_ROUTES } from "../dashboard/page.js"
+import { serveDashboard } from "../dashboard/assets.js"
 import { chatCodec, serveChoices } from "./fanout.js"
 import { parseChatRequest } from "./request.js"
 import { collectCompletion, encodeError, encodeModelList, streamCompletion } from "./response.js"
@@ -120,7 +125,10 @@ export function createOpenAiRoute(routeHost: RouteHost) {
   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") || (host.usage !== undefined && route === "GET /v1/usage")
+    KNOWN_ROUTES.includes(route) ||
+    DISCOVERY_ROUTES.includes(route) ||
+    (metrics !== undefined && route === "GET /metrics") ||
+    (host.usage !== undefined && (route === "GET /v1/usage" || DASHBOARD_ROUTES.has(route)))
   /** Responses to Gemini routes: errors there use Google's body. */
   const googleErrors = new WeakSet<ServerResponse>()
   const fail = (response: ServerResponse, error: PlugError, close = false) =>
@@ -148,7 +156,9 @@ export function createOpenAiRoute(routeHost: RouteHost) {
     const path = url.pathname
     const modelId = request.method === "GET" && path.startsWith(MODEL_PREFIX) && path.length > MODEL_PREFIX.length ? decodeSegment(path.slice(MODEL_PREFIX.length)) : undefined
     const gemini = matchGeminiRoute(request.method, path)
-    if (gemini) googleErrors.add(response)
+    // Any /v1beta path is Google's API, even one that matches no Gemini route (#150): its errors use Google's body.
+    const googleShaped = gemini !== undefined || path === "/v1beta" || path.startsWith("/v1beta/")
+    if (googleShaped) googleErrors.add(response)
     const route = gemini?.route ?? `${request.method} ${modelId !== undefined ? "/v1/models/{id}" : path}`
     // Arbitrary client paths stay out of the log.
     info.route = gemini || modelId !== undefined || known(route) || route === "GET /healthz" ? route : "unknown"
@@ -176,15 +186,27 @@ export function createOpenAiRoute(routeHost: RouteHost) {
       return sendText(response, 200, "text/html; charset=utf-8", renderDiscoveryHtml(doc), PAGE_HEADERS)
     }
 
+    // The usage dashboard (#141): a page and its files, keyless like the discovery pages. Its data comes from `GET /v1/usage`, behind a key.
+    if (host.usage && DASHBOARD_ROUTES.has(route)) return serveDashboard(request, response, route)
+
     // Usage has its own credentials: the admin key reads every app, any other key only its own app (`authenticateUsage`).
     if (route === "GET /v1/usage" && host.usage) return serveUsage(request, response, url, host.usage, info)
 
     // Authenticate before anything reveals which routes exist: an unauthenticated caller sees 401 for every path but /healthz and the first-run pages.
     // Gemini clients also send the key as `x-goog-api-key` or `?key=` (see `geminiAuthorization`).
-    const auth = authenticate(liveOptions(host.options), gemini ? geminiAuthorization(request, url) : request.headers.authorization)
+    const auth = authenticate(liveOptions(host.options), googleShaped ? geminiAuthorization(request, url) : request.headers.authorization)
     if (isPlugError(auth)) return fail(response, auth)
     info.app = auth.app
 
+    // A /v1beta path no Gemini route matches: the AI SDK and LangChain send a model id with a slash and no `models/` prefix (#150).
+    if (googleShaped && !gemini)
+      return fail(response, {
+        status: 404,
+        kind: "not_found",
+        code: "not_found",
+        message: `No Gemini route for ${request.method} ${path}. Expected POST /v1beta/models/{model}:generateContent or POST /v1beta/models/{model}:streamGenerateContent; the path must start with /v1beta/models/. GET /v1beta/models lists the models.`,
+      })
+
     if (!gemini && modelId === undefined && !known(route)) {
       return fail(response, {
         status: 404,
@@ -265,6 +287,7 @@ export function createOpenAiRoute(routeHost: RouteHost) {
         // An alias with fallbacks: report which target answered, and echo it as the response model.
         onServed: reportServed(response, info, (served) => void (exchange.model = served.model)),
         onPolicy: reportPolicy(response),
+        onUsage: reportUsage(response, exchange.stream),
         onCache: reportCache(response),
       }),
       scope,
@@ -309,6 +332,14 @@ export function createOpenAiRoute(routeHost: RouteHost) {
       app: who.admin ? app : who.app,
     })
     if (isPlugError(report)) return fail(response, report)
+    // Each app's budget state, read from its current window rather than from the report's range (src/budgets.ts).
+    if (host.options.budgets) {
+      const at = Date.now()
+      for (const [name, entry] of Object.entries(report.apps)) {
+        const budget = budgetFor(host.options.budgets, name)
+        if (budget) entry.budgets = await budgetStatus(usage, budget, name, at)
+      }
+    }
     return sendJson(response, 200, report)
   }
 

package/src/responses/request.ts

@@ -2,10 +2,11 @@
  * OpenAI Responses request -> neutral `PlugRequest` plus the `ResponsesExchange` the response
  * encoder needs.
  *
- * Pure function: no I/O. Stateless subset: the caller sends the whole conversation in `input`
- * each time, which is how history already works. Anything that needs server-side state
- * (`previous_response_id`, `conversation`, `item_reference`, `background`) or a hosted tool is
- * rejected with 400 `unsupported_parameter` naming the field. The route resolves `model` to a
+ * Pure function: no I/O. The caller sends the whole conversation in `input` each time, which is
+ * how history already works. An `item_reference` is resolved through the `resolve` argument (the
+ * route passes the per-app store of recent answers, src/responses/store.ts; #147). Anything else that
+ * needs server-side state (`previous_response_id`, `conversation`, `background`) or a hosted tool
+ * is rejected with 400 `unsupported_parameter` naming the field. The route resolves `model` to a
  * `ModelRef` afterwards, which is why the request omits `ref`.
  */
 import type { PlugboardOptions } from "../config.js"
@@ -121,7 +122,23 @@ const assistantText = (content: unknown, param: string): string | PlugError => {
  * assistant message, the shape the Chat Completions front-end produces, so a parallel-call turn
  * is one message followed by its results.
  */
-const parseInput = (input: unknown): { system: string[]; messages: PlugMessage[] } | PlugError => {
+/** The output item an `item_reference` names, or undefined when the app's store does not hold it. */
+export type ItemResolver = (itemId: string) => JsonObject | undefined
+
+/** An `item_reference` is the output item of an earlier answer, decoded as that item (#147). */
+const resolveReference = (item: JsonObject, param: string, resolve: ItemResolver | undefined): JsonObject | PlugError => {
+  if (typeof item.id !== "string" || item.id.length === 0) return bad("item_reference needs the id of an output item", `${param}.id`)
+  const found = resolve?.(item.id)
+  if (found === undefined)
+    return bad(
+      `item_reference "${item.id}" is not known to plugboard: it keeps the output of recent answers for an hour, per app. Send the earlier items in full, or send store: false (Vercel AI SDK: providerOptions.openai.store = false)`,
+      `${param}.id`,
+      "item_not_found",
+    )
+  return found
+}
+
+const parseInput = (input: unknown, resolve: ItemResolver | undefined): { system: string[]; messages: PlugMessage[] } | PlugError => {
   if (typeof input === "string") return { system: [], messages: [{ role: "user", content: [{ type: "text", text: input }] }] }
   if (!Array.isArray(input) || input.length === 0) return bad("input must be a string or a non-empty array of items", "input")
 
@@ -134,9 +151,11 @@ const parseInput = (input: unknown): { system: string[]; messages: PlugMessage[]
     pending = undefined
   }
 
-  for (const [index, item] of input.entries()) {
+  for (const [index, given] of input.entries()) {
     const param = `input[${index}]`
-    if (!isRecord(item)) return bad("Each input item must be an object", param)
+    if (!isRecord(given)) return bad("Each input item must be an object", param)
+    const item = given.type === "item_reference" ? resolveReference(given, param, resolve) : given
+    if (isPlugError(item)) return item
     const type = item.type ?? (item.role !== undefined ? "message" : undefined)
     switch (type) {
       case "message": {
@@ -192,11 +211,6 @@ const parseInput = (input: unknown): { system: string[]; messages: PlugMessage[]
       // Reasoning items carry no content plugboard can replay; they are dropped.
       case "reasoning":
         break
-      case "item_reference":
-        return unsupported(
-          "item_reference needs server-side state, which plugboard does not keep; send the full items instead (Vercel AI SDK: providerOptions.openai.store = false)",
-          `${param}.type`,
-        )
       default:
         return unsupported(`Unsupported input item type "${String(type)}"`, `${param}.type`)
     }
@@ -296,7 +310,7 @@ const checkUnsupported = (body: JsonObject): PlugError | undefined => {
   if (body.truncation != null && body.truncation !== "disabled") return unsupported('Only truncation "disabled" is supported', "truncation")
 }
 
-export function parseResponsesRequest(body: unknown, options: PlugboardOptions): ParsedResponses | PlugError {
+export function parseResponsesRequest(body: unknown, options: PlugboardOptions, resolve?: ItemResolver): ParsedResponses | PlugError {
   if (!isRecord(body)) return bad("Request body must be a JSON object")
   if (typeof body.model !== "string" || body.model.length === 0) return bad("model is required", "model")
   if (body.input == null) return bad("input is required", "input")
@@ -305,7 +319,7 @@ export function parseResponsesRequest(body: unknown, options: PlugboardOptions):
   if (body.instructions != null && typeof body.instructions !== "string") return bad("instructions must be a string", "instructions")
   if (body.reasoning != null && !isRecord(body.reasoning)) return bad("reasoning must be an object", "reasoning")
 
-  const parsed = parseInput(body.input)
+  const parsed = parseInput(body.input, resolve)
   if (isPlugError(parsed)) return parsed
   const callerTools = parseTools(body.tools)
   if (!Array.isArray(callerTools)) return callerTools

package/src/responses/route.ts

@@ -15,10 +15,12 @@ import { boundEvents, sendError, sendJson, sseWriter, type RequestScope } from "
 import { resolveModel } from "../models.js"
 import { reportCache } from "../cache.js"
 import { reportPolicy } from "../policy.js"
+import { reportUsage } from "../usage-header.js"
 import { encodeError } from "../openai/response.js"
 import type { RouteHost } from "../openai/route.js"
 import { parseResponsesRequest } from "./request.js"
 import { runResponse, sseFrame } from "./response.js"
+import { findItem, rememberAnswer } from "./store.js"
 
 const SESSION_HEADER = "x-plugboard-session"
 
@@ -34,7 +36,7 @@ export interface ResponsesCall {
 export async function serveResponses(host: RouteHost, { app, body, response, scope, info }: ResponsesCall): Promise<void> {
   const fail = (error: PlugError) => sendError(response, error, encodeError(error))
 
-  const parsed = parseResponsesRequest(body, host.options)
+  const parsed = parseResponsesRequest(body, host.options, (itemId) => findItem(app, itemId))
   if (isPlugError(parsed)) return fail(parsed)
   const catalog = await scope.race(host.loadCatalog())
   const ref = resolveModel(host.options, parsed.request.model, catalog, parsed.reasoningEffort)
@@ -55,6 +57,7 @@ export async function serveResponses(host: RouteHost, { app, body, response, sco
       },
       onServed: reportServed(response, info, (served) => void (exchange.model = served.model)),
       onPolicy: reportPolicy(response),
+      onUsage: reportUsage(response, exchange.stream),
       onCache: reportCache(response),
     }),
     scope,
@@ -62,11 +65,12 @@ export async function serveResponses(host: RouteHost, { app, body, response, sco
 
   if (exchange.stream) {
     const sse = sseWriter(response, scope.signal)
-    const { failure } = await runResponse(sse.paced(events), exchange, (event) => sse.write(sseFrame(event)), () => sse.started)
+    const run = await runResponse(sse.paced(events), exchange, (event) => sse.write(sseFrame(event)), () => sse.started)
+    if (run.response && !run.failure) rememberAnswer(app, run.response)
     if (!sse.started && !response.headersSent) {
-      if (!scope.signal.aborted || scope.timedOut) fail(failure ?? { status: 502, kind: "server", message: "No response from the model" })
+      if (!scope.signal.aborted || scope.timedOut) fail(run.failure ?? { status: 502, kind: "server", message: "No response from the model" })
     } else {
-      if (failure) info.failed = failure.code ?? failure.kind
+      if (run.failure) info.failed = run.failure.code ?? run.failure.kind
       if (!response.writableEnded) response.end()
     }
     return
@@ -74,5 +78,6 @@ export async function serveResponses(host: RouteHost, { app, body, response, sco
 
   const run = await runResponse(events, exchange, () => {})
   if (run.failure || !run.response) return fail(run.failure ?? { status: 502, kind: "server", message: "No response from the model" })
+  rememberAnswer(app, run.response)
   sendJson(response, 200, run.response)
 }