opencode-plugboard 0.4.0 → 0.5.0

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