opencode-plugboard 0.4.0 → 0.5.0

package/src/discovery.ts

@@ -0,0 +1,280 @@
+/**
+ * First-run discovery and status documents: `GET /v1` (JSON), `GET /` (small HTML page) and the
+ * authenticated `GET /v1/status`. Pure builders over the options, the catalog and a runtime
+ * snapshot; no I/O, no host calls. `src/openai/route.ts` loads the catalog and sends the result.
+ *
+ * Disclosure rule: the discovery pages are reachable without a key, so they only describe the
+ * configuration when that is safe. On a keyless endpoint (loopback only) everything is shown.
+ * When `keys` are configured, a caller without an `Authorization` header sees the address, the
+ * authentication requirement, the endpoint list and a curl example, and nothing about apps,
+ * allowlist, aliases or the catalog. A caller with a valid key additionally sees its own app name
+ * (never the other apps), the allowlist, the aliases and the catalog suggestion. Keys themselves
+ * never appear anywhere, and nothing here echoes a request header or path.
+ *
+ * The HTML page is built from the same document as the JSON, has no scripts or external assets,
+ * and every dynamic value goes through `escapeHtml`.
+ */
+
+import type { ServerResponse } from "node:http"
+import type { PlugboardOptions } from "./config.js"
+import type { CatalogModel } from "./contract.js"
+import { listAvailableModels } from "./models.js"
+import type { RuntimeSnapshot } from "./metrics.js"
+
+const NAME = "opencode-plugboard"
+/** Providers listed in the catalog summary; the rest are counted, not listed. */
+const MAX_PROVIDERS = 50
+const EXAMPLES_PER_PROVIDER = 3
+const PLACEHOLDER_MODEL = "provider/model"
+
+/** A text response with the headers every page of this module shares. */
+export function sendText(response: ServerResponse, status: number, contentType: string, body: string, headers: Record<string, string> = {}): void {
+  if (response.headersSent || response.destroyed) return
+  response.writeHead(status, {
+    "content-type": contentType,
+    "content-length": Buffer.byteLength(body),
+    "x-content-type-options": "nosniff",
+    "cache-control": "no-store",
+    ...headers,
+  })
+  response.end(body)
+}
+
+const escapeHtml = (value: unknown): string =>
+  String(value).replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[char] ?? char)
+
+/** `http://host:port` for a listen address; an IPv6 literal gets brackets. */
+function origin(listen: PlugboardOptions["listen"]): string {
+  const host = listen.host.includes(":") && !listen.host.startsWith("[") ? `[${listen.host}]` : listen.host
+  return `http://${host}:${listen.port}`
+}
+
+const shellQuote = (text: string): string => `'${text.replace(/'/g, `'\\''`)}'`
+
+export interface Endpoint {
+  readonly method: string
+  readonly path: string
+  readonly auth: boolean
+  readonly description: string
+}
+
+function endpoints(options: PlugboardOptions): 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." },
+    ...(options.metrics ? [{ method: "GET", path: "/metrics", auth: true, description: "Prometheus metrics." }] : []),
+  ]
+}
+
+type ModelsState = "ready" | "no_models_configured" | "none_available" | "catalog_unavailable"
+
+interface ProviderSummary {
+  readonly id: string
+  readonly models: number
+  readonly examples: ReadonlyArray<string>
+}
+
+/** The `GET /v1` document. Fields marked "detail" are present only when the caller may see the configuration. */
+export interface Discovery {
+  readonly name: string
+  readonly baseUrl: string
+  readonly listen: { readonly host: string; readonly port: number }
+  readonly authentication: { readonly required: boolean; readonly scheme?: "Bearer" }
+  readonly hint?: string
+  /** detail: the caller's own app name, or `default` on a keyless endpoint. */
+  readonly apps?: ReadonlyArray<string>
+  /** detail */
+  readonly models?: {
+    readonly state: ModelsState
+    readonly allowlist: ReadonlyArray<string>
+    readonly aliases: Readonly<Record<string, string>>
+    /** Ids `GET /v1/models` lists (allowlist intersected with the catalog, plus aliases). */
+    readonly available?: number
+    readonly hint?: string
+  }
+  /** detail: a paste-ready `models` option built from the catalog (one wildcard per provider). */
+  readonly suggestedModels?: ReadonlyArray<string>
+  /** detail: what the catalog offers, by provider. */
+  readonly catalog?: { readonly providers: ReadonlyArray<ProviderSummary>; readonly moreProviders?: number }
+  readonly endpoints: ReadonlyArray<Endpoint>
+  readonly example: { readonly curl: string }
+}
+
+export interface DiscoveryInput {
+  readonly options: PlugboardOptions
+  /** The authenticated app; undefined when the caller sent no credentials (only possible when `keys` are set). */
+  readonly app?: string
+  /** The serving Location's catalog; undefined when it could not be loaded (or was not asked for). */
+  readonly catalog?: ReadonlyArray<CatalogModel>
+}
+
+function summarize(catalog: ReadonlyArray<CatalogModel>): { providers: ProviderSummary[]; more: number } {
+  const byProvider = new Map<string, string[]>()
+  for (const model of catalog) {
+    const ids = byProvider.get(model.providerID) ?? []
+    if (!ids.includes(model.id)) ids.push(model.id)
+    byProvider.set(model.providerID, ids)
+  }
+  const all = [...byProvider.entries()].sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+  return {
+    providers: all.slice(0, MAX_PROVIDERS).map(([id, ids]) => ({ id, models: ids.length, examples: ids.slice(0, EXAMPLES_PER_PROVIDER).map((model) => `${id}/${model}`) })),
+    more: Math.max(0, all.length - MAX_PROVIDERS),
+  }
+}
+
+export function buildDiscovery({ options, app, catalog }: DiscoveryInput): Discovery {
+  const keyed = Object.keys(options.keys).length > 0
+  const base = `${origin(options.listen)}/v1`
+  const detail = !keyed || app !== undefined
+  const auth = keyed ? ({ required: true, scheme: "Bearer" } as const) : { required: false }
+
+  const listed = detail && catalog ? listAvailableModels(options, catalog) : []
+  const summary = detail && catalog ? summarize(catalog) : undefined
+  const suggested = summary?.providers.map((provider) => `${provider.id}/*`)
+
+  let state: ModelsState = "ready"
+  let modelsHint: string | undefined
+  const example = JSON.stringify(suggested && suggested.length > 0 ? { models: suggested } : { models: ["provider/*"] })
+  if (options.models.length === 0) {
+    state = "no_models_configured"
+    modelsHint = `The \`models\` option is empty, so every model call fails with 403 no_models_configured. Add an allowlist to the plugin options, for example ${example}`
+  } else if (!catalog) {
+    state = "catalog_unavailable"
+    modelsHint = "The model catalog could not be loaded from the OpenCode server."
+  } else if (listed.length === 0) {
+    state = "none_available"
+    modelsHint = "Nothing in the `models` allowlist matches a model the server offers. Check the provider and model ids against the catalog below."
+  }
+
+  const first = listed[0]?.id ?? PLACEHOLDER_MODEL
+  const body = JSON.stringify({ model: first, messages: [{ role: "user", content: "Say hello." }] })
+  const curl = [`curl -s ${base}/chat/completions`, `-H "Content-Type: application/json"`, ...(keyed ? [`-H "Authorization: Bearer $PLUGBOARD_KEY"`] : []), `-d ${shellQuote(body)}`].join(" ")
+
+  return {
+    name: NAME,
+    baseUrl: base,
+    listen: { host: options.listen.host, port: options.listen.port },
+    authentication: auth,
+    ...(detail
+      ? {}
+      : { hint: "Authentication is required. Send `Authorization: Bearer <key>` to see this app's configuration: the allowlist, aliases and a model suggestion." }),
+    ...(detail ? { apps: [app ?? "default"] } : {}),
+    ...(detail
+      ? {
+          models: {
+            state,
+            allowlist: options.models,
+            aliases: options.aliases,
+            ...(catalog ? { available: listed.length } : {}),
+            ...(modelsHint ? { hint: modelsHint } : {}),
+          },
+        }
+      : {}),
+    ...(suggested && suggested.length > 0 ? { suggestedModels: suggested } : {}),
+    ...(summary ? { catalog: { providers: summary.providers, ...(summary.more > 0 ? { moreProviders: summary.more } : {}) } } : {}),
+    endpoints: endpoints(options),
+    example: { curl },
+  }
+}
+
+const pre = (text: string) => `<pre>${escapeHtml(text)}</pre>`
+const list = (items: ReadonlyArray<string>) => `<ul>${items.map((item) => `<li><code>${escapeHtml(item)}</code></li>`).join("")}</ul>`
+
+/** The `GET /` page: the discovery document as small, script-free HTML. */
+export function renderDiscoveryHtml(doc: Discovery): string {
+  const sections: string[] = []
+  sections.push(`<p>Base URL: <code>${escapeHtml(doc.baseUrl)}</code></p>`)
+  sections.push(
+    `<p>Authentication: ${doc.authentication.required ? "required. Send <code>Authorization: Bearer &lt;key&gt;</code>." : "none (keyless, loopback only)."}</p>`,
+  )
+  if (doc.hint) sections.push(`<p class="hint">${escapeHtml(doc.hint)}</p>`)
+  if (doc.apps) sections.push(`<h2>App</h2>${list(doc.apps)}`)
+  if (doc.models) {
+    const models = doc.models
+    sections.push(`<h2>Models</h2>`)
+    if (models.hint) sections.push(`<p class="hint">${escapeHtml(models.hint)}</p>`)
+    if (models.available !== undefined) sections.push(`<p>${escapeHtml(models.available)} model ids available.</p>`)
+    sections.push(`<h3>Allowlist</h3>${models.allowlist.length > 0 ? list(models.allowlist) : "<p>Empty.</p>"}`)
+    const aliases = Object.entries(models.aliases)
+    if (aliases.length > 0) sections.push(`<h3>Aliases</h3>${list(aliases.map(([alias, target]) => `${alias} -> ${target}`))}`)
+  }
+  if (doc.suggestedModels) {
+    sections.push(`<h2>Suggested <code>models</code> option</h2>${pre(`"models": ${JSON.stringify(doc.suggestedModels)}`)}`)
+  }
+  if (doc.catalog) {
+    const rows = doc.catalog.providers
+      .map(
+        (provider) =>
+          `<tr><td><code>${escapeHtml(provider.id)}</code></td><td>${escapeHtml(provider.models)}</td><td>${provider.examples.map((example) => `<code>${escapeHtml(example)}</code>`).join(" ")}</td></tr>`,
+      )
+      .join("")
+    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}`)
+  }
+  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
+      .map(
+        (endpoint) =>
+          `<tr><td>${escapeHtml(endpoint.method)}</td><td><code>${escapeHtml(endpoint.path)}</code></td><td>${endpoint.auth ? "yes" : "no"}</td><td>${escapeHtml(endpoint.description)}</td></tr>`,
+      )
+      .join("")}</table>`,
+  )
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(doc.name)}</title>
+<style>
+body{font:16px/1.5 system-ui,sans-serif;max-width:48rem;margin:2rem auto;padding:0 1rem;color:#1a1a1a}
+code,pre{font-family:ui-monospace,monospace;font-size:.9em}
+pre{background:#f4f4f4;padding:.75rem;overflow-x:auto;white-space:pre-wrap;word-break:break-all}
+table{border-collapse:collapse}td,th{border:1px solid #ccc;padding:.25rem .5rem;text-align:left;vertical-align:top}
+.hint{border-left:4px solid #c80;background:#fff7e6;padding:.5rem .75rem}
+</style>
+</head>
+<body>
+<h1>${escapeHtml(doc.name)}</h1>
+${sections.join("\n")}
+<p><a href="/v1">JSON version of this page</a></p>
+</body>
+</html>
+`
+}
+
+/** `GET /v1/status`: authenticated runtime facts. `models` is absent when the catalog could not be loaded. */
+export function buildStatus(input: {
+  readonly options: PlugboardOptions
+  readonly app: string
+  readonly runtime: RuntimeSnapshot & {
+    readonly runtimeVersion: number
+    readonly listener?: { readonly host: string; readonly port: number; readonly bound: boolean }
+    readonly servingConfirmed: boolean
+  }
+  readonly catalog?: ReadonlyArray<CatalogModel>
+  readonly now?: number
+}): object {
+  const { options, app, runtime, catalog } = input
+  const now = input.now ?? Date.now()
+  return {
+    ok: true,
+    app,
+    runtimeVersion: runtime.runtimeVersion,
+    startedAt: new Date(runtime.startedAt).toISOString(),
+    uptimeSeconds: Math.max(0, Math.floor((now - runtime.startedAt) / 1000)),
+    listen: { host: options.listen.host, port: options.listen.port, bound: runtime.listener?.bound ?? false },
+    generations: runtime.generations,
+    servingConfirmed: runtime.servingConfirmed,
+    eventPump: { running: runtime.pumpRunning },
+    sessionGuards: runtime.guards,
+    models: catalog ? { catalog: catalog.length, available: listAvailableModels(options, catalog).length } : { error: "catalog_unavailable" },
+    metrics: options.metrics,
+  }
+}

package/src/log.ts

@@ -1,28 +1,79 @@
 /**
- * Tiny structured logger: one line per event, `[opencode-plugboard] event key=value ...`.
+ * Tiny structured logger: one line per event.
+ *
+ *   text (default)  `[opencode-plugboard] event key=value ...`
+ *   json            `{"time":"...","level":"info","service":"opencode-plugboard","event":"request","id":"...",...}`
  *
  * Callers pass only identifiers and outcomes (event name, request id, app, model, duration, an
  * error message). Never pass API keys, request or response bodies, URLs or raw provider
  * objects: nothing here redacts them.
+ *
+ * The format is process-wide (`setLogFormat`, set by the runtime from the live generation's
+ * `logFormat` option). A line logged while a request is being handled also carries that request's
+ * id (`id`, the value of the `x-plugboard-request-id` response header): `withRequestId` scopes it
+ * to the request's async chain (node:async_hooks), and `outsideRequest` detaches work that merely
+ * started from a request but is not about it (the history sweep, the event pump).
+ *
+ * Both settings sit on `globalThis`, because the module can be evaluated once per Location.
  */
 
+import { AsyncLocalStorage } from "node:async_hooks"
+
 export type LogFields = Readonly<Record<string, string | number | boolean | undefined>>
+export type LogFormat = "text" | "json"
 
 const PREFIX = "[opencode-plugboard]"
+const SERVICE = "opencode-plugboard"
+const KEY = Symbol.for("opencode-plugboard.log.1")
+
+interface LogState {
+  format: LogFormat
+  readonly requests: AsyncLocalStorage<{ readonly id: string } | undefined>
+}
+
+function state(): LogState {
+  const slot = globalThis as Record<symbol, unknown>
+  return (slot[KEY] ??= { format: "text", requests: new AsyncLocalStorage() } satisfies LogState) as LogState
+}
+
+/** Set the line format for the whole process. */
+export function setLogFormat(format: LogFormat): void {
+  state().format = format
+}
+
+/** Run `fn` so that every log line emitted from its async chain carries `id`. */
+export const withRequestId = <T>(id: string, fn: () => T): T => state().requests.run({ id }, fn)
+
+/** Run `fn` detached from the current request: its log lines carry no request id. */
+export const outsideRequest = <T>(fn: () => T): T => state().requests.run(undefined, fn)
 
 function formatValue(value: string | number | boolean): string {
   return typeof value === "string" && !/^[\w.:/#-]+$/.test(value) ? JSON.stringify(value) : String(value)
 }
 
-function format(event: string, fields: LogFields | undefined): string {
+/** The fields with the ambient request id added (an explicit `id` field wins). */
+function withAmbientId(fields: LogFields | undefined): Array<[string, string | number | boolean | undefined]> {
+  const entries = Object.entries(fields ?? {})
+  const ambient = state().requests.getStore()?.id
+  return ambient !== undefined && !entries.some(([key]) => key === "id") ? [["id", ambient], ...entries] : entries
+}
+
+function format(level: "info" | "error", event: string, fields: LogFields | undefined): string {
+  const entries = withAmbientId(fields)
+  if (state().format === "json") {
+    const line: Record<string, unknown> = { time: new Date().toISOString(), level, service: SERVICE, event }
+    // The envelope keys cannot be overwritten by a field of the same name.
+    for (const [key, value] of entries) if (value !== undefined && !(key in line)) line[key] = value
+    return JSON.stringify(line)
+  }
   let line = `${PREFIX} ${event}`
-  for (const [key, value] of Object.entries(fields ?? {})) if (value !== undefined) line += ` ${key}=${formatValue(value)}`
+  for (const [key, value] of entries) if (value !== undefined) line += ` ${key}=${formatValue(value)}`
   return line
 }
 
-export const log = (event: string, fields?: LogFields): void => console.log(format(event, fields))
+export const log = (event: string, fields?: LogFields): void => console.log(format("info", event, fields))
 
-export const logError = (event: string, fields?: LogFields): void => console.error(format(event, fields))
+export const logError = (event: string, fields?: LogFields): void => console.error(format("error", 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

@@ -0,0 +1,176 @@
+/**
+ * Process metrics in the Prometheus text exposition format (version 0.0.4), hand-rolled: no
+ * dependency, no I/O. One registry lives in the process runtime (`src/runtime.ts`), so counts
+ * survive a plugin generation being replaced. `GET /metrics` renders it (opt-in, `metrics: true`).
+ *
+ * Labels are bounded by construction and carry ids only: `app` is a configured key name (or
+ * `_none` before authentication succeeded), `route` is one of the known routes or `unknown`,
+ * `status` a response code, `outcome` one of a fixed set, `param` a sampling parameter name from
+ * `src/openai/sampling.ts`. Never a model string, key, path or client-supplied text.
+ */
+
+import type { PlugUsage } from "./contract.js"
+
+/** `app` label of a request that was not authenticated (app names cannot contain an underscore). */
+export const NO_APP = "_none"
+
+/** What a request ended as, for the `outcome` label. */
+export type Outcome = "ok" | "rejected" | "failed" | "timeout" | "disconnected"
+
+/** Collapses the request log's outcome string and the response status into the bounded `outcome` label. */
+export function outcomeLabel(logOutcome: string, status: number): Outcome {
+  if (logOutcome === "timeout" || logOutcome === "disconnected") return logOutcome
+  if (logOutcome === "error") return "failed"
+  if (status >= 500) return "failed"
+  if (status >= 400) return "rejected"
+  return "ok"
+}
+
+/** Process-level values the registry does not own; read from the runtime at scrape time. */
+export interface RuntimeSnapshot {
+  /** Accepted plugin generations currently serving. */
+  readonly generations: number
+  /** Whether the event pump is subscribed. */
+  readonly pumpRunning: boolean
+  /** Request guards outstanding (sessions the runtime still owns, including ones past their response). */
+  readonly guards: number
+  /** Runtime start, epoch ms. */
+  readonly startedAt: number
+}
+
+/** Request duration buckets, seconds: model calls run from under a second to many minutes. */
+const BUCKETS = [0.1, 0.5, 1, 2.5, 5, 10, 30, 60, 120, 300, 600]
+
+const escapeLabel = (value: string): string => value.replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/"/g, '\\"')
+const escapeHelp = (value: string): string => value.replace(/\\/g, "\\\\").replace(/\n/g, "\\n")
+const labelText = (names: ReadonlyArray<string>, values: ReadonlyArray<string>): string =>
+  names.length === 0 ? "" : `{${names.map((name, index) => `${name}="${escapeLabel(values[index] ?? "")}"`).join(",")}}`
+
+class Counter {
+  private readonly series = new Map<string, { values: string[]; total: number }>()
+  constructor(
+    readonly name: string,
+    readonly help: string,
+    private readonly labels: ReadonlyArray<string>,
+  ) {}
+  add(values: ReadonlyArray<string>, amount = 1): void {
+    if (!(amount > 0) || !Number.isFinite(amount)) return
+    const key = values.join("\u0000")
+    const entry = this.series.get(key)
+    if (entry) entry.total += amount
+    else this.series.set(key, { values: [...values], total: amount })
+  }
+  render(): string[] {
+    const lines = [`# HELP ${this.name} ${escapeHelp(this.help)}`, `# TYPE ${this.name} counter`]
+    for (const { values, total } of this.series.values()) lines.push(`${this.name}${labelText(this.labels, values)} ${total}`)
+    return lines
+  }
+}
+
+class Histogram {
+  private readonly series = new Map<string, { values: string[]; counts: number[]; sum: number; count: number }>()
+  constructor(
+    readonly name: string,
+    readonly help: string,
+    private readonly labels: ReadonlyArray<string>,
+  ) {}
+  observe(values: ReadonlyArray<string>, seconds: number): void {
+    if (!(seconds >= 0) || !Number.isFinite(seconds)) return
+    const key = values.join("\u0000")
+    let entry = this.series.get(key)
+    if (!entry) this.series.set(key, (entry = { values: [...values], counts: BUCKETS.map(() => 0), sum: 0, count: 0 }))
+    BUCKETS.forEach((bound, index) => {
+      if (seconds <= bound) entry.counts[index]! += 1
+    })
+    entry.sum += seconds
+    entry.count += 1
+  }
+  render(): string[] {
+    const lines = [`# HELP ${this.name} ${escapeHelp(this.help)}`, `# TYPE ${this.name} histogram`]
+    for (const { values, counts, sum, count } of this.series.values()) {
+      const names = [...this.labels, "le"]
+      BUCKETS.forEach((bound, index) => lines.push(`${this.name}_bucket${labelText(names, [...values, String(bound)])} ${counts[index]}`))
+      lines.push(`${this.name}_bucket${labelText(names, [...values, "+Inf"])} ${count}`)
+      lines.push(`${this.name}_sum${labelText(this.labels, values)} ${sum}`)
+      lines.push(`${this.name}_count${labelText(this.labels, values)} ${count}`)
+    }
+    return lines
+  }
+}
+
+const gauge = (name: string, help: string, value: number): string[] => [
+  `# HELP ${name} ${escapeHelp(help)}`,
+  `# TYPE ${name} gauge`,
+  `${name} ${value}`,
+]
+
+export interface Metrics {
+  /** A request entered the handler. Pair with `requestFinished`. */
+  requestStarted(): void
+  requestFinished(input: { readonly app: string; readonly route: string; readonly status: number; readonly outcome: Outcome; readonly ms: number }): void
+  /** Token usage of one model call, as a non-overlapping breakdown (see `plugboard_tokens_total`). */
+  tokens(app: string, usage: PlugUsage): void
+  /** Sampling parameters dropped for one request. */
+  dropped(params: ReadonlyArray<string>): void
+  /** One history sweep ended. */
+  sweep(result: "ok" | "failed" | "timeout", removed: number): void
+  /** The exposition text. Called from a request that is itself in flight, which is not counted. */
+  render(snapshot: RuntimeSnapshot): string
+}
+
+export function createMetrics(): Metrics {
+  let inFlight = 0
+  const requests = new Counter("plugboard_requests_total", "Requests handled, by app, route, response status and outcome.", ["app", "route", "status", "outcome"])
+  const duration = new Histogram("plugboard_request_duration_seconds", "Time from request start to the end of the response, by app and route.", ["app", "route"])
+  const tokens = new Counter(
+    "plugboard_tokens_total",
+    "Tokens of completed model calls, by app and kind. Kinds do not overlap: input is uncached prompt tokens, cache_read and cache_write are cached prompt tokens, output excludes reasoning.",
+    ["app", "kind"],
+  )
+  const dropped = new Counter("plugboard_dropped_params_total", "Sampling parameters dropped because the target model rejects them, by parameter.", ["param"])
+  const sweeps = new Counter("plugboard_history_sweeps_total", "History sweeps that ended, by result.", ["result"])
+  const removed = new Counter("plugboard_history_sessions_removed_total", "Request sessions removed by history sweeps.", [])
+
+  return {
+    requestStarted: () => void inFlight++,
+    requestFinished({ app, route, status, outcome, ms }) {
+      inFlight = Math.max(0, inFlight - 1)
+      requests.add([app, route, String(status), outcome])
+      duration.observe([app, route], ms / 1000)
+    },
+    tokens(app, usage) {
+      const cacheRead = usage.cacheReadTokens ?? 0
+      const cacheWrite = usage.cacheWriteTokens ?? 0
+      const reasoning = usage.reasoningTokens ?? 0
+      tokens.add([app, "input"], Math.max(0, (usage.inputTokens ?? 0) - cacheRead - cacheWrite))
+      tokens.add([app, "cache_read"], cacheRead)
+      tokens.add([app, "cache_write"], cacheWrite)
+      tokens.add([app, "output"], Math.max(0, (usage.outputTokens ?? 0) - reasoning))
+      tokens.add([app, "reasoning"], reasoning)
+    },
+    dropped(params) {
+      for (const param of params) dropped.add([param])
+    },
+    sweep(result, count) {
+      sweeps.add([result])
+      removed.add([], count)
+    },
+    render(snapshot) {
+      const lines = [
+        ...requests.render(),
+        ...duration.render(),
+        // The scrape itself is in flight; do not report it.
+        ...gauge("plugboard_requests_in_flight", "Requests being handled right now, not counting this scrape.", Math.max(0, inFlight - 1)),
+        ...tokens.render(),
+        ...dropped.render(),
+        ...sweeps.render(),
+        ...removed.render(),
+        ...gauge("plugboard_generations", "Accepted plugin generations (one per OpenCode Location) serving requests.", snapshot.generations),
+        ...gauge("plugboard_event_pump_up", "1 while the event pump is subscribed to the OpenCode event bus, else 0 (it starts with the first request).", snapshot.pumpRunning ? 1 : 0),
+        ...gauge("plugboard_session_guards", "Request guards outstanding: request sessions plugboard still owns, including ones whose response has ended.", snapshot.guards),
+        ...gauge("plugboard_start_time_seconds", "Start of the plugboard runtime in this process, Unix time.", Math.floor(snapshot.startedAt / 1000)),
+      ]
+      return lines.join("\n") + "\n"
+    },
+  }
+}

package/src/openai/response.ts

@@ -63,6 +63,34 @@ export const encodeError = (error: PlugError): object => ({
   error: { message: error.message, type: ERROR_TYPES[error.kind], param: error.param ?? null, code: error.code ?? null },
 })
 
+/** Epoch ms -> ISO 8601, or undefined for a value Date cannot represent. */
+const isoDate = (ms: number | undefined): string | undefined => {
+  if (ms === undefined) return undefined
+  const date = new Date(ms)
+  return Number.isNaN(date.getTime()) ? undefined : date.toISOString()
+}
+
+/**
+ * The `plugboard` object of a model entry: what the catalog knows beyond the OpenAI fields. Absent
+ * facts are omitted. `cost` is USD per million tokens (an entry with `aboveContext` applies when
+ * the prompt exceeds that many tokens; the entry without it is the base price); `released` is ISO 8601.
+ */
+const encodePlugboard = (model: ListedModel["model"]) => ({
+  capabilities: model.capabilities ?? {},
+  contextLimit: model.contextLimit,
+  limit: model.limits,
+  modalities: model.modalities,
+  cost: model.cost?.map(({ input, output, cacheRead, cacheWrite, aboveContext }) => ({
+    input,
+    output,
+    cache: { read: cacheRead, write: cacheWrite },
+    ...(aboveContext === undefined ? {} : { aboveContext }),
+  })),
+  status: model.status,
+  family: model.family,
+  released: isoDate(model.released),
+})
+
 /** `GET /v1/models` body. */
 export const encodeModelList = (models: ReadonlyArray<ListedModel>): object => ({
   object: "list",
@@ -71,7 +99,7 @@ export const encodeModelList = (models: ReadonlyArray<ListedModel>): object => (
     object: "model",
     created: 0,
     owned_by: ref.providerID,
-    plugboard: { capabilities: model.capabilities ?? {}, contextLimit: model.contextLimit },
+    plugboard: encodePlugboard(model),
   })),
 })