opencode-plugboard 0.19.0 → 0.20.0

package/src/keys.ts

@@ -0,0 +1,172 @@
+/**
+ * Runtime app keys (#55): keys created through `/v1/admin/keys` (src/admin/route.ts), kept beside
+ * the keys of the config.
+ *
+ * Each runtime key is one record in the plugin's host storage (`ctx.storage`, the table the history
+ * index and usage use) under `keys/<id>`, as JSON `{ app, digest, createdAt }`. The digest is the
+ * SHA-256 of the key, so the key value is never stored: it is returned once, by the create call.
+ * The id is the first 8 hex chars of that digest, the name `DELETE` takes; it is safe to show.
+ *
+ * The records are read lazily, from request handling, by the first request that authenticates (never
+ * from plugin setup, I3), and cached on the process runtime (`KeyState`), so the cache outlives a
+ * plugin generation. A failed read leaves the cache unloaded: runtime keys then fail closed (401) and
+ * the next request reads again. Create and revoke write storage first and the cache second, so a
+ * revoked key stops authenticating on the next request.
+ */
+
+import { createHash, randomBytes } from "node:crypto"
+import { APP_NAME_PATTERN } from "./config.js"
+import { errorMessage, logError } from "./log.js"
+import type { StoragePort } from "./session/host.js"
+
+const PREFIX = "keys/"
+const SCAN_PAGE = 200
+/** A collision of two 32-bit ids is rare; a fresh key is drawn instead of sharing an id. */
+const ID_ATTEMPTS = 5
+
+export interface RuntimeKey {
+  readonly id: string
+  readonly app: string
+  readonly digest: Buffer
+  readonly createdAt: string
+}
+
+/** The live cache of runtime keys on the process runtime (src/runtime.ts). */
+export interface KeyState {
+  loaded: boolean
+  readonly keys: Map<string, RuntimeKey>
+}
+
+export const createKeyState = (): KeyState => ({ loaded: false, keys: new Map() })
+
+/** SHA-256 of a key: what is stored and compared. */
+export const keyDigest = (key: string): Buffer => createHash("sha256").update(key).digest()
+
+/** The id of a key: the first 8 hex chars of its digest. */
+export const keyIdOf = (digest: Buffer): string => digest.subarray(0, 4).toString("hex")
+
+export interface KeyListing {
+  readonly id: string
+  readonly app: string
+  readonly source: "config" | "runtime"
+  readonly createdAt?: string
+}
+
+export interface CreatedKey {
+  readonly id: string
+  readonly app: string
+  /** The key value. Returned by `create` only; it is never stored or listed. */
+  readonly key: string
+  readonly createdAt: string
+}
+
+export interface KeyStore {
+  /** The digests of the loaded runtime keys, as `[app, digest]`. Reads storage once; a failed read answers with what is loaded. */
+  digests(): Promise<ReadonlyArray<readonly [string, Buffer]>>
+  /** Config keys and runtime keys, without key values. */
+  list(config: Readonly<Record<string, string>>): Promise<ReadonlyArray<KeyListing>>
+  /** A new random key for `app`. The caller checks the app name and that the config has no key for it. */
+  create(app: string, config: Readonly<Record<string, string>>): Promise<CreatedKey>
+  /** `config` when the id names a config key (not revocable here), `not_found` when no runtime key has it. */
+  revoke(id: string, config: Readonly<Record<string, string>>): Promise<"revoked" | "config" | "not_found">
+}
+
+export interface KeyStoreDeps {
+  readonly state: KeyState
+  readonly storage: StoragePort
+  /** Epoch ms; tests inject a clock. */
+  readonly now?: () => number
+}
+
+const configIds = (config: Readonly<Record<string, string>>): Set<string> => new Set(Object.values(config).map((key) => keyIdOf(keyDigest(key))))
+
+/** A stored record, or undefined when the value is not one (logged; the key then never authenticates). */
+function parseRecord(id: string, raw: string | undefined): RuntimeKey | undefined {
+  try {
+    const value = JSON.parse(raw ?? "") as { app?: unknown; digest?: unknown; createdAt?: unknown }
+    const digest = typeof value.digest === "string" && /^[0-9a-f]{64}$/.test(value.digest) ? Buffer.from(value.digest, "hex") : undefined
+    if (typeof value.app !== "string" || !APP_NAME_PATTERN.test(value.app) || digest === undefined || typeof value.createdAt !== "string") throw new Error("shape")
+    if (keyIdOf(digest) !== id) throw new Error("id")
+    return { id, app: value.app, digest, createdAt: value.createdAt }
+  } catch {
+    logError("keys.unreadable", { id })
+    return undefined
+  }
+}
+
+export function createKeyStore(deps: KeyStoreDeps): KeyStore {
+  const { state, storage } = deps
+  const now = deps.now ?? Date.now
+  let loading: Promise<void> | undefined
+
+  /** Reads every stored key once. Concurrent callers share one read. */
+  const ensure = (): Promise<void> => {
+    if (state.loaded) return Promise.resolve()
+    loading ??= (async () => {
+      const found = new Map<string, RuntimeKey>()
+      let after: string | undefined
+      for (;;) {
+        const page = await storage.scan({ prefix: PREFIX, ...(after === undefined ? {} : { after }), limit: SCAN_PAGE })
+        for (const key of page.keys) {
+          const record = parseRecord(key.slice(PREFIX.length), await storage.get(key))
+          if (record) found.set(record.id, record)
+        }
+        if (page.next === undefined) break
+        after = page.next
+      }
+      state.keys.clear()
+      for (const [id, record] of found) state.keys.set(id, record)
+      state.loaded = true
+    })().finally(() => {
+      loading = undefined
+    })
+    return loading
+  }
+
+  return {
+    async digests() {
+      try {
+        await ensure()
+      } catch (error) {
+        logError("keys.load_failed", { error: errorMessage(error) })
+      }
+      return [...state.keys.values()].map((record) => [record.app, record.digest] as const)
+    },
+
+    async list(config) {
+      await ensure()
+      const runtime = [...state.keys.values()].sort((a, b) => (a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : 0))
+      return [
+        ...Object.entries(config).map(([app, key]) => ({ id: keyIdOf(keyDigest(key)), app, source: "config" as const })),
+        ...runtime.map((record) => ({ id: record.id, app: record.app, source: "runtime" as const, createdAt: record.createdAt })),
+      ]
+    },
+
+    async create(app, config) {
+      await ensure()
+      const taken = configIds(config)
+      for (let attempt = 0; attempt < ID_ATTEMPTS; attempt++) {
+        const key = randomBytes(32).toString("base64url")
+        const digest = keyDigest(key)
+        const id = keyIdOf(digest)
+        if (taken.has(id) || state.keys.has(id)) continue
+        const createdAt = new Date(now()).toISOString()
+        // Storage first: a failed write creates no key, and the value is never returned for a key that does not exist.
+        await storage.put(PREFIX + id, JSON.stringify({ app, digest: digest.toString("hex"), createdAt }))
+        state.keys.set(id, { id, app, digest, createdAt })
+        return { id, app, key, createdAt }
+      }
+      throw new Error("could not draw an unused key id")
+    },
+
+    async revoke(id, config) {
+      await ensure()
+      if (configIds(config).has(id)) return "config"
+      if (!state.keys.has(id)) return "not_found"
+      // Storage first: if the delete fails the key keeps working and the caller can retry.
+      await storage.drop(PREFIX + id)
+      state.keys.delete(id)
+      return "revoked"
+    },
+  }
+}

package/src/models.ts

@@ -3,6 +3,12 @@
 import { appPolicy, type AppPolicy, type PlugboardOptions } from "./config.js"
 import type { CatalogModel, ModelRef, PlugError } from "./contract.js"
 
+/** Alias target prefix that binds a skill: `skill:<id>@provider/model[#variant]` (see `parseAliasTarget`). */
+export const SKILL_PREFIX = "skill:"
+/** Listed id prefix of an agent (option `agents`): `agent/<name>`. Aliases cannot contain `/`, so the two never collide. */
+export const AGENT_PREFIX = "agent/"
+const SKILL_TARGET = /^skill:([^@\s#*/]+)@([^@/#*\s]+\/[^@#*\s]+(#[^#*\s]+)?)$/
+
 /** `provider/model[#variant]`. The model id may contain slashes (`openrouter/vendor/model`). */
 export function parseModelRef(s: string): ModelRef | undefined {
   if (typeof s !== "string") return undefined
@@ -58,6 +64,42 @@ export function allowedBy(models: ReadonlyArray<string>, ref: ModelRef): boolean
 
 const allowed = (options: PlugboardOptions, ref: ModelRef): boolean => allowedBy(options.models, ref)
 
+/** An alias target as written in `aliases`: `provider/model[#variant]`, or `skill:<id>@` in front of one. */
+export interface AliasTarget {
+  readonly ref: ModelRef
+  /** The skill the alias binds, for a `skill:` target. */
+  readonly skill?: string
+}
+
+/** The model (and skill) an alias target names, or undefined when it is neither form. */
+export function parseAliasTarget(target: string): AliasTarget | undefined {
+  if (!target.startsWith(SKILL_PREFIX)) {
+    const ref = parseModelRef(target)
+    return ref === undefined ? undefined : { ref }
+  }
+  const match = SKILL_TARGET.exec(target)
+  const ref = match ? parseModelRef(match[2]!) : undefined
+  return match && ref ? { ref, skill: match[1]! } : undefined
+}
+
+/**
+ * What a request name stands for, beyond a plain model: a skill alias (its skill id) or an agent (its name
+ * in option `agents`). Undefined for plain model ids and plain aliases. The caller reads it to add the
+ * skill's content or the agent's system prompt to the session.
+ */
+export type Persona = { readonly kind: "skill"; readonly skill: string } | { readonly kind: "agent"; readonly agent: string }
+
+export function personaOf(options: Pick<PlugboardOptions, "aliases" | "agents">, name: string): Persona | undefined {
+  const target = own(options.aliases, name)
+  if (target !== undefined) {
+    const skill = parseAliasTarget(target)?.skill
+    return skill === undefined ? undefined : { kind: "skill", skill }
+  }
+  if (!name.startsWith(AGENT_PREFIX)) return undefined
+  const agent = name.slice(AGENT_PREFIX.length)
+  return Object.hasOwn(options.agents, agent) ? { kind: "agent", agent } : undefined
+}
+
 /**
  * Per-app narrowing (`apps.<name>.models`), applied on top of the global allowlist, never instead of it.
  * `name` is what the caller sent (an alias or a model id). An entry that is an alias name admits that
@@ -108,7 +150,15 @@ export function resolveModel(
     param: "model",
   }
   // Aliases keep priority over slugs; a slug and a canonical id both resolve, whatever `modelIds` lists.
-  let ref = parseModelRef(own(options.aliases, model) ?? fromSlug(model) ?? model)
+  // An agent runs on the model its `agents` entry names (the allowlist still applies below).
+  const target = own(options.aliases, model)
+  const persona = personaOf(options, model)
+  let ref =
+    target !== undefined
+      ? parseAliasTarget(target)?.ref
+      : persona?.kind === "agent"
+        ? parseModelRef(options.agents[persona.agent]!)
+        : parseModelRef(fromSlug(model) ?? model)
   if (!ref) return notAvailable
   if (!ref.variant && reasoningEffort && find(catalog, { ...ref, variant: reasoningEffort }))
     ref = { ...ref, variant: reasoningEffort }
@@ -120,6 +170,10 @@ export interface ListedModel {
   readonly id: string
   readonly ref: ModelRef
   readonly model: CatalogModel
+  /** The skill an alias binds (`skill:` target), listed as `plugboard.skill`. */
+  readonly skill?: string
+  /** The agent an `agent/<name>` id runs, listed as `plugboard.agent`. */
+  readonly agent?: string
 }
 
 /**
@@ -146,9 +200,16 @@ export function listAvailableModels(options: PlugboardOptions, catalog: Readonly
     }
   }
   for (const [alias, target] of Object.entries(options.aliases)) {
-    const ref = parseModelRef(target)
+    const parsed = parseAliasTarget(target)
+    const ref = parsed?.ref
     const model = ref && allowed(options, ref) && inAppScope(policy, alias, ref) ? find(catalog, ref) : undefined
-    if (ref && model) data.push(entry(alias, ref, model))
+    if (ref && model) data.push({ ...entry(alias, ref, model), ...(parsed.skill === undefined ? {} : { skill: parsed.skill }) })
+  }
+  for (const [name, target] of Object.entries(options.agents)) {
+    const id = `${AGENT_PREFIX}${name}`
+    const ref = parseModelRef(target)
+    const model = ref && allowed(options, ref) && inAppScope(policy, id, ref) ? find(catalog, ref) : undefined
+    if (ref && model) data.push({ ...entry(id, ref, model), agent: name })
   }
   return data
 }

package/src/openai/fanout.ts

@@ -26,6 +26,7 @@ import { reportServed, type ServedInfo } from "../fallback.js"
 import { reportCache } from "../cache.js"
 import { reportPolicy } from "../policy.js"
 import { reportUsage } from "../usage-header.js"
+import { SESSION_URL_HEADER, sessionUrl } from "../session/link.js"
 import { RequestAborted, boundEvents, sendError, sendJson, sseWriter, type RequestScope } from "../http.js"
 import { chatUsageChunk, collectCompletion, encodeError, streamCompletion, type OpenAiExchange, type StreamChoice, type StreamResult } from "./response.js"
 import type { RouteHost } from "./route.js"
@@ -155,7 +156,7 @@ const addUsage = (a: PlugUsage, b: PlugUsage): PlugUsage => {
   return out
 }
 
-export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls, response, scope, info, codec }: ChoicesCall): Promise<void> {
+export async function serveChoices(host: Pick<RouteHost, "caller" | "options">, { app, calls, response, scope, info, codec }: ChoicesCall): Promise<void> {
   const fail = (error: PlugError) => sendError(response, error, encodeError(error))
   // Abandoned requests (client gone, deadline passed) must never reach the model caller.
   if (scope.signal.aborted) throw scope.signal.reason
@@ -165,6 +166,8 @@ export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls
   const gscope = groupScope(scope, AbortSignal.any([scope.signal, group.signal]))
   /** History record ids as the callers report them, in choice order, for the response header (comma separated). */
   const records: Array<string | undefined> = []
+  /** The session page links of the same records, in choice order (option `historyUrl`, src/session/link.ts). */
+  const links: Array<string | undefined> = []
   // Headers: the first choice to be served wins. Body model: only a single call echoes the served model.
   const served = reportServed(response, info, (s) => {
     if (calls.length === 1) codec.setModel(s.model)
@@ -179,10 +182,15 @@ export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls
       host.caller.stream(calls[index]!, {
         app,
         signal: gscope.signal,
-        onRecord: (recordID) => {
+        onRecord: (recordID, directory) => {
           if (response.headersSent || response.destroyed || !/^[\x21-\x7e]+$/.test(recordID)) return
           records[index] = recordID
           response.setHeader(SESSION_HEADER, records.filter((id) => id !== undefined).join(","))
+          if (host.options.historyUrl !== undefined) {
+            links[index] = sessionUrl(host.options.historyUrl, recordID, directory)
+            info.sessionUrl = links.filter((link) => link !== undefined).join(",")
+            response.setHeader(SESSION_URL_HEADER, info.sessionUrl)
+          }
         },
         onServed: served,
         onPolicy: policy,

package/src/openai/request.ts

@@ -6,6 +6,7 @@
  * the request omits `ref`.
  */
 import type { PlugboardOptions } from "../config.js"
+import { bodyUser, userField } from "../user.js"
 import {
   isPlugError,
   type PlugError,
@@ -322,6 +323,7 @@ export function parseChatRequest(body: unknown, options: PlugboardOptions): Pars
 
   const forced: PlugToolChoice | undefined = respond ? (withCallerTools ? "required" : { type: "tool", name: RESPOND_TOOL }) : toolChoice
   const request: Omit<PlugRequest, "ref"> = {
+    ...userField(bodyUser(body)),
     model: body.model,
     system: format.instruction ? [...parsed.system, format.instruction] : parsed.system,
     messages: parsed.messages,

package/src/openai/response.ts

@@ -111,12 +111,12 @@ const encodePlugboard = (model: ListedModel["model"]) => ({
 /** `GET /v1/models` body. */
 export const encodeModelList = (models: ReadonlyArray<ListedModel>): object => ({
   object: "list",
-  data: models.map(({ id, ref, model }) => ({
+  data: models.map(({ id, ref, model, skill, agent }) => ({
     id,
     object: "model",
     created: 0,
     owned_by: ref.providerID,
-    plugboard: encodePlugboard(model),
+    plugboard: { ...encodePlugboard(model), ...(skill === undefined ? {} : { skill }), ...(agent === undefined ? {} : { agent }) },
   })),
 })
 

package/src/openai/route.ts

@@ -21,6 +21,7 @@
  */
 
 import type { IncomingMessage, ServerResponse } from "node:http"
+import { serveAdmin } from "../admin/route.js"
 import { DEFAULT_APP, authenticate, authenticateUsage, 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"
@@ -52,9 +53,12 @@ import { serveCompletions } from "../completions/route.js"
 import { serveResponses } from "../responses/route.js"
 import { liveOptions, processMetrics, processStatus, type RuntimeStatus } from "../runtime.js"
 import { budgetFor, budgetStatus } from "../budgets.js"
+import type { KeyStore } from "../keys.js"
 import type { UsageRecorder } from "../usage.js"
 import { DASHBOARD_ROUTES } from "../dashboard/page.js"
 import { serveDashboard } from "../dashboard/assets.js"
+import { bodyUser, noteEndUser } from "../user.js"
+import { setSessionLink } from "../session/link.js"
 import { chatCodec, serveChoices } from "./fanout.js"
 import { parseChatRequest } from "./request.js"
 import { collectCompletion, encodeError, encodeModelList, streamCompletion } from "./response.js"
@@ -72,6 +76,8 @@ export interface RouteHost {
   readonly status?: () => RuntimeStatus
   /** Per-app usage (`src/usage.ts`): fed from the request log point, and served by `GET /v1/usage` when present. */
   readonly usage?: UsageRecorder
+  /** Runtime app keys (src/keys.ts, #55): their digests authenticate, and the admin routes (src/admin/route.ts) read them. */
+  readonly keys?: KeyStore
 }
 
 const SESSION_HEADER = "x-plugboard-session"
@@ -116,6 +122,8 @@ interface RequestInfo extends ServedInfo {
   failed?: string
   /** Sampling parameters dropped for this model (comma list), when any. */
   dropped?: string
+  /** The end user the body named, when kept (src/user.ts). */
+  user?: string
 }
 
 export function createOpenAiRoute(routeHost: RouteHost) {
@@ -123,6 +131,8 @@ export function createOpenAiRoute(routeHost: RouteHost) {
   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
+  /** The runtime app keys that authenticate (loaded from storage on first use, #55). */
+  const runtimeDigests = async () => (host.keys ? await host.keys.digests() : [])
   /** 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) ||
@@ -176,7 +186,7 @@ export function createOpenAiRoute(routeHost: RouteHost) {
       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(liveOptions(host.options), request.headers.authorization)
+        const auth = authenticate(liveOptions(host.options), request.headers.authorization, await runtimeDigests())
         if (isPlugError(auth)) return fail(response, auth)
         app = auth.app
       }
@@ -192,9 +202,13 @@ export function createOpenAiRoute(routeHost: RouteHost) {
     // Usage has its own credentials: the admin key reads every app, any other key only its own app (`authenticateUsage`).
     if (route === "GET /v1/usage" && host.usage) return serveUsage(request, response, url, host.usage, info)
 
+    // Runtime app keys (#55): the admin routes answer the admin key only, and are a 404 without `adminKey`.
+    if (path === "/v1/admin/keys" || path.startsWith("/v1/admin/keys/"))
+      return serveAdmin({ options: liveOptions(host.options), keys: host.keys }, { path, request, response, scope, info })
+
     // Authenticate before anything reveals which routes exist: an unauthenticated caller sees 401 for every path but /healthz and the first-run pages.
     // Gemini clients also send the key as `x-goog-api-key` or `?key=` (see `geminiAuthorization`).
-    const auth = authenticate(liveOptions(host.options), googleShaped ? geminiAuthorization(request, url) : request.headers.authorization)
+    const auth = authenticate(liveOptions(host.options), googleShaped ? geminiAuthorization(request, url) : request.headers.authorization, await runtimeDigests())
     if (isPlugError(auth)) return fail(response, auth)
     info.app = auth.app
 
@@ -253,6 +267,7 @@ export function createOpenAiRoute(routeHost: RouteHost) {
     if (unsupported) return fail(response, unsupported)
 
     const body = await readJsonBody(request, scope.signal)
+    noteEndUser(response, info, bodyUser(body))
     if (route === "POST /v1/responses") return serveResponses(host, { app: auth.app, body, response, scope, info })
     if (route === "POST /v1/completions") return serveCompletions(host, { app: auth.app, body, response, scope, info })
     const parsed = parseChatRequest(body, host.options)
@@ -280,9 +295,10 @@ export function createOpenAiRoute(routeHost: RouteHost) {
       host.caller.stream(call, {
         app: auth.app,
         signal: scope.signal,
-        onRecord: (recordID) => {
+        onRecord: (recordID, directory) => {
           if (response.headersSent || response.destroyed || !/^[\x21-\x7e]+$/.test(recordID)) return
           response.setHeader(SESSION_HEADER, recordID)
+          setSessionLink(response, info, host.options.historyUrl, recordID, directory)
         },
         // An alias with fallbacks: report which target answered, and echo it as the response model.
         onServed: reportServed(response, info, (served) => void (exchange.model = served.model)),
@@ -318,7 +334,7 @@ export function createOpenAiRoute(routeHost: RouteHost) {
 
   /** `GET /v1/usage?from=&to=&app=`. An app key may name only its own app (another one is a 403); the admin key may name any app or none. */
   async function serveUsage(request: IncomingMessage, response: ServerResponse, url: URL, usage: UsageRecorder, info: RequestInfo): Promise<void> {
-    const who = authenticateUsage(liveOptions(host.options), request.headers.authorization)
+    const who = authenticateUsage(liveOptions(host.options), request.headers.authorization, await runtimeDigests())
     if (isPlugError(who)) return fail(response, who)
     const app = url.searchParams.get("app") ?? undefined
     if (!who.admin) {
@@ -330,6 +346,7 @@ export function createOpenAiRoute(routeHost: RouteHost) {
       from: url.searchParams.get("from") ?? undefined,
       to: url.searchParams.get("to") ?? undefined,
       app: who.admin ? app : who.app,
+      user: url.searchParams.get("user") || undefined,
     })
     if (isPlugError(report)) return fail(response, report)
     // Each app's budget state, read from its current window rather than from the report's range (src/budgets.ts).
@@ -396,10 +413,10 @@ export function createOpenAiRoute(routeHost: RouteHost) {
       } catch {}
       const ms = Date.now() - started
       metrics?.requestFinished({ app: info.app ?? NO_APP, route: info.route, status: response.statusCode, outcome: outcomeLabel(outcome, response.statusCode), ms })
-      if (info.app !== undefined) host.usage?.request({ app: info.app, route: info.route, status: response.statusCode, outcome: outcomeLabel(outcome, response.statusCode), ms })
+      if (info.app !== undefined) host.usage?.request({ app: info.app, route: info.route, status: response.statusCode, outcome: outcomeLabel(outcome, response.statusCode), ms, ...(info.user === undefined ? {} : { user: info.user }) })
       // 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, served: info.served, fallbacks: info.fallbacks, dropped: info.dropped, status: response.statusCode, ms, outcome, error }
+        const fields = { id, route: info.route, app: info.app, user: info.user, session_url: info.sessionUrl, model: info.model, served: info.served, fallbacks: info.fallbacks, 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/responses/request.ts

@@ -10,6 +10,7 @@
  * `ModelRef` afterwards, which is why the request omits `ref`.
  */
 import type { PlugboardOptions } from "../config.js"
+import { bodyUser, userField } from "../user.js"
 import {
   isPlugError,
   type PlugError,
@@ -353,6 +354,7 @@ export function parseResponsesRequest(body: unknown, options: PlugboardOptions,
   const instructions = typeof body.instructions === "string" && body.instructions.length > 0 ? [body.instructions] : []
   const system = [...instructions, ...parsed.system, ...(format.instruction ? [format.instruction] : [])]
   const request: Omit<PlugRequest, "ref"> = {
+    ...userField(bodyUser(body)),
     model: body.model,
     system,
     messages: parsed.messages,

package/src/responses/route.ts

@@ -16,6 +16,7 @@ import { resolveModel } from "../models.js"
 import { reportCache } from "../cache.js"
 import { reportPolicy } from "../policy.js"
 import { reportUsage } from "../usage-header.js"
+import { setSessionLink } from "../session/link.js"
 import { encodeError } from "../openai/response.js"
 import type { RouteHost } from "../openai/route.js"
 import { parseResponsesRequest } from "./request.js"
@@ -51,9 +52,10 @@ export async function serveResponses(host: RouteHost, { app, body, response, sco
     host.caller.stream(call, {
       app,
       signal: scope.signal,
-      onRecord: (recordID) => {
+      onRecord: (recordID, directory) => {
         if (response.headersSent || response.destroyed || !/^[\x21-\x7e]+$/.test(recordID)) return
         response.setHeader(SESSION_HEADER, recordID)
+        setSessionLink(response, info, host.options.historyUrl, recordID, directory)
       },
       onServed: reportServed(response, info, (served) => void (exchange.model = served.model)),
       onPolicy: reportPolicy(response),

package/src/rpc.ts

@@ -26,6 +26,7 @@ export const UsageRpc = Rpc.define({
           from: { type: "string", description: "First UTC day, YYYY-MM-DD. Default: 29 days before `to`." },
           to: { type: "string", description: "Last UTC day, YYYY-MM-DD. Default: today." },
           app: { type: "string", description: "One app name. Default: every app." },
+          user: { type: "string", description: "One end user id. Each app's `users` then lists only that user. Default: every user." },
         },
         additionalProperties: false,
       },
@@ -37,7 +38,7 @@ export const UsageRpc = Rpc.define({
       errors: {
         invalid_query: {
           type: "object",
-          properties: { param: { type: "string", description: "The query parameter that is wrong: from, to or app." } },
+          properties: { param: { type: "string", description: "The query parameter that is wrong: from, to, app or user." } },
           required: ["param"],
           additionalProperties: false,
         },
@@ -51,7 +52,7 @@ export const UsageRpc = Rpc.define({
 function queryOf(input: unknown): UsageQuery {
   const record: Record<string, unknown> = typeof input === "object" && input !== null ? (input as Record<string, unknown>) : {}
   const text = (value: unknown) => (typeof value === "string" ? value : undefined)
-  return { from: text(record.from), to: text(record.to), app: text(record.app) }
+  return { from: text(record.from), to: text(record.to), app: text(record.app), user: text(record.user) }
 }
 
 /** The handlers for `UsageRpc`, reading the given usage query (the generation's recorder). */

package/src/runtime.ts

@@ -53,6 +53,7 @@ import { Cause, Effect, Stream } from "effect"
 import stableStringify from "safe-stable-stringify"
 import { raceAbort } from "./abort.js"
 import { cachedCaller, createCacheStore, type CacheStore } from "./cache.js"
+import { personaOf } from "./models.js"
 import type { PlugboardOptions } from "./config.js"
 import { isPlugError, type CatalogModel, type ModelCaller, type PlugError } from "./contract.js"
 import { errorMessage, log, logError, outsideRequest, setLogFormat } from "./log.js"
@@ -63,6 +64,7 @@ import type { HistoryPort } from "./session/host.js"
 import { recordSession, sweepHistory, type HistoryLimits } from "./session/prune.js"
 import { createSessionStore, type SessionStore } from "./session/state.js"
 import { createBudgetState, type BudgetState } from "./budgets.js"
+import { createKeyState, type KeyState } from "./keys.js"
 import { createUsageState, type UsageState } from "./usage.js"
 
 export type Handler = (request: IncomingMessage, response: ServerResponse) => void
@@ -116,8 +118,8 @@ const BACKEND_POLL_MS = 25
 const BIND_RETRY_MS = 15_000
 const BIND_REMINDER_MS = 5 * 60_000
 
-/** 13: the budget warning state (`src/budgets.ts`) lives here too. 12: the live key set (`keys`, `Runtime.keys`) that a stricter newer generation replaces at once (#90). 11: the usage store's live days (`src/usage.ts`) live here too. 10: the response cache store (`src/cache.ts`) lives here too. 9: the request limiter state (`src/limits.ts`) lives here, so the concurrency caps and rate windows survive a generation. 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 = 13
+/** 14: the runtime app keys (src/keys.ts, #55) are cached here, so a key created or revoked through the admin routes holds across plugin generations. 13: the budget warning state (`src/budgets.ts`) lives here too. 12: the live key set (`keys`, `Runtime.keys`) that a stricter newer generation replaces at once (#90). 11: the usage store's live days (`src/usage.ts`) live here too. 10: the response cache store (`src/cache.ts`) lives here too. 9: the request limiter state (`src/limits.ts`) lives here, so the concurrency caps and rate windows survive a generation. 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 = 14
 const KEY = Symbol.for("opencode-plugboard.runtime")
 
 interface Listener {
@@ -183,6 +185,8 @@ interface Runtime {
   readonly usage: UsageState
   /** The budget warnings already logged (src/budgets.ts). */
   readonly budgets: BudgetState
+  /** The runtime app keys (src/keys.ts), loaded from storage on the first authentication. */
+  readonly runtimeKeys: KeyState
   listener?: Listener
   /** Present while a fiber is subscribed to the server event bus. */
   pump?: Pump
@@ -197,6 +201,7 @@ const detachedStartedAt = Date.now()
 const detachedLimits = createLimitState()
 const detachedUsage = createUsageState()
 const detachedBudgets = createBudgetState()
+const detachedKeys = createKeyState()
 let foreignVersionLogged = false
 
 /** The process runtime, created on first use; undefined when a different version already owns the process. */
@@ -215,6 +220,7 @@ function runtime(): Runtime | undefined {
       limits: createLimitState(),
       usage: createUsageState(),
       budgets: createBudgetState(),
+      runtimeKeys: createKeyState(),
       startedAt: Date.now(),
     }
     slot[KEY] = created
@@ -299,6 +305,9 @@ export const processUsage = (): UsageState => runtime()?.usage ?? detachedUsage
 /** The budget warning state shared by every generation in the process (detached under a foreign-version runtime). */
 export const processBudgets = (): BudgetState => runtime()?.budgets ?? detachedBudgets
 
+/** The runtime app keys' cache shared by every generation in the process (detached under a foreign-version runtime). */
+export const processKeys = (): KeyState => runtime()?.runtimeKeys ?? detachedKeys
+
 /**
  * The options authentication reads: `keys` is the live key set, not the serving generation's own
  * (a generation that is still live after a key revocation keeps its old keys otherwise, #90).
@@ -336,7 +345,7 @@ export function withResponseCache(caller: ModelCaller, options: PlugboardOptions
       if (rt) rt.cache = held
     }
     const count = options.metrics ? (app: string, result: "hit" | "miss") => processMetrics().cache(app, result) : undefined
-    return cachedCaller(caller, config, held.store, count)
+    return cachedCaller(caller, config, held.store, count, (model) => personaOf(options, model) !== undefined)
   }
   return { stream: (request, context) => (wrapped ??= build()).stream(request, context) }
 }