opencode-plugboard 0.4.1 → 0.6.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.6.0",
       "options": {
         "keys": { "my-app": "{env:PLUGBOARD_KEY_MY_APP}" },
         "models": ["anthropic/claude-sonnet-4-6", "github-copilot/*", "opencode-go/glm-5.3-flash"],
@@ -81,10 +81,9 @@ Plugboard is early (0.x) and narrow on purpose.
 - **No concurrency limit per app** yet ([#54](https://github.com/jjjermiah/opencode-plugboard/issues/54), [#86](https://github.com/jjjermiah/opencode-plugboard/issues/86)).
 - **Not a gateway with its own provider keys.** It only reuses what OpenCode is logged in to.
 
-How it differs from the alternatives:
+How it differs from a standalone gateway:
 
-- [KochC/opencode-llm-proxy](https://github.com/KochC/opencode-llm-proxy) serves more API formats but targets OpenCode V1 only. Plugboard is V2 only and adds per-app keys and history, an explicit model allowlist, and rules that keep it from freezing the host (see [AGENTS.md](https://github.com/jjjermiah/opencode-plugboard/blob/main/AGENTS.md)).
-- [LiteLLM](https://github.com/BerriAI/litellm) is a separate gateway you run and give its own provider keys. It covers many more providers and API shapes. Pick it when you want a standalone service. Pick plugboard when OpenCode already holds the logins you want to reuse, such as a ChatGPT or Copilot subscription.
+- [LiteLLM](https://github.com/BerriAI/litellm) is a separate gateway you run and give its own provider keys. It covers many more providers and API shapes. Pick it when you want a standalone service. Pick plugboard when OpenCode already holds the logins you want to reuse, such as a ChatGPT or Copilot subscription. Plugboard also gives each app its own key and history, an explicit model allowlist, and rules that keep it from ever freezing the host.
 
 The most common first failure is an SDK defaulting to `/v1/responses` for newer models. Plugboard serves it, but some clients need `store: false` or a "use chat completions" switch. Check the client's page below.
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "opencode-plugboard",
-  "version": "0.4.1",
+  "version": "0.6.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

@@ -1,6 +1,7 @@
 /** Plugin options: type, defaults, validation, caller authentication and the loopback check. */
 
 import type { PlugError } from "./contract.js"
+import { parseAllowEntry, type RemoteImages } from "./session/media.js"
 import type { HistoryLimits } from "./session/prune.js"
 
 /** Plugin options, after defaults and validation (see `parseOptions`). */
@@ -14,12 +15,21 @@ export interface PlugboardOptions {
   readonly aliases: Readonly<Record<string, string>>
   readonly maxTools: number
   readonly requestTimeoutMs: number
-  /** Fetch http(s) image URLs server-side. Off by default: it is an SSRF vector into the host's network. */
-  readonly remoteImages: boolean
+  /**
+   * Fetch http(s) image URLs server-side. Off by default: it is an SSRF vector into the host's network.
+   * `true` fetches public addresses only (loopback, private, link-local, CGNAT and ULA ranges are refused);
+   * `{ allow }` is on too, and lists the hosts (`name`, `*.suffix`), addresses or CIDR ranges that may be
+   * fetched even when they are not public.
+   */
+  readonly remoteImages: RemoteImages
   /** Prune old request sessions (see `src/session/prune.ts`). A limit that is unset is not applied; with neither, history is kept forever. Applies per app. */
   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 +41,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
@@ -64,6 +74,23 @@ function positiveInt(value: unknown, name: string, fallback: number, max = Numbe
   return value
 }
 
+const REMOTE_IMAGES_ERROR =
+  "plugboard option `remoteImages` must be a boolean or `{ allow: [...] }` with host names, IP addresses or CIDR ranges that may be fetched even when they are not public"
+
+function parseRemoteImages(value: unknown): RemoteImages {
+  if (value === undefined) return false
+  if (typeof value === "boolean") return value
+  if (!isRecord(value)) throw new Error(REMOTE_IMAGES_ERROR)
+  for (const key of Object.keys(value))
+    if (key !== "allow") throw new Error(`Unknown plugboard option \`remoteImages.${key}\` (known: allow)`)
+  const allow = value.allow ?? []
+  if (!Array.isArray(allow)) throw new Error(REMOTE_IMAGES_ERROR)
+  for (const entry of allow)
+    if (typeof entry !== "string" || parseAllowEntry(entry) === undefined)
+      throw new Error(`plugboard \`remoteImages.allow\` entry \`${String(entry)}\` must be a host name (\`images.internal\`, \`*.internal\`), an IP address or a CIDR range`)
+  return { allow: allow as string[] }
+}
+
 /** Validates raw plugin options and applies defaults. Throws `Error` with an actionable message. */
 export function parseOptions(raw: unknown): PlugboardOptions {
   if (raw !== undefined && raw !== null && !isRecord(raw)) throw new Error("plugboard options must be an object")
@@ -118,11 +145,14 @@ export function parseOptions(raw: unknown): PlugboardOptions {
   }
   const aliases: Record<string, string> = Object.fromEntries(aliasEntries)
 
-  if (input.remoteImages !== undefined && typeof input.remoteImages !== "boolean")
-    throw new Error("plugboard option `remoteImages` must be a boolean")
+  const remoteImages = parseRemoteImages(input.remoteImages)
   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 ?? {}))
@@ -137,9 +167,11 @@ export function parseOptions(raw: unknown): PlugboardOptions {
     aliases,
     maxTools: positiveInt(input.maxTools, "maxTools", DEFAULTS.maxTools, 1024),
     requestTimeoutMs: positiveInt(input.requestTimeoutMs, "requestTimeoutMs", DEFAULTS.requestTimeoutMs, MAX_TIMER_MS),
-    remoteImages: input.remoteImages === true,
+    remoteImages,
     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))