opencode-plugboard 0.13.0 → 0.14.0

package/README.md

@@ -30,7 +30,7 @@ export PLUGBOARD_KEY_MY_APP=choose-a-long-random-string
 {
   "plugins": [
     {
-      "package": "opencode-plugboard@0.13.0",
+      "package": "opencode-plugboard@0.14.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,6 +1,6 @@
 {
   "name": "opencode-plugboard",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "type": "module",
   "license": "MIT",
   "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.",
@@ -25,8 +25,10 @@
     "release": "bun .github/scripts/release.ts"
   },
   "dependencies": {
+    "@prometheus-io/client": "0.16.1",
     "escape-html": "1.0.3",
     "ipaddr.js": "2.5.0",
+    "pino": "10.4.0",
     "safe-stable-stringify": "2.5.0"
   },
   "devDependencies": {

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
@@ -117,65 +65,95 @@ export interface Metrics {
   /** 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 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 }),
+    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/openai/route.ts

@@ -193,7 +193,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) {

package/src/runtime.ts

@@ -107,8 +107,8 @@ const BACKEND_POLL_MS = 25
 const BIND_RETRY_MS = 15_000
 const BIND_REMINDER_MS = 5 * 60_000
 
-/** 7: the options fingerprint comes from safe-stable-stringify, so it must not be compared with an older one. 6: the listener retries a failed bind (new fields on `Listener`). 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 = 7
+/** 8: `Metrics.render` is async and the registry is @prometheus-io/client's. 7: the options fingerprint comes from safe-stable-stringify, so it must not be compared with an older one. 6: the listener retries a failed bind (new fields on `Listener`). 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 = 8
 const KEY = Symbol.for("opencode-plugboard.runtime")
 
 interface Listener {