opencode-plugboard 0.13.0 → 0.15.0

package/src/log.ts

@@ -1,39 +1,123 @@
 /**
- * Tiny structured logger: one line per event.
+ * Structured logger on pino: one line per event.
  *
  *   text (default)  `[opencode-plugboard] event key=value ...`
- *   json            `{"time":"...","level":"info","service":"opencode-plugboard","event":"request","id":"...",...}`
+ *   json            `{"level":"info","time":"...","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.
+ * objects. As a backstop pino's `redact` censors the fields `authorization`, `key`, `apiKey`,
+ * `x-api-key` and `x-goog-api-key` (also under `headers`); it matches field names, not values,
+ * so it does not replace that rule.
+ *
+ * `json` is pino's own JSON with three settings: the level is its name (`"info"`, `"error"`, not
+ * pino's 30 and 50) so lines keep the shape they had before pino, the message key is `event`, and
+ * the base object holds only `service` (no `pid` or `hostname`). A field cannot overwrite
+ * `level`, `time`, `service` or `event`.
+ *
+ * There is no pino transport and no worker thread: pino writes synchronously to two small
+ * destinations, and the transport machinery (thread-stream) is never started, which keeps it
+ * safe inside the OpenCode host. Info lines go to `console.log` (stdout), error lines to
+ * `console.error` (stderr), as before. Text lines are made from the JSON line by `toText`;
+ * pino-pretty was not used because it prints multi-line, level-prefixed output, adds a dozen
+ * packages, and cannot produce the `event key=value` shape that log scrapers already match.
  *
  * 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).
+ * to the request's async chain (node:async_hooks) and pino's `mixin` reads it per line, and
+ * `outsideRequest` detaches work that merely started from a request but is not about it (the
+ * history sweep, the event pump). An explicit `id` field wins over the ambient one.
  *
- * Both settings sit on `globalThis`, because the module can be evaluated once per Location.
+ * The logger and both settings sit on `globalThis`, because the module can be evaluated once per
+ * Location. They are here and not on the process runtime (`src/runtime.ts`) because the runtime
+ * imports this module and must still be able to log when a foreign-version runtime owns the process.
  */
 
 import { AsyncLocalStorage } from "node:async_hooks"
+import pino, { type Logger } from "pino"
 
 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")
+const KEY = Symbol.for("opencode-plugboard.log.2")
+/** Keys of the line itself; a caller's field of the same name is dropped. */
+const ENVELOPE = new Set(["level", "time", "service", "event"])
+
+/** Field names whose value is censored, at the top level and under `headers` (pino path syntax). */
+const REDACTED = ["authorization", "Authorization", "x-api-key", "x-goog-api-key", "key", "apiKey"]
+const REDACT_PATHS = REDACTED.flatMap((name) => {
+  const path = /^[A-Za-z_$][\w$]*$/.test(name) ? name : `["${name}"]`
+  return [path, `headers${path.startsWith("[") ? "" : "."}${path}`]
+})
 
 interface LogState {
   format: LogFormat
   readonly requests: AsyncLocalStorage<{ readonly id: string } | undefined>
+  readonly logger: Logger
+}
+
+/** A pino line (JSON, newline ended) as one line of the console: raw for `json`, `event key=value` for `text`. */
+function toText(line: string): string {
+  let record: Record<string, unknown>
+  try {
+    record = JSON.parse(line) as Record<string, unknown>
+  } catch {
+    return line
+  }
+  let text = `${PREFIX} ${String(record.event)}`
+  for (const [key, value] of Object.entries(record)) {
+    if (ENVELOPE.has(key) || value === undefined) continue
+    text += ` ${key}=${formatValue(value)}`
+  }
+  return text
+}
+
+function formatValue(value: unknown): string {
+  if (typeof value === "string") return /^[\w.:/#-]+$/.test(value) ? value : JSON.stringify(value)
+  if (typeof value === "number" || typeof value === "boolean") return String(value)
+  return JSON.stringify(value)
+}
+
+function createState(): LogState {
+  const requests = new AsyncLocalStorage<{ readonly id: string } | undefined>()
+  const state = { format: "text" as LogFormat, requests } as { format: LogFormat; requests: typeof requests; logger: Logger }
+  // `console` is read at write time, not captured, so spies and host patches of it keep working.
+  const destination = (channel: "log" | "error") => ({
+    write(line: string) {
+      const text = line.endsWith("\n") ? line.slice(0, -1) : line
+      console[channel](state.format === "json" ? text : toText(text))
+    },
+  })
+  state.logger = pino(
+    {
+      level: "info",
+      base: { service: SERVICE },
+      timestamp: pino.stdTimeFunctions.isoTime,
+      formatters: { level: (label) => ({ level: label }) },
+      mixin: () => {
+        const id = requests.getStore()?.id
+        return id === undefined ? {} : { id }
+      },
+      redact: { paths: REDACT_PATHS, censor: "[redacted]" },
+    },
+    // dedupe: a record goes to the highest-level destination it reaches, so errors only to stderr.
+    pino.multistream(
+      [
+        { level: "info", stream: destination("log") },
+        { level: "error", stream: destination("error") },
+      ],
+      { dedupe: true },
+    ),
+  )
+  return state
 }
 
 function state(): LogState {
   const slot = globalThis as Record<symbol, unknown>
-  return (slot[KEY] ??= { format: "text", requests: new AsyncLocalStorage() } satisfies LogState) as LogState
+  return (slot[KEY] ??= createState()) as LogState
 }
 
 /** Set the line format for the whole process. */
@@ -47,33 +131,16 @@ export const withRequestId = <T>(id: string, fn: () => T): T => state().requests
 /** 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)
-}
-
-/** 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 entries) if (value !== undefined) line += ` ${key}=${formatValue(value)}`
+/** The fields without the keys of the line envelope (a field cannot overwrite them), with `event` first. */
+function record(event: string, fields: LogFields | undefined): Record<string, unknown> {
+  const line: Record<string, unknown> = { event }
+  for (const [key, value] of Object.entries(fields ?? {})) if (value !== undefined && !ENVELOPE.has(key)) line[key] = value
   return line
 }
 
-export const log = (event: string, fields?: LogFields): void => console.log(format("info", event, fields))
+export const log = (event: string, fields?: LogFields): void => state().logger.info(record(event, fields))
 
-export const logError = (event: string, fields?: LogFields): void => console.error(format("error", event, fields))
+export const logError = (event: string, fields?: LogFields): void => state().logger.error(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

@@ -1,7 +1,9 @@
 /**
- * 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`).
+ * Process metrics in the Prometheus text exposition format (version 0.0.4), on @prometheus-io/client. No
+ * I/O. `createMetrics` makes one `Registry` of its own (the default global registry is never
+ * touched, and the default process metrics are never collected); the one the server uses 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`,
@@ -9,6 +11,7 @@
  * `src/openai/sampling.ts`. Never a model string, key, path or client-supplied text.
  */
 
+import { Counter, Gauge, Histogram, Registry } from "@prometheus-io/client"
 import type { PlugUsage } from "./contract.js"
 
 /** `app` label of a request that was not authenticated (app names cannot contain an underscore). */
@@ -41,70 +44,15 @@ export interface RuntimeSnapshot {
 /** 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
-  }
+/** A counter that ignores zero, negative and non-finite amounts (@prometheus-io/client throws on the last two and would write a zero series for the first). */
+const count = <L extends string>(counter: Counter<L>, labels: Record<L, string>, amount = 1): void => {
+  // `Record<L, string>` is what `LabelValues<L>` means for a non-empty label list; its conditional type cannot resolve for a generic `L`.
+  if (amount > 0 && Number.isFinite(amount)) (counter as Counter<string>).inc(labels, amount)
 }
 
-const gauge = (name: string, help: string, value: number): string[] => [
-  `# HELP ${name} ${escapeHelp(help)}`,
-  `# TYPE ${name} gauge`,
-  `${name} ${value}`,
-]
-
 export interface Metrics {
+  /** The `Content-Type` of `render`'s text, as the registry reports it. */
+  readonly contentType: string
   /** 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
@@ -114,68 +62,116 @@ 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 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. */
   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
+  render(snapshot: RuntimeSnapshot): Promise<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 fallbacks = new Counter("plugboard_fallbacks_total", "Model calls retried on the next target of an alias after a failure before any output, by app.", ["app"])
-  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.", [])
+  const registry = new Registry()
+  // Registration order is the order of the exposition text.
+  const requests = new Counter({
+    name: "plugboard_requests_total",
+    help: "Requests handled, by app, route, response status and outcome.",
+    labelNames: ["app", "route", "status", "outcome"],
+    registers: [registry],
+  })
+  const duration = new Histogram({
+    name: "plugboard_request_duration_seconds",
+    help: "Time from request start to the end of the response, by app and route.",
+    labelNames: ["app", "route"],
+    buckets: BUCKETS,
+    registers: [registry],
+  })
+  const inFlightGauge = new Gauge({ name: "plugboard_requests_in_flight", help: "Requests being handled right now, not counting this scrape.", registers: [registry] })
+  const tokens = new Counter({
+    name: "plugboard_tokens_total",
+    help: "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.",
+    labelNames: ["app", "kind"],
+    registers: [registry],
+  })
+  const dropped = new Counter({
+    name: "plugboard_dropped_params_total",
+    help: "Sampling parameters dropped because the target model rejects them, by parameter.",
+    labelNames: ["param"],
+    registers: [registry],
+  })
+  const fallbacks = new Counter({
+    name: "plugboard_fallbacks_total",
+    help: "Model calls retried on the next target of an alias after a failure before any output, by app.",
+    labelNames: ["app"],
+    registers: [registry],
+  })
+  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.",
+    labelNames: ["app", "reason"],
+    registers: [registry],
+  })
+  const cache = new Counter({
+    name: "plugboard_cache_requests_total",
+    help: "Model calls the response cache applied to, by app and result (hit or miss). Absent unless the `cache` option is set.",
+    labelNames: ["app", "result"],
+    registers: [registry],
+  })
+  const sweeps = new Counter({ name: "plugboard_history_sweeps_total", help: "History sweeps that ended, by result.", labelNames: ["result"], registers: [registry] })
+  const removed = new Counter({ name: "plugboard_history_sessions_removed_total", help: "Request sessions removed by history sweeps.", registers: [registry] })
+  const generations = new Gauge({ name: "plugboard_generations", help: "Accepted plugin generations (one per OpenCode Location) serving requests.", registers: [registry] })
+  const pumpUp = new Gauge({
+    name: "plugboard_event_pump_up",
+    help: "1 while the event pump is subscribed to the OpenCode event bus, else 0 (it starts with the first request).",
+    registers: [registry],
+  })
+  const guards = new Gauge({
+    name: "plugboard_session_guards",
+    help: "Request guards outstanding: request sessions plugboard still owns, including ones whose response has ended.",
+    registers: [registry],
+  })
+  const startTime = new Gauge({ name: "plugboard_start_time_seconds", help: "Start of the plugboard runtime in this process, Unix time.", registers: [registry] })
 
   return {
+    contentType: registry.contentType,
     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)
+      count(requests, { app, route, status: String(status), outcome })
+      const seconds = ms / 1000
+      if (seconds >= 0 && Number.isFinite(seconds)) duration.observe({ app, route }, seconds)
     },
     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)
+      count(tokens, { app, kind: "input" }, Math.max(0, (usage.inputTokens ?? 0) - cacheRead - cacheWrite))
+      count(tokens, { app, kind: "cache_read" }, cacheRead)
+      count(tokens, { app, kind: "cache_write" }, cacheWrite)
+      count(tokens, { app, kind: "output" }, Math.max(0, (usage.outputTokens ?? 0) - reasoning))
+      count(tokens, { app, kind: "reasoning" }, reasoning)
     },
     dropped(params) {
-      for (const param of params) dropped.add([param])
+      for (const param of params) count(dropped, { param })
     },
-    fallback: (app) => fallbacks.add([app]),
-    sweep(result, count) {
-      sweeps.add([result])
-      removed.add([], count)
+    fallback: (app) => count(fallbacks, { app }),
+    limited: (app, reason) => count(limited, { app, reason }),
+    cache: (app, result) => count(cache, { app, result }),
+    sweep(result, amount) {
+      count(sweeps, { result })
+      if (amount > 0 && Number.isFinite(amount)) removed.inc(amount)
     },
     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(),
-        ...fallbacks.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"
+      // The scrape itself is in flight; do not report it.
+      inFlightGauge.set(Math.max(0, inFlight - 1))
+      generations.set(snapshot.generations)
+      pumpUp.set(snapshot.pumpRunning ? 1 : 0)
+      guards.set(snapshot.guards)
+      startTime.set(Math.floor(snapshot.startedAt / 1000))
+      return registry.metrics()
     },
   }
 }

package/src/models.ts

@@ -20,6 +20,33 @@ export function refToString(ref: ModelRef): string {
   return `${ref.providerID}/${ref.id}${ref.variant ? `#${ref.variant}` : ""}`
 }
 
+/**
+ * A UI-safe spelling of a canonical id: `/` becomes `--` and `#` becomes `__`, so some chat UIs that mangle
+ * `/` and `#` keep it intact. `anthropic/claude-haiku-4-5#high` -> `anthropic--claude-haiku-4-5__high`.
+ */
+export function toSlug(id: string): string {
+  return id.replaceAll("/", "--").replaceAll("#", "__")
+}
+
+/**
+ * The canonical id a slug stands for, or undefined when `slug` is not one. The first `--` ends the provider, the
+ * first `__` starts the variant; a `--` inside the model id is read back as `/`. Ids where that does not round
+ * trip are not listed as slugs (see `listAvailableModels`), so they are never offered and never resolved this way.
+ */
+export function fromSlug(slug: string): string | undefined {
+  if (typeof slug !== "string" || /[\s/#*]/.test(slug)) return undefined
+  const sep = slug.indexOf("--")
+  if (sep <= 0) return undefined
+  const providerID = slug.slice(0, sep)
+  const rest = slug.slice(sep + 2)
+  const at = rest.indexOf("__")
+  const model = (at === -1 ? rest : rest.slice(0, at)).replaceAll("--", "/")
+  const variant = at === -1 ? undefined : rest.slice(at + 2)
+  if (variant !== undefined && (!variant || variant.includes("__"))) return undefined
+  const id = refToString({ providerID, id: model, ...(variant === undefined ? {} : { variant }) })
+  return parseModelRef(id) ? id : undefined
+}
+
 /** `provider/*` any model of the provider; `provider/model` any variant; `provider/model#variant` exactly. */
 export function allowedBy(models: ReadonlyArray<string>, ref: ModelRef): boolean {
   return models.some((pattern) => {
@@ -80,7 +107,8 @@ export function resolveModel(
     code: "model_not_found",
     param: "model",
   }
-  let ref = parseModelRef(own(options.aliases, model) ?? model)
+  // Aliases keep priority over slugs; a slug and a canonical id both resolve, whatever `modelIds` lists.
+  let ref = parseModelRef(own(options.aliases, model) ?? fromSlug(model) ?? model)
   if (!ref) return notAvailable
   if (!ref.variant && reasoningEffort && find(catalog, { ...ref, variant: reasoningEffort }))
     ref = { ...ref, variant: reasoningEffort }
@@ -96,7 +124,9 @@ export interface ListedModel {
 
 /**
  * The allowlist intersected with the catalog, plus aliases whose target qualifies. Ids are unique except an alias may repeat one.
- * With `app`, the list is narrowed to that app's `models` (see `inAppScope`).
+ * Each model is listed as its canonical id, its slug, or both, per `options.modelIds`; a model whose slug does not
+ * round trip (see `fromSlug`) is left out in `slugs` mode. Aliases are listed as they are.
+ * With `app`, the list is narrowed to that app's `models` (see `inAppScope`), judged on the canonical id.
  */
 export function listAvailableModels(options: PlugboardOptions, catalog: ReadonlyArray<CatalogModel>, app?: string): ListedModel[] {
   const policy = app === undefined ? undefined : appPolicy(options, app)
@@ -110,7 +140,9 @@ export function listAvailableModels(options: PlugboardOptions, catalog: Readonly
       const id = refToString(ref)
       if (seen.has(id) || !allowed(options, ref) || !inAppScope(policy, id, ref)) continue
       seen.add(id)
-      data.push(entry(id, ref, model))
+      if (options.modelIds !== "slugs") data.push(entry(id, ref, model))
+      const slug = toSlug(id)
+      if (options.modelIds !== "canonical" && fromSlug(slug) === id) data.push(entry(slug, ref, model))
     }
   }
   for (const [alias, target] of Object.entries(options.aliases)) {
@@ -121,6 +153,22 @@ export function listAvailableModels(options: PlugboardOptions, catalog: Readonly
   return data
 }
 
+/** Capabilities `GET /v1/models?capability=` can filter on: the flags the catalog reports (`CatalogModel.capabilities`). */
+export type Capability = "vision" | "tools"
+
+const CAPABILITY_FLAG: Readonly<Record<Capability, "image" | "tools">> = { vision: "image", tools: "tools" }
+
+/** The capability a query value names, or undefined for anything else (`json` has no catalog flag, so it is not one). */
+export function parseCapability(value: string): Capability | undefined {
+  return Object.hasOwn(CAPABILITY_FLAG, value) ? (value as Capability) : undefined
+}
+
+/** The listed models whose catalog entry sets that capability flag to true. Order is kept. */
+export function filterByCapability(models: ReadonlyArray<ListedModel>, capability: Capability): ListedModel[] {
+  const flag = CAPABILITY_FLAG[capability]
+  return models.filter(({ model }) => model.capabilities?.[flag] === true)
+}
+
 /**
  * The targets an alias falls back to, in order: the fallbacks that are allowed and enabled on the server.
  * Empty for a plain model id or an alias without fallbacks. The primary target is `resolveModel`'s answer.

package/src/openai/fanout.ts

@@ -23,6 +23,7 @@
 import type { ServerResponse } from "node:http"
 import type { PlugError, PlugEvent, PlugRequest, PlugUsage } from "../contract.js"
 import { reportServed, type ServedInfo } from "../fallback.js"
+import { reportCache } from "../cache.js"
 import { reportPolicy } from "../policy.js"
 import { RequestAborted, boundEvents, sendJson, sseWriter, type RequestScope } from "../http.js"
 import { chatUsageChunk, collectCompletion, encodeError, streamCompletion, type OpenAiExchange, type StreamChoice, type StreamResult } from "./response.js"
@@ -168,6 +169,8 @@ export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls
     if (calls.length === 1) codec.setModel(s.model)
   })
   const policy = reportPolicy(response)
+  // Each choice is a fresh sample: the response cache never serves or stores fan-out calls.
+  const cache = reportCache(response)
   const open = (index: number) =>
     boundEvents(
       host.caller.stream(calls[index]!, {
@@ -180,6 +183,8 @@ export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls
         },
         onServed: served,
         onPolicy: policy,
+        onCache: cache,
+        noCache: calls.length > 1,
       }),
       gscope,
     )

package/src/openai/route.ts

@@ -42,6 +42,7 @@ import { geminiAuthorization, matchGeminiRoute, serveGemini } from "../gemini/ro
 import { errorMessage, log, logError, withRequestId } from "../log.js"
 import { NO_APP, outcomeLabel, type Metrics } from "../metrics.js"
 import { listAvailableModels, resolveModel } from "../models.js"
+import { reportCache } from "../cache.js"
 import { reportPolicy } from "../policy.js"
 import { isMessagesPath, serveMessages } from "../anthropic/route.js"
 import { serveCompletions } from "../completions/route.js"
@@ -193,7 +194,7 @@ export function createOpenAiRoute(routeHost: RouteHost) {
     }
 
     if (route === "GET /metrics" && metrics) {
-      return sendText(response, 200, "text/plain; version=0.0.4; charset=utf-8", metrics.render(runtimeStatus()))
+      return sendText(response, 200, metrics.contentType, await metrics.render(runtimeStatus()))
     }
 
     if (route === "GET /v1/models" || modelId !== undefined) {
@@ -251,6 +252,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),
+        onCache: reportCache(response),
       }),
       scope,
     )

package/src/responses/route.ts

@@ -13,6 +13,7 @@ import { isPlugError, type PlugError, type PlugRequest } from "../contract.js"
 import { reportServed, type ServedInfo } from "../fallback.js"
 import { boundEvents, sendJson, sseWriter, type RequestScope } from "../http.js"
 import { resolveModel } from "../models.js"
+import { reportCache } from "../cache.js"
 import { reportPolicy } from "../policy.js"
 import { encodeError } from "../openai/response.js"
 import type { RouteHost } from "../openai/route.js"
@@ -54,6 +55,7 @@ export async function serveResponses(host: RouteHost, { app, body, response, sco
       },
       onServed: reportServed(response, info, (served) => void (exchange.model = served.model)),
       onPolicy: reportPolicy(response),
+      onCache: reportCache(response),
     }),
     scope,
   )