opencode-plugboard 0.4.1 → 0.5.0

package/README.md

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

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "opencode-plugboard",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "type": "module",
   "license": "MIT",
-  "description": "OpenCode V2 plugin that serves an OpenAI-compatible /v1/chat/completions and /v1/models from your OpenCode server, backed by the providers you already connected there.",
-  "keywords": ["opencode", "opencode-plugin", "openai", "openai-compatible", "chat-completions"],
+  "description": "Use the ChatGPT, Claude, Copilot and OpenCode Go logins in your OpenCode server from any app. An OpenCode V2 plugin serving OpenAI-compatible Chat Completions, Responses and model endpoints.",
+  "keywords": ["opencode", "opencode-plugin", "openai", "openai-compatible", "chat-completions", "responses-api", "llm-gateway", "llm-proxy"],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jjjermiah/opencode-plugboard.git"

package/src/config.ts

@@ -20,6 +20,10 @@ export interface PlugboardOptions {
   readonly history: HistoryLimits
   /** Drop sampling parameters the target model is known to reject (reported in `x-plugboard-dropped-params`). On by default; off forwards them as sent. */
   readonly dropUnsupportedParams: boolean
+  /** Log line format: `text` (`key=value`, the default) or `json` (one object per line). Process-wide: the live generation's value applies. */
+  readonly logFormat: "text" | "json"
+  /** Serve `GET /metrics` (Prometheus text). Off by default; same authentication as `/v1`. */
+  readonly metrics: boolean
 }
 
 export const APP_NAME_PATTERN = /^[a-z0-9-]+$/
@@ -31,7 +35,7 @@ const DEFAULTS = {
   requestTimeoutMs: 600_000,
 } as const
 
-const KNOWN = new Set(["listen", "keys", "models", "aliases", "maxTools", "requestTimeoutMs", "remoteImages", "history", "dropUnsupportedParams"])
+const KNOWN = new Set(["listen", "keys", "models", "aliases", "maxTools", "requestTimeoutMs", "remoteImages", "history", "dropUnsupportedParams", "logFormat", "metrics"])
 const HISTORY_KNOWN = new Set(["maxSessions", "maxAgeDays"])
 /** About 100 years: keeps `maxAgeDays * 86_400_000` a safe integer. */
 const MAX_AGE_DAYS = 36_500
@@ -123,6 +127,10 @@ export function parseOptions(raw: unknown): PlugboardOptions {
   if (input.dropUnsupportedParams !== undefined && typeof input.dropUnsupportedParams !== "boolean")
     throw new Error("plugboard option `dropUnsupportedParams` must be a boolean")
 
+  if (input.logFormat !== undefined && input.logFormat !== "text" && input.logFormat !== "json")
+    throw new Error("plugboard option `logFormat` must be `text` or `json`")
+  if (input.metrics !== undefined && typeof input.metrics !== "boolean") throw new Error("plugboard option `metrics` must be a boolean")
+
   const historyInput = input.history
   if (historyInput !== undefined && !isRecord(historyInput)) throw new Error("plugboard option `history` must be an object")
   for (const key of Object.keys(historyInput ?? {}))
@@ -140,6 +148,8 @@ export function parseOptions(raw: unknown): PlugboardOptions {
     remoteImages: input.remoteImages === true,
     history: { ...(maxSessions === undefined ? {} : { maxSessions }), ...(maxAgeDays === undefined ? {} : { maxAgeDays }) },
     dropUnsupportedParams: input.dropUnsupportedParams !== false,
+    logFormat: input.logFormat === "json" ? "json" : "text",
+    metrics: input.metrics === true,
   }
 }
 

package/src/contract.ts

@@ -20,6 +20,18 @@ export interface ModelRef {
   readonly variant?: string
 }
 
+/**
+ * One price entry, USD per million tokens (the host's `Model.Cost`). An entry with `aboveContext`
+ * applies once the prompt context exceeds that many tokens; the entry without it is the base price.
+ */
+export interface CatalogCost {
+  readonly input: number
+  readonly output: number
+  readonly cacheRead: number
+  readonly cacheWrite: number
+  readonly aboveContext?: number
+}
+
 /** One enabled model as the server sees it: what model listing and the request resolver work from. */
 export interface CatalogModel {
   readonly providerID: string
@@ -28,6 +40,15 @@ export interface CatalogModel {
   readonly variants: ReadonlyArray<string>
   readonly capabilities?: { readonly tools?: boolean; readonly image?: boolean }
   readonly contextLimit?: number
+  /** Token limits as the host reports them (`limit.{context,input,output}`). */
+  readonly limits?: { readonly context?: number; readonly input?: number; readonly output?: number }
+  /** Modalities the model accepts and produces (`capabilities.input` / `.output`, for example `text`, `image`). */
+  readonly modalities?: { readonly input: ReadonlyArray<string>; readonly output: ReadonlyArray<string> }
+  readonly cost?: ReadonlyArray<CatalogCost>
+  readonly status?: "alpha" | "beta" | "deprecated" | "active"
+  readonly family?: string
+  /** Release date, epoch milliseconds. */
+  readonly released?: number
 }
 
 // ---------------------------------------------------------------- request

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),
   })),
 })
 

package/src/openai/route.ts

@@ -1,6 +1,8 @@
 /**
  * OpenAI front-end route table: `GET /healthz`, `GET /v1/models`, `GET /v1/models/{id}`,
  * `POST /v1/chat/completions`, and the dispatch of `POST /v1/responses` to `src/responses/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`).
  *
  * 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;
@@ -10,11 +12,16 @@
  * Response header `x-plugboard-session: <id>` carries the id of the history record the call
  * writes (the `ModelCaller` reports it through `CallContext.onRecord`). It is set before the
  * response headers go out (JSON body or first SSE chunk); an id reported after that is ignored.
+ *
+ * Response header `x-plugboard-request-id: <id>` is set on every response, before anything else
+ * can fail. The same id is the `id` of the request's log line, and of every other log line emitted
+ * while the request is being handled (`withRequestId` in `src/log.ts`).
  */
 
 import type { IncomingMessage, ServerResponse } from "node:http"
-import { authenticate, type PlugboardOptions } from "../config.js"
+import { DEFAULT_APP, authenticate, type PlugboardOptions } from "../config.js"
 import { isPlugError, type CatalogModel, type ModelCaller, type PlugError, type PlugRequest } from "../contract.js"
+import { buildDiscovery, buildStatus, renderDiscoveryHtml, sendText } from "../discovery.js"
 import {
   BodyError,
   RequestAborted,
@@ -28,9 +35,11 @@ import {
   sseWriter,
   type RequestScope,
 } from "../http.js"
-import { errorMessage, log, logError } from "../log.js"
+import { errorMessage, log, logError, withRequestId } from "../log.js"
+import { NO_APP, outcomeLabel, type Metrics } from "../metrics.js"
 import { listAvailableModels, resolveModel } from "../models.js"
 import { serveResponses } from "../responses/route.js"
+import { processMetrics, processStatus, type RuntimeStatus } from "../runtime.js"
 import { parseChatRequest } from "./request.js"
 import { collectCompletion, encodeError, encodeModelList, streamCompletion } from "./response.js"
 import { dropRejected } from "./sampling.js"
@@ -41,12 +50,36 @@ export interface RouteHost {
   readonly caller: ModelCaller
   /** The serving Location's enabled models. */
   loadCatalog(): Promise<ReadonlyArray<CatalogModel>>
+  /** Metrics registry; the process runtime's by default. Only written to when option `metrics` is on. */
+  readonly metrics?: Metrics
+  /** Runtime facts for `/v1/status` and `/metrics`; the process runtime's by default. */
+  readonly status?: () => RuntimeStatus
 }
 
 const SESSION_HEADER = "x-plugboard-session"
+const REQUEST_ID_HEADER = "x-plugboard-request-id"
 const DROPPED_HEADER = "x-plugboard-dropped-params"
 const MODEL_PREFIX = "/v1/models/"
-const KNOWN_ROUTES = ["GET /v1/models", "POST /v1/chat/completions", "POST /v1/responses"]
+const KNOWN_ROUTES = ["GET /v1/models", "POST /v1/chat/completions", "POST /v1/responses", "GET /v1/status"]
+/** Pages anyone may fetch; they decide for themselves how much to show (see `src/discovery.ts`). */
+const DISCOVERY_ROUTES = ["GET /", "GET /v1"]
+/** Allows a page's inline style and nothing else: no scripts, images, fonts or frames. */
+const PAGE_HEADERS = { "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'", "x-frame-options": "DENY", "referrer-policy": "no-referrer" }
+
+/** Records the token usage of every finished model call (see `plugboard_tokens_total`); events pass through untouched. */
+function metered(caller: ModelCaller, metrics: Metrics): ModelCaller {
+  return {
+    stream(request, context) {
+      const inner = caller.stream(request, context)
+      return (async function* () {
+        for await (const event of inner) {
+          if (event.type === "finish" && event.usage) metrics.tokens(context.app, event.usage)
+          yield event
+        }
+      })()
+    },
+  }
+}
 
 const decodeSegment = (raw: string): string => {
   try {
@@ -67,10 +100,28 @@ interface RequestInfo {
   dropped?: string
 }
 
-export function createOpenAiRoute(host: RouteHost) {
+export function createOpenAiRoute(routeHost: RouteHost) {
+  // Metrics are written only when the option is on: off means no bookkeeping, no wrapped event stream.
+  const metrics = routeHost.options.metrics ? (routeHost.metrics ?? processMetrics()) : undefined
+  const runtimeStatus = routeHost.status ?? processStatus
+  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")
+
   const fail = (response: ServerResponse, error: PlugError, close = false) =>
     sendJson(response, error.status, encodeError(error), { close })
 
+  /** The catalog for a page that can do without it: a failure is logged and reported as absent; an abort still ends the request. */
+  async function optionalCatalog(scope: RequestScope): Promise<ReadonlyArray<CatalogModel> | undefined> {
+    try {
+      return await scope.race(host.loadCatalog())
+    } catch (caught) {
+      if (caught instanceof RequestAborted) throw caught
+      logError("catalog.failed", { error: errorMessage(caught) })
+      return undefined
+    }
+  }
+
   /** The route proper. Throws `BodyError`, `RequestAborted` or an unexpected error; `handle` maps them. */
   async function serve(request: IncomingMessage, response: ServerResponse, scope: RequestScope, info: RequestInfo): Promise<void> {
     let url: URL
@@ -83,14 +134,30 @@ export function createOpenAiRoute(host: RouteHost) {
     const modelId = request.method === "GET" && path.startsWith(MODEL_PREFIX) && path.length > MODEL_PREFIX.length ? decodeSegment(path.slice(MODEL_PREFIX.length)) : undefined
     const route = `${request.method} ${modelId !== undefined ? "/v1/models/{id}" : path}`
     // Arbitrary client paths stay out of the log.
-    info.route = modelId !== undefined || KNOWN_ROUTES.includes(route) || route === "GET /healthz" ? route : "unknown"
+    info.route = modelId !== undefined || known(route) || route === "GET /healthz" ? route : "unknown"
 
     const rejected = checkOrigin(request, host.options)
     if (rejected) return fail(response, rejected)
 
     if (route === "GET /healthz") return sendJson(response, 200, { ok: true })
 
-    if (modelId === undefined && !KNOWN_ROUTES.includes(route)) {
+    // First-run pages: reachable without a key, so what they show depends on the caller (`buildDiscovery`).
+    // With `keys` set, a request without credentials gets the minimal page; wrong credentials are a 401.
+    if (DISCOVERY_ROUTES.includes(route)) {
+      const keyed = Object.keys(host.options.keys).length > 0
+      let app: string | undefined = keyed ? undefined : DEFAULT_APP
+      if (keyed && request.headers.authorization !== undefined) {
+        const auth = authenticate(host.options, request.headers.authorization)
+        if (isPlugError(auth)) return fail(response, auth)
+        app = auth.app
+      }
+      info.app = app
+      const doc = buildDiscovery({ options: host.options, app, catalog: app === undefined ? undefined : await optionalCatalog(scope) })
+      if (route === "GET /v1") return sendJson(response, 200, doc)
+      return sendText(response, 200, "text/html; charset=utf-8", renderDiscoveryHtml(doc), PAGE_HEADERS)
+    }
+
+    if (modelId === undefined && !known(route)) {
       return fail(response, {
         status: 404,
         kind: "not_found",
@@ -103,6 +170,15 @@ export function createOpenAiRoute(host: RouteHost) {
     if (isPlugError(auth)) return fail(response, auth)
     info.app = auth.app
 
+    if (route === "GET /v1/status") {
+      const catalog = await optionalCatalog(scope)
+      return sendJson(response, 200, buildStatus({ options: host.options, app: auth.app, runtime: runtimeStatus(), catalog }))
+    }
+
+    if (route === "GET /metrics" && metrics) {
+      return sendText(response, 200, "text/plain; version=0.0.4; charset=utf-8", metrics.render(runtimeStatus()))
+    }
+
     if (route === "GET /v1/models" || modelId !== undefined) {
       const listed = listAvailableModels(host.options, await scope.race(host.loadCatalog()))
       if (modelId === undefined) return sendJson(response, 200, encodeModelList(listed))
@@ -136,6 +212,7 @@ export function createOpenAiRoute(host: RouteHost) {
     if (sampled && sampled.dropped.length > 0) {
       info.dropped = sampled.dropped.join(",")
       response.setHeader(DROPPED_HEADER, info.dropped)
+      metrics?.dropped(sampled.dropped)
     }
     const call: PlugRequest = { ...parsed.request, ...(sampled ? { generation: sampled.generation } : {}), ref }
     const { exchange } = parsed
@@ -179,9 +256,16 @@ export function createOpenAiRoute(host: RouteHost) {
 
   /** Never rejects: every failure ends in a response (or a closed socket) and one log line. */
   return async function handle(request: IncomingMessage, response: ServerResponse): Promise<void> {
+    // Generated here, never taken from the client: the id is echoed and logged, so it must not be attacker-controlled text.
+    const id = crypto.randomUUID().replaceAll("-", "").slice(0, 12)
+    if (!response.headersSent) response.setHeader(REQUEST_ID_HEADER, id)
+    return withRequestId(id, () => run(request, response, id))
+  }
+
+  async function run(request: IncomingMessage, response: ServerResponse, id: string): Promise<void> {
     const started = Date.now()
-    const id = crypto.randomUUID().slice(0, 8)
     const info: RequestInfo = { route: "unparsed" }
+    metrics?.requestStarted()
     const scope = beginRequest(request, response, host.options.requestTimeoutMs)
     let outcome = "ok"
     let error: string | undefined
@@ -221,8 +305,11 @@ export function createOpenAiRoute(host: RouteHost) {
       try {
         finishRequest(request, response)
       } catch {}
-      if (info.route !== "GET /healthz" || outcome !== "ok") {
-        const fields = { id, route: info.route, app: info.app, model: info.model, dropped: info.dropped, status: response.statusCode, ms: Date.now() - started, outcome, error }
+      const ms = Date.now() - started
+      metrics?.requestFinished({ app: info.app ?? NO_APP, route: info.route, status: response.statusCode, outcome: outcomeLabel(outcome, response.statusCode), ms })
+      // Probes and scrapes that succeed are not worth a line each.
+      if ((info.route !== "GET /healthz" && info.route !== "GET /metrics") || outcome !== "ok") {
+        const fields = { id, route: info.route, app: info.app, model: info.model, dropped: info.dropped, status: response.statusCode, ms, outcome, error }
         if (outcome === "error" || response.statusCode >= 500) logError("request.failed", fields)
         else log("request", fields)
       }

package/src/runtime.ts

@@ -19,9 +19,12 @@
  *     requests in flight fail with a 502 instead of waiting for their deadline;
  *   - the session store (src/session/state.ts), which outlives the listener and owns the request
  *     guards, their cleanup timers included;
- *   - the history sweep state: every registered request session is indexed in the host's plugin
+ *  - the history sweep state: every registered request session is indexed in the host's plugin
  *     storage and, at most every `SWEEP_INTERVAL_MS`, a sweep prunes old ones past the `history`
- *     limits (src/session/prune.ts). Both start from request handling (the store's `register`).
+ *     limits (src/session/prune.ts). Both start from request handling (the store's `register`);
+ *  - the metrics registry (src/metrics.ts) and the runtime start time, so counters and uptime
+ *     outlive any one generation. `processMetrics` / `processStatus` read them for `/metrics`,
+ *     `/v1/status` and the discovery pages.
  *
  * Registration is explicit: `registerGeneration` returns whether the generation was accepted. A
  * rejected one (different `listen`, options that differ from the live ones, foreign runtime) never
@@ -43,7 +46,8 @@
 import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http"
 import { Cause, Effect, Stream } from "effect"
 import { isPlugError, type CatalogModel, type PlugError } from "./contract.js"
-import { errorMessage, log, logError } from "./log.js"
+import { errorMessage, log, logError, outsideRequest, setLogFormat } from "./log.js"
+import { createMetrics, type Metrics, type RuntimeSnapshot } from "./metrics.js"
 import { ensureAppDir } from "./session/history.js"
 import type { HistoryPort } from "./session/host.js"
 import { recordSession, sweepHistory, type HistoryLimits } from "./session/prune.js"
@@ -96,8 +100,8 @@ const SWEEP_DEADLINE_MS = 60_000
 const BACKEND_TIMEOUT_MS = 15_000
 const BACKEND_POLL_MS = 25
 
-/** 4: adds the history sweep state and the session store's register hook. 3: confirmed directories and rejected generations. */
-const VERSION = 4
+/** 5: adds the metrics registry and the start time. 4: the history sweep state and the session store's register hook. 3: confirmed directories and rejected generations. */
+const VERSION = 5
 const KEY = Symbol.for("opencode-plugboard.runtime")
 
 interface Listener {
@@ -140,6 +144,10 @@ interface Runtime {
   readonly rejected: Map<string, number>
   /** History sweep rate limit: no sweep starts before `nextAt` (epoch ms) or while one `running`. */
   readonly sweep: { nextAt: number; running: boolean }
+  /** Process-wide counters, shared by every generation (see src/metrics.ts). */
+  readonly metrics: Metrics
+  /** When this runtime was created, epoch ms. */
+  readonly startedAt: number
   listener?: Listener
   /** Present while a fiber is subscribed to the server event bus. */
   pump?: Pump
@@ -149,6 +157,8 @@ const REJECTED: Registration = { accepted: false, dispose() {}, confirmed: () =>
 
 /** Used when a foreign-version runtime owns the process: never registered into, never dispatched to. */
 const detachedSessions = createSessionStore()
+const detachedMetrics = createMetrics()
+const detachedStartedAt = Date.now()
 let foreignVersionLogged = false
 
 /** The process runtime, created on first use; undefined when a different version already owns the process. */
@@ -163,6 +173,8 @@ function runtime(): Runtime | undefined {
       confirmed: new Set(),
       rejected: new Map(),
       sweep: { nextAt: 0, running: false },
+      metrics: createMetrics(),
+      startedAt: Date.now(),
     }
     slot[KEY] = created
     return created
@@ -185,9 +197,12 @@ function trackSession(rt: Runtime, app: string, sessionID: string): void {
   if (!history) return logError("history.index_skipped", { app, sessionID, reason: "no live generation" })
   // No limits, no index: an unbounded index would grow opencode.db by a row per request forever (#85).
   if (history.limits.maxSessions === undefined && history.limits.maxAgeDays === undefined) return
-  void recordSession(history.port, app, sessionID, Date.now())
-    .catch((error) => logError("history.index_failed", { app, sessionID, error: errorMessage(error) }))
-    .then(() => maybeSweep(rt, history))
+  // Not about the request that happened to create the session: its log lines carry no request id.
+  void outsideRequest(() =>
+    recordSession(history.port, app, sessionID, Date.now())
+      .catch((error) => logError("history.index_failed", { app, sessionID, error: errorMessage(error) }))
+      .then(() => maybeSweep(rt, history)),
+  )
 }
 
 /**
@@ -212,10 +227,15 @@ async function maybeSweep(rt: Runtime, history: GenerationInput["history"]): Pro
         timer.unref?.()
       }),
     ])
-    if (!result) return logError("history.sweep_timeout", { limit: SWEEP_DEADLINE_MS })
+    if (!result) {
+      rt.metrics.sweep("timeout", 0)
+      return logError("history.sweep_timeout", { limit: SWEEP_DEADLINE_MS })
+    }
     if (result.more) rt.sweep.nextAt = Date.now() + SWEEP_BACKLOG_MS
+    rt.metrics.sweep("ok", result.removed)
     log("history.swept", { ...result, durationMs: Date.now() - now })
   } catch (error) {
+    rt.metrics.sweep("failed", 0)
     logError("history.sweep_failed", { error: errorMessage(error) })
   } finally {
     clearTimeout(timer)
@@ -226,6 +246,34 @@ async function maybeSweep(rt: Runtime, history: GenerationInput["history"]): Pro
 /** The session store shared by every generation in the process. */
 export const sessionStore = (): SessionStore => runtime()?.sessions ?? detachedSessions
 
+/** The metrics registry shared by every generation in the process (a detached one under a foreign-version runtime). */
+export const processMetrics = (): Metrics => runtime()?.metrics ?? detachedMetrics
+
+/** What `/v1/status` and the discovery pages report about the process, besides the model catalog. */
+export interface RuntimeStatus extends RuntimeSnapshot {
+  readonly runtimeVersion: number
+  /** The shared listener's address, and whether it is bound; absent before the first generation registered. */
+  readonly listener?: { readonly host: string; readonly port: number; readonly bound: boolean }
+  /** The serving generation's Location is a confirmed app directory (else the newest generation serves). */
+  readonly servingConfirmed: boolean
+}
+
+/** A synchronous snapshot of the runtime: no host call, no filesystem. */
+export function processStatus(): RuntimeStatus {
+  const rt = runtime()
+  if (!rt) return { runtimeVersion: VERSION, generations: 0, pumpRunning: false, guards: detachedSessions.size(), startedAt: detachedStartedAt, servingConfirmed: false }
+  const serving = preferred(rt)
+  return {
+    runtimeVersion: rt.version,
+    generations: rt.generations.length,
+    pumpRunning: rt.pump !== undefined,
+    guards: rt.sessions.size(),
+    startedAt: rt.startedAt,
+    servingConfirmed: serving !== undefined && rt.confirmed.has(serving.directory),
+    ...(rt.listener ? { listener: { host: rt.listener.listen.host, port: rt.listener.listen.port, bound: rt.listener.bound } } : {}),
+  }
+}
+
 /** The generation that serves requests and supplies the catalog: the newest confirmed app-directory one, else the newest. */
 function preferred(rt: Runtime): Generation | undefined {
   for (let index = rt.generations.length - 1; index >= 0; index--) if (rt.confirmed.has(rt.generations[index]!.directory)) return rt.generations[index]
@@ -367,6 +415,9 @@ export function registerGeneration(input: GenerationInput): Registration {
     activated: rt.confirmed.has(directory),
   }
   rt.generations.push(generation)
+  // Accepted generations share the live options, so this is the live `logFormat` (log lines are process-wide).
+  const options = input.options as { readonly logFormat?: unknown } | null
+  setLogFormat(options?.logFormat === "json" ? "json" : "text")
   return {
     accepted: true,
     confirmed: () => rt.confirmed.has(directory),
@@ -399,7 +450,8 @@ export function registerGeneration(input: GenerationInput): Registration {
 export function ensurePump(subscribe: () => Stream.Stream<unknown, unknown, never>): void {
   const rt = runtime()
   if (!rt || rt.pump) return
-  const fiber = Effect.runFork(subscribe().pipe(Stream.runForEach((event) => Effect.sync(() => rt.sessions.dispatch(event)))))
+  // The pump serves every request; its log lines must not carry the id of the request that started it.
+  const fiber = outsideRequest(() => Effect.runFork(subscribe().pipe(Stream.runForEach((event) => Effect.sync(() => rt.sessions.dispatch(event))))))
   const pump: Pump = {
     stopped: false,
     stop: () => {

package/src/session/host.ts

@@ -12,7 +12,7 @@
 import type { Plugin } from "@opencode/plugin/effect"
 import type { SessionContext } from "@opencode/plugin/effect/session"
 import { Effect } from "effect"
-import type { CatalogModel } from "../contract.js"
+import type { CatalogCost, CatalogModel } from "../contract.js"
 
 export type HostContext = Plugin.Context
 
@@ -132,9 +132,39 @@ export function createHistoryPort(ctx: HostContext): HistoryPort {
 const record = (value: unknown): Record<string, unknown> | undefined =>
   typeof value === "object" && value !== null ? (value as Record<string, unknown>) : undefined
 
+const finite = (value: unknown): number | undefined => (typeof value === "number" && Number.isFinite(value) ? value : undefined)
+const strings = (value: unknown): string[] | undefined =>
+  Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : undefined
+const STATUSES = new Set(["alpha", "beta", "deprecated", "active"])
+
+/** Host `Model.Cost[]` (USD per million tokens, optional context tier) -> neutral price entries; malformed entries are skipped. */
+function toCosts(raw: unknown): CatalogCost[] | undefined {
+  if (!Array.isArray(raw)) return undefined
+  const costs: CatalogCost[] = []
+  for (const item of raw) {
+    const cost = record(item)
+    const input = finite(cost?.input)
+    const output = finite(cost?.output)
+    if (!cost || input === undefined || output === undefined) continue
+    const cache = record(cost.cache)
+    const tier = record(cost.tier)
+    const size = tier?.type === "context" ? finite(tier.size) : undefined
+    costs.push({
+      input,
+      output,
+      cacheRead: finite(cache?.read) ?? 0,
+      cacheWrite: finite(cache?.write) ?? 0,
+      ...(size === undefined ? {} : { aboveContext: size }),
+    })
+  }
+  return costs
+}
+
 /**
  * Reduces `ctx.model.list` data (V2 `Model.Info`, tolerant of missing fields) to the catalog.
  * Models with `enabled: false` are dropped; `modelID` wins over `id`; variants may be `{ id }` or strings.
+ * Cost, limits, modalities, status, family and release date are carried as the host reports them
+ * (`Model.Info`, packages/schema/src/model.ts); anything absent or malformed is left out.
  */
 function toCatalog(raw: ReadonlyArray<unknown>): CatalogModel[] {
   const catalog: CatalogModel[] = []
@@ -149,7 +179,13 @@ function toCatalog(raw: ReadonlyArray<unknown>): CatalogModel[] {
       .filter((v): v is string => typeof v === "string" && v.length > 0)
     const caps = record(model.capabilities)
     const input = caps && Array.isArray(caps.input) ? caps.input : undefined
-    const context = record(model.limit)?.context
+    const limit = record(model.limit)
+    const context = limit?.context
+    const limits = { context: finite(limit?.context), input: finite(limit?.input), output: finite(limit?.output) }
+    const modalityIn = strings(caps?.input)
+    const modalityOut = strings(caps?.output)
+    const cost = toCosts(model.cost)
+    const released = finite(record(model.time)?.released)
     catalog.push({
       providerID,
       id,
@@ -164,6 +200,14 @@ function toCatalog(raw: ReadonlyArray<unknown>): CatalogModel[] {
           }
         : {}),
       ...(typeof context === "number" ? { contextLimit: context } : {}),
+      ...(limits.context !== undefined || limits.input !== undefined || limits.output !== undefined
+        ? { limits: Object.fromEntries(Object.entries(limits).filter(([, value]) => value !== undefined)) }
+        : {}),
+      ...(modalityIn || modalityOut ? { modalities: { input: modalityIn ?? [], output: modalityOut ?? [] } } : {}),
+      ...(cost && cost.length > 0 ? { cost } : {}),
+      ...(typeof model.status === "string" && STATUSES.has(model.status) ? { status: model.status as NonNullable<CatalogModel["status"]> } : {}),
+      ...(typeof model.family === "string" && model.family ? { family: model.family } : {}),
+      ...(released !== undefined ? { released } : {}),
     })
   }
   return catalog

package/src/session/state.ts

@@ -57,6 +57,8 @@ export interface SessionStore {
   retire(sessionID: string, retirement: Retirement): void
   /** Fail every registered request with `error`; returns how many were registered. */
   failAll(error: PlugError): number
+  /** How many request guards are outstanding (metrics and status only). */
+  size(): number
 }
 
 const EXECUTION_END = new Set(["session.execution.succeeded", "session.execution.failed", "session.execution.interrupted"])
@@ -140,5 +142,6 @@ export function createSessionStore(options: SessionStoreOptions = {}): SessionSt
       }
       return entries.size
     },
+    size: () => entries.size,
   }
 }