opencode-plugboard 0.19.0 → 0.20.0

package/README.md

@@ -43,7 +43,7 @@ export PLUGBOARD_KEY_MY_APP=choose-a-long-random-string
 {
   "plugins": [
     {
-      "package": "opencode-plugboard@0.19.0",
+      "package": "opencode-plugboard@0.20.0",
       "options": {
         "keys": { "my-app": "{env:PLUGBOARD_KEY_MY_APP}" },
         "models": ["anthropic/claude-sonnet-4-6", "github-copilot/*", "opencode-go/glm-5.3-flash"],
@@ -390,7 +390,7 @@ A server shared by a Discord bot, n8n, Open WebUI and a coding agent, with most
 {
   "plugins": [
     {
-      "package": "opencode-plugboard@0.19.0",
+      "package": "opencode-plugboard@0.20.0",
       "options": {
         // Reachable from the LAN. Non-loopback hosts refuse to start without keys.
         "listen": { "host": "10.0.1.50", "port": 4010 },

package/index.ts

@@ -21,15 +21,17 @@
 import { Plugin } from "@opencode/plugin/effect"
 import { Effect } from "effect"
 import { parseOptions } from "./src/config.js"
+import { personaOf } from "./src/models.js"
 import { errorMessage, logError } from "./src/log.js"
 import { withFallbacks } from "./src/fallback.js"
 import { withBudgets } from "./src/budgets.js"
 import { withLimits } from "./src/limits.js"
 import { createOpenAiRoute } from "./src/openai/route.js"
-import { ensureBackend, ensurePump, loadServingCatalog, processBudgets, processLimits, processMetrics, processUsage, registerGeneration, sessionStore, withResponseCache } from "./src/runtime.js"
+import { ensureBackend, ensurePump, loadServingCatalog, processBudgets, processKeys, processLimits, processMetrics, processUsage, registerGeneration, sessionStore, withResponseCache } from "./src/runtime.js"
 import { createSessionCaller } from "./src/session/caller.js"
 import { installSessionHooks } from "./src/session/context.js"
 import { createHistoryPort, createSessionPort, createStoragePort, loadCatalog } from "./src/session/host.js"
+import { createKeyStore } from "./src/keys.js"
 import { usageHandlers, UsageRpc } from "./src/rpc.js"
 import { createUsageRecorder, withUsage } from "./src/usage.js"
 
@@ -59,6 +61,7 @@ export default Plugin.define({
         sessions,
         maxTools: options.maxTools,
         apps: options.apps,
+        persona: (model: string) => personaOf(options, model),
         remoteImages: options.remoteImages,
         // The readiness gate the caller awaits before creating a session (fails closed: 503 `backend_unavailable`).
         ensureBackend: (app: string, signal: AbortSignal) => ensureBackend(app, signal, bootLocation),
@@ -118,6 +121,8 @@ export default Plugin.define({
         ),
         loadCatalog: servingCatalog,
         usage,
+        // Runtime app keys (#55): read from storage on the first authentication, cached on the runtime.
+        keys: createKeyStore({ state: processKeys(), storage: createStoragePort(ctx) }),
       })
       const registration = registerGeneration({
         listen: options.listen,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-plugboard",
-  "version": "0.19.0",
+  "version": "0.20.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, Anthropic and Gemini compatible APIs.",

package/src/admin/route.ts

@@ -0,0 +1,81 @@
+/**
+ * Admin routes for runtime app keys (#55): `GET /v1/admin/keys` (keys without values),
+ * `POST /v1/admin/keys` with body `{ "app": "<name>" }` (a new random key, returned once) and
+ * `DELETE /v1/admin/keys/{keyId}` (revokes a runtime key; a config key is a 409).
+ *
+ * The routes exist only when option `adminKey` is set: without it every path here is a 404. Only the
+ * admin key passes; an app key, a wrong key or no key is a 401. src/openai/route.ts dispatches here
+ * after the origin check and before app authentication, so an app key never reaches them.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http"
+import { APP_NAME_PATTERN, DEFAULT_APP, authenticateUsage, type PlugboardOptions } from "../config.js"
+import { isPlugError, type PlugError } from "../contract.js"
+import { checkJsonContentType, readJsonBody, sendError, sendJson, type RequestScope } from "../http.js"
+import type { KeyStore } from "../keys.js"
+import { log } from "../log.js"
+import { encodeError } from "../openai/response.js"
+
+export interface AdminHost {
+  /** The live options (`liveOptions`): the config keys, and `adminKey`. */
+  readonly options: PlugboardOptions
+  /** The runtime key store; absent means the admin routes are not served. */
+  readonly keys?: KeyStore
+}
+
+export interface AdminCall {
+  readonly path: string
+  readonly request: IncomingMessage
+  readonly response: ServerResponse
+  readonly scope: RequestScope
+  /** The route's log fields: the route name is set here, so the request log names the admin route. */
+  readonly info: { route: string; app?: string }
+}
+
+const KEYS = "/v1/admin/keys"
+const ONE_KEY = /^\/v1\/admin\/keys\/([0-9a-f]{8})$/
+
+export async function serveAdmin(host: AdminHost, call: AdminCall): Promise<void> {
+  const { path, request, response, scope, info } = call
+  const fail = (error: PlugError) => sendError(response, error, encodeError(error))
+  const { keys } = host
+  if (host.options.adminKey === undefined || keys === undefined)
+    return fail({ status: 404, kind: "not_found", code: "not_found", message: `No route for ${request.method} ${path}` })
+
+  const who = authenticateUsage(host.options, request.headers.authorization, await keys.digests())
+  if (isPlugError(who) || !who.admin) return fail({ status: 401, kind: "authentication", code: "invalid_api_key", message: "Missing or invalid admin key" })
+
+  const id = ONE_KEY.exec(path)?.[1]
+  if (path === KEYS && request.method === "GET") {
+    info.route = "GET /v1/admin/keys"
+    return sendJson(response, 200, { keys: await keys.list(host.options.keys) })
+  }
+  if (path === KEYS && request.method === "POST") {
+    info.route = "POST /v1/admin/keys"
+    const unsupported = checkJsonContentType(request)
+    if (unsupported) return fail(unsupported)
+    const body = await readJsonBody(request, scope.signal)
+    const app = typeof body === "object" && body !== null && !Array.isArray(body) ? (body as { app?: unknown }).app : undefined
+    if (typeof app !== "string" || app === DEFAULT_APP || !APP_NAME_PATTERN.test(app))
+      return fail({ status: 400, kind: "invalid_request", code: "invalid_app", param: "app", message: `\`app\` must match ${APP_NAME_PATTERN} and must not be \`${DEFAULT_APP}\`` })
+    if (Object.hasOwn(host.options.keys, app))
+      return fail({ status: 409, kind: "invalid_request", code: "app_has_config_key", param: "app", message: `App ${app} already has a key in the plugboard config; edit \`keys\` to change it` })
+    const created = await keys.create(app, host.options.keys)
+    log("admin.key_created", { id: created.id, app })
+    // The key value is shown once: a cache or a log of this response must not keep it.
+    response.setHeader("cache-control", "no-store")
+    return sendJson(response, 201, created)
+  }
+  if (id !== undefined && request.method === "DELETE") {
+    info.route = "DELETE /v1/admin/keys/{keyId}"
+    const result = await keys.revoke(id, host.options.keys)
+    if (result === "config")
+      return fail({ status: 409, kind: "invalid_request", code: "config_key", message: "This key is set in the plugboard config (`keys`). Remove it there and reload OpenCode." })
+    if (result === "not_found") return fail({ status: 404, kind: "not_found", code: "key_not_found", message: `No runtime key ${id}` })
+    log("admin.key_revoked", { id })
+    return sendJson(response, 200, { id, revoked: true })
+  }
+  if (path === KEYS || id !== undefined)
+    return fail({ status: 405, kind: "invalid_request", code: "method_not_allowed", message: `Method ${request.method} is not allowed for ${path}` })
+  return fail({ status: 404, kind: "not_found", code: "not_found", message: `No route for ${request.method} ${path}` })
+}

package/src/anthropic/request.ts

@@ -9,6 +9,7 @@
  * afterwards, which is why the request omits `ref`.
  */
 import type { PlugboardOptions } from "../config.js"
+import { bodyUserId, userField } from "../user.js"
 import {
   isPlugError,
   type PlugError,
@@ -327,6 +328,7 @@ export function parseMessagesRequest(body: unknown, options: PlugboardOptions):
     return bad(`tool_choice.name: "${toolChoice.name}" is not in tools`)
 
   const request: Omit<PlugRequest, "ref"> = {
+    ...userField(bodyUserId(body)),
     model: body.model,
     system,
     messages,

package/src/anthropic/route.ts

@@ -14,6 +14,7 @@
 import type { IncomingMessage, ServerResponse } from "node:http"
 import { authenticate } from "../config.js"
 import { liveOptions } from "../runtime.js"
+import { bodyUserId, noteEndUser } from "../user.js"
 import { isPlugError, type PlugError, type PlugRequest } from "../contract.js"
 import {
   BodyError,
@@ -32,6 +33,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 { dropRejected } from "../openai/sampling.js"
 import type { RouteHost } from "../openai/route.js"
 import { parseMessagesRequest } from "./request.js"
@@ -54,7 +56,7 @@ export interface MessagesCall {
   readonly response: ServerResponse
   readonly scope: RequestScope
   /** The route's log fields: the route name, the app, the resolved model, dropped parameters, and the outcome of a stream that failed after it committed. */
-  readonly info: ServedInfo & { route: string; app?: string; model?: string; failed?: string; dropped?: string }
+  readonly info: ServedInfo & { route: string; app?: string; model?: string; failed?: string; dropped?: string; user?: string }
 }
 
 const header = (request: IncomingMessage, name: string): string | undefined => {
@@ -63,11 +65,12 @@ const header = (request: IncomingMessage, name: string): string | undefined => {
 }
 
 /** `Authorization: Bearer` first (Claude Code with ANTHROPIC_AUTH_TOKEN), then `x-api-key` (the Anthropic SDKs). One key store. */
-const authenticateRequest = (host: RouteHost, request: IncomingMessage) => {
+const authenticateRequest = async (host: RouteHost, request: IncomingMessage) => {
   const options = liveOptions(host.options)
-  const bearer = authenticate(options, request.headers.authorization)
+  const runtime = host.keys ? await host.keys.digests() : []
+  const bearer = authenticate(options, request.headers.authorization, runtime)
   const apiKey = header(request, "x-api-key")
-  return isPlugError(bearer) && apiKey ? authenticate(options, `Bearer ${apiKey}`) : bearer
+  return isPlugError(bearer) && apiKey ? authenticate(options, `Bearer ${apiKey}`, runtime) : bearer
 }
 
 export async function serveMessages(host: RouteHost, call: MessagesCall): Promise<void> {
@@ -94,7 +97,7 @@ export async function serveMessages(host: RouteHost, call: MessagesCall): Promis
     const rejected = checkOrigin(request, host.options)
     if (rejected) return fail(rejected)
     // Authenticate before the method check, so an unauthenticated caller cannot map this path (#137).
-    const auth = authenticateRequest(host, request)
+    const auth = await authenticateRequest(host, request)
     if (isPlugError(auth)) return fail(auth)
     info.app = auth.app
     if (request.method !== "POST")
@@ -103,6 +106,7 @@ export async function serveMessages(host: RouteHost, call: MessagesCall): Promis
     if (unsupported) return fail(unsupported)
 
     const body = await readJsonBody(request, scope.signal)
+    noteEndUser(response, info, bodyUserId(body))
     // count_tokens takes the message body without max_tokens; the parser needs one, so a placeholder stands in
     // (the count never uses it). A max_tokens the client did send is still validated.
     const sized = path === COUNT_TOKENS && isRecord(body) && body.max_tokens === undefined ? { ...body, max_tokens: Number.MAX_SAFE_INTEGER } : body
@@ -130,9 +134,10 @@ export async function serveMessages(host: RouteHost, call: MessagesCall): Promis
       host.caller.stream(model, {
         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)
         },
         onServed: reportServed(response, info, (served) => void (exchange.model = served.model)),
         onPolicy: reportPolicy(response),

package/src/cache.ts

@@ -25,6 +25,10 @@
  *
  * Fan-out (`n` above 1, prompt arrays) calls the caller once per choice with the same request, so
  * the fan-out sets `noCache`: every choice must be a fresh sample.
+ *
+ * A persona (a skill alias or an `agent/<name>` id, `bypass`) is never cached: its answer depends on
+ * the skill's content or the agent's prompt, which the key does not see, and a skill edit must not be
+ * masked by an old entry.
  */
 
 import { createHash } from "node:crypto"
@@ -115,11 +119,17 @@ function append(events: PlugEvent[], event: { readonly type: "text-delta" | "rea
 }
 
 /** Wraps `inner`: hits are replayed, misses stream through and are stored when they qualify. */
-export function cachedCaller(inner: ModelCaller, config: CacheConfig, store: CacheStore, count?: CacheCounter): ModelCaller {
+export function cachedCaller(
+  inner: ModelCaller,
+  config: CacheConfig,
+  store: CacheStore,
+  count?: CacheCounter,
+  bypass?: (model: string) => boolean,
+): ModelCaller {
   const apps = config.apps ? new Set(config.apps) : undefined
   return {
     async *stream(request: PlugRequest, context: CallContext): AsyncIterable<PlugEvent> {
-      if (context.noCache || (apps && !apps.has(context.app))) return yield* inner.stream(request, context)
+      if (context.noCache || bypass?.(request.model) || (apps && !apps.has(context.app))) return yield* inner.stream(request, context)
       const key = cacheKey(context.app, request)
       const hit = store.get(key)
       if (hit) {

package/src/completions/request.ts

@@ -10,6 +10,7 @@
  */
 import type { PlugboardOptions } from "../config.js"
 import { isPlugError, type PlugError, type PlugRequest } from "../contract.js"
+import { bodyUser, userField } from "../user.js"
 import { parseChoiceCount, parseGeneration } from "../openai/request.js"
 import type { CompletionsExchange } from "./response.js"
 
@@ -85,6 +86,7 @@ export function parseCompletionsRequest(body: unknown, options: PlugboardOptions
   return {
     requests: prompts.map((prompt) => ({
       model: body.model as string,
+      ...userField(bodyUser(body)),
       system: suffix ? [SUFFIX_INSTRUCTION(suffix)] : [],
       messages: [{ role: "user", content: [{ type: "text", text: prompt }] }],
       tools: [],

package/src/config.ts

@@ -3,7 +3,7 @@
 import { createHash, timingSafeEqual } from "node:crypto"
 import type { CacheConfig } from "./cache.js"
 import { isPlugError, type PlugError } from "./contract.js"
-import { allowedBy, parseModelRef } from "./models.js"
+import { allowedBy, parseAliasTarget, parseModelRef, SKILL_PREFIX } from "./models.js"
 import { parseAllowEntry, type RemoteImages } from "./session/media.js"
 import type { HistoryLimits } from "./session/prune.js"
 
@@ -21,6 +21,11 @@ export interface PlugboardOptions {
   readonly models: ReadonlyArray<string>
   /** Alias -> `provider/model[#variant]`. Targets must also pass the allowlist. */
   readonly aliases: Readonly<Record<string, string>>
+  /**
+   * Agent name -> `provider/model[#variant]` (option `agents`): each is listed as `agent/<name>` and runs its
+   * OpenCode agent's system prompt on that model. The model must pass the allowlist.
+   */
+  readonly agents: Readonly<Record<string, string>>
   /**
    * Alias -> the targets after the first, in order, for an alias written as an array. `aliases` holds the
    * first target, so everything that resolves an alias keeps working; the model caller retries the rest
@@ -58,6 +63,8 @@ export interface PlugboardOptions {
   readonly usage: UsageConfig
   /** A key that may read every app's usage on `GET /v1/usage`. Compared like app keys; must differ from every one of them. */
   readonly adminKey?: string
+  /** A template for the OpenCode session page of each request: `{id}`, and optional `{directory}` (see src/session/link.ts, #77). */
+  readonly historyUrl?: string
 }
 
 /** Option `usage` after defaults: on, and days of history kept. */
@@ -139,7 +146,7 @@ const DEFAULTS = {
   requestTimeoutMs: 600_000,
 } as const
 
-const KNOWN = new Set(["listen", "keys", "adminKey", "apps", "models", "aliases", "maxTools", "maxN", "requestTimeoutMs", "remoteImages", "history", "dropUnsupportedParams", "logFormat", "metrics", "modelIds", "limits", "budgets", "cache", "usage"])
+const KNOWN = new Set(["listen", "keys", "adminKey", "apps", "models", "aliases", "agents", "maxTools", "maxN", "requestTimeoutMs", "remoteImages", "history", "dropUnsupportedParams", "logFormat", "metrics", "modelIds", "limits", "budgets", "cache", "usage", "historyUrl"])
 const USAGE_KNOWN = new Set(["enabled", "retentionDays"])
 const USAGE_DEFAULTS = { enabled: true, retentionDays: 90 } as const
 /** Ten years: keeps a day-keyed store bounded and a range query well inside its limits. */
@@ -396,6 +403,55 @@ function parseBudgets(raw: unknown, keys: Readonly<Record<string, string>>): Bud
   return { ...(perApp === undefined ? {} : { perApp }), ...(raw.apps === undefined ? {} : { apps }) }
 }
 
+const AGENT_KNOWN = new Set(["name", "model"])
+/** An OpenCode agent name: letters, digits, `_` and `-`, starting with a letter or digit. */
+const AGENT_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/
+
+/**
+ * Option `agents`: `{ name, model }` per OpenCode agent to expose. `model` is required and must pass the
+ * allowlist, so an agent's own configured model never runs outside `models` (the agent's model setting is
+ * not read). Names must be unique.
+ */
+function parseAgents(raw: unknown, models: ReadonlyArray<string>): Record<string, string> {
+  if (raw === undefined) return {}
+  if (!Array.isArray(raw)) throw new Error("plugboard option `agents` must be an array of { name, model } objects")
+  const entries: Array<[string, string]> = []
+  for (const item of raw) {
+    if (!isRecord(item)) throw new Error("plugboard option `agents` entries must be objects of the form { name, model }")
+    for (const key of Object.keys(item))
+      if (!AGENT_KNOWN.has(key)) throw new Error(`Unknown plugboard option \`agents.${key}\` (known: ${[...AGENT_KNOWN].join(", ")})`)
+    const { name, model } = item
+    if (typeof name !== "string" || !AGENT_NAME.test(name)) throw new Error(`plugboard agent name \`${String(name)}\` must match ${AGENT_NAME} (an OpenCode agent name)`)
+    if (entries.some(([known]) => known === name)) throw new Error(`plugboard agent \`${name}\` is listed more than once in \`agents\``)
+    if (typeof model !== "string" || !ALIAS_TARGET.test(model))
+      throw new Error(`plugboard agent \`${name}\` must set \`model\` to \`provider/model\` or \`provider/model#variant\``)
+    if (!allowedBy(models as string[], parseModelRef(model)!))
+      throw new Error(`plugboard agent \`${name}\` model \`${model}\` is not allowed by the \`models\` option`)
+    entries.push([name, model])
+  }
+  return Object.fromEntries(entries)
+}
+
+/**
+ * Option `historyUrl` (#77): an http(s) URL template that must contain `{id}`. Its only other placeholder is
+ * `{directory}`, so a typo such as `{sesion}` fails at load instead of producing a link that is wrong.
+ */
+function parseHistoryUrl(value: unknown): string | undefined {
+  if (value === undefined) return undefined
+  const at = "plugboard option `historyUrl`"
+  if (typeof value !== "string" || !value.includes("{id}")) throw new Error(`${at} must be a URL template with {id} (for example http://host:4096/session/{id})`)
+  const unknown = (value.match(/\{[^{}]*\}/g) ?? []).find((placeholder) => placeholder !== "{id}" && placeholder !== "{directory}")
+  if (unknown !== undefined) throw new Error(`${at} has the unknown placeholder ${unknown} (known: {id}, {directory})`)
+  let url: URL
+  try {
+    url = new URL(value.replaceAll("{id}", "x").replaceAll("{directory}", "x"))
+  } catch {
+    throw new Error(`${at} must be an http(s) URL template`)
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error(`${at} must be http or https`)
+  return value
+}
+
 /** 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")
@@ -452,6 +508,14 @@ export function parseOptions(raw: unknown): PlugboardOptions {
     const chain = Array.isArray(target) ? target : [target]
     if (chain.length === 0) throw new Error(`plugboard alias \`${alias}\` must list at least one target`)
     for (const entry of chain) {
+      // A skill target binds one model and takes no fallbacks; like a list entry it must pass the allowlist at load.
+      if (typeof entry === "string" && entry.startsWith(SKILL_PREFIX)) {
+        const parsed = parseAliasTarget(entry)
+        if (parsed?.skill === undefined) throw new Error(`plugboard alias \`${alias}\` skill target \`${entry}\` must be \`skill:<id>@provider/model\` or \`skill:<id>@provider/model#variant\``)
+        if (Array.isArray(target)) throw new Error(`plugboard alias \`${alias}\` binds a skill, so it takes one target and no list of fallbacks`)
+        if (!allowedBy(models as string[], parsed.ref)) throw new Error(`plugboard alias \`${alias}\` target \`${entry}\` is not allowed by the \`models\` option`)
+        continue
+      }
       if (typeof entry !== "string" || !ALIAS_TARGET.test(entry))
         throw new Error(`plugboard alias \`${alias}\` must target \`provider/model\` or \`provider/model#variant\` (or a list of them)`)
       // A list is new, so it is strict: a target the allowlist would refuse can never serve, so fail at load.
@@ -465,6 +529,7 @@ export function parseOptions(raw: unknown): PlugboardOptions {
   }
   const aliases: Record<string, string> = Object.fromEntries(aliasEntries)
   const fallbacks: Record<string, string[]> = Object.fromEntries(fallbackEntries)
+  const agents = parseAgents(input.agents, models as string[])
 
   const maxTools = positiveInt(input.maxTools, "maxTools", DEFAULTS.maxTools, 1024)
   const apps = parseApps(input.apps, { keys, aliases, maxTools })
@@ -493,6 +558,7 @@ export function parseOptions(raw: unknown): PlugboardOptions {
   if (budgets !== undefined && !usage.enabled) throw new Error("plugboard option `budgets` needs `usage` enabled: budgets are counted from the usage records")
   if (budgets !== undefined && usage.retentionDays < widestWindowDays(budgets))
     throw new Error(`plugboard option \`usage.retentionDays\` must be at least ${widestWindowDays(budgets)} for the budget windows in use (a month is 31 days, a week 7): older days are deleted and would stop counting`)
+  const historyUrl = parseHistoryUrl(input.historyUrl)
 
   return {
     listen: { host, port: port ?? DEFAULTS.port },
@@ -500,6 +566,7 @@ export function parseOptions(raw: unknown): PlugboardOptions {
     apps,
     models: models as string[],
     aliases,
+    agents,
     fallbacks,
     maxTools,
     maxN: positiveInt(input.maxN, "maxN", DEFAULTS.maxN, 64),
@@ -515,6 +582,7 @@ export function parseOptions(raw: unknown): PlugboardOptions {
     usage,
     ...(budgets === undefined ? {} : { budgets }),
     ...(typeof input.adminKey === "string" ? { adminKey: input.adminKey } : {}),
+    ...(historyUrl === undefined ? {} : { historyUrl }),
   }
 }
 
@@ -543,24 +611,32 @@ function digestsOf(keys: Readonly<Record<string, string>>): ReadonlyArray<readon
 /** Who may read `GET /v1/usage`: the admin key (every app), or one app (`default` when keyless). */
 export type UsageScope = { readonly admin: true } | { readonly admin: false; readonly app: string }
 
+/** The digest of a runtime key (src/keys.ts), with its app: checked like a config key (#55). */
+export type RuntimeDigest = readonly [app: string, digest: Buffer]
+
 /** The admin key is checked first; any other valid key (or keyless mode) is an app, as `authenticate` decides. */
-export function authenticateUsage(options: PlugboardOptions, authorization: string | undefined): UsageScope | PlugError {
+export function authenticateUsage(options: PlugboardOptions, authorization: string | undefined, runtime: ReadonlyArray<RuntimeDigest> = []): UsageScope | PlugError {
   const bearer = /^Bearer\s+(\S+)\s*$/i.exec(authorization ?? "")?.[1]
   if (options.adminKey !== undefined && bearer !== undefined && timingSafeEqual(sha256(bearer), sha256(options.adminKey))) return { admin: true }
-  const auth = authenticate(options, authorization)
+  const auth = authenticate(options, authorization, runtime)
   if (isPlugError(auth)) return auth
   return { admin: false, app: auth.app }
 }
 
-/** No keys -> app `default`; with keys every request needs `Authorization: Bearer <key>`. */
-export function authenticate(options: PlugboardOptions, authorization: string | undefined): { app: string } | PlugError {
+/**
+ * No config keys -> app `default` (keyless), as before. With config keys every request needs
+ * `Authorization: Bearer <key>`. A runtime key (#55) matches like a config key, so it names its app
+ * whenever it is presented. It never makes a keyless server require a key, so deleting the last
+ * runtime key cannot open or close access by itself.
+ */
+export function authenticate(options: PlugboardOptions, authorization: string | undefined, runtime: ReadonlyArray<RuntimeDigest> = []): { app: string } | PlugError {
   const entries = digestsOf(options.keys)
-  if (entries.length === 0) return { app: DEFAULT_APP }
   const token = /^Bearer\s+(\S+)\s*$/i.exec(authorization ?? "")?.[1]
-  if (!token) return UNAUTHORIZED
+  if (token === undefined) return entries.length === 0 ? { app: DEFAULT_APP } : UNAUTHORIZED
   const digest = sha256(token)
   let app: string | undefined
   // Every key is compared, no early exit.
-  for (const [name, expected] of entries) if (timingSafeEqual(digest, expected)) app = name
-  return app === undefined ? UNAUTHORIZED : { app }
+  for (const [name, expected] of [...entries, ...runtime]) if (timingSafeEqual(digest, expected)) app = name
+  if (app !== undefined) return { app }
+  return entries.length === 0 ? { app: DEFAULT_APP } : UNAUTHORIZED
 }

package/src/contract.ts

@@ -114,6 +114,8 @@ export interface PlugRequest {
   readonly tools: ReadonlyArray<PlugTool>
   readonly toolChoice?: PlugToolChoice
   readonly generation: PlugGeneration
+  /** The end user the caller named, when kept (src/user.ts, #57). Labels the session title and the usage counts. */
+  readonly user?: string
 }
 
 // ---------------------------------------------------------------- events
@@ -172,7 +174,7 @@ export interface CallContext {
   /** Aborted on client disconnect or timeout. */
   readonly signal: AbortSignal
   /** Called once, before the first event, with the id of the history record this call writes (if any). */
-  readonly onRecord?: (recordID: string) => void
+  readonly onRecord?: (recordID: string, directory?: string) => void
   /**
    * Called once, before the first event, only for a request whose model is an alias with fallbacks
    * (`src/fallback.ts`): which target answered and how many earlier targets failed first. A front-end

package/src/discovery.ts

@@ -92,6 +92,14 @@ function endpoints(options: PlugboardOptions): ReadonlyArray<Endpoint> {
         ]
       : []),
     ...(options.metrics ? [{ method: "GET", path: "/metrics", auth: true, description: "Prometheus metrics." }] : []),
+    // The admin key only (option `adminKey`); without it these paths are a 404 (src/admin/route.ts).
+    ...(options.adminKey === undefined
+      ? []
+      : [
+          { method: "GET", path: "/v1/admin/keys", auth: true, description: "Admin: the config and runtime app keys, without key values." },
+          { method: "POST", path: "/v1/admin/keys", auth: true, description: "Admin: a new app key for `{ app }`, returned once." },
+          { method: "DELETE", path: "/v1/admin/keys/{keyId}", auth: true, description: "Admin: revoke a runtime app key." },
+        ]),
   ]
 }
 

package/src/fallback.ts

@@ -51,6 +51,8 @@ export const FALLBACKS_HEADER = "x-plugboard-fallbacks"
 export interface ServedInfo {
   served?: string
   fallbacks?: number
+  /** The session page link of the request (option `historyUrl`, src/session/link.ts), for the log line. */
+  sessionUrl?: string
 }
 
 /**
@@ -90,9 +92,9 @@ async function* chain(inner: ModelCaller, deps: FallbackDeps, request: PlugReque
   let attempt = 0
   for (;;) {
     // The history id of this attempt: handed on only if the attempt is the one that answers (or the last).
-    let recordID: string | undefined
+    let recorded: { id: string; directory?: string } | undefined
     const next = attempt === 0 ? request : retarget(deps.options, request, ref)
-    const iterator = inner.stream(next, { ...context, onRecord: (id) => void (recordID = id) })[Symbol.asyncIterator]()
+    const iterator = inner.stream(next, { ...context, onRecord: (id, directory) => void (recorded = { id, directory }) })[Symbol.asyncIterator]()
 
     let first: IteratorResult<PlugEvent> | undefined
     let thrown: { readonly error: unknown } | undefined
@@ -124,7 +126,7 @@ async function* chain(inner: ModelCaller, deps: FallbackDeps, request: PlugReque
     }
 
     // Answered, ran out of targets, or the request ended: this attempt's outcome is the response.
-    if (recordID !== undefined) report(context, recordID)
+    if (recorded !== undefined) report(context, recorded)
     if (thrown) throw thrown.error
     if (first!.done) return
     // An error is not an answer: a call that fails (non-retryable, or on its last target) reports no served model.
@@ -153,9 +155,9 @@ async function resolveRest(deps: FallbackDeps, request: PlugRequest, app: string
   }
 }
 
-const report = (context: CallContext, recordID: string): void => {
+const report = (context: CallContext, recorded: { readonly id: string; readonly directory?: string }): void => {
   try {
-    context.onRecord?.(recordID)
+    context.onRecord?.(recorded.id, recorded.directory)
   } catch {}
 }
 

package/src/gemini/route.ts

@@ -22,6 +22,7 @@ import { listAvailableModels, 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 type { RouteHost } from "../openai/route.js"
 import { dropRejected } from "../openai/sampling.js"
 import { estimateTokens } from "../anthropic/tokens.js"
@@ -157,9 +158,10 @@ export async function serveGemini(host: RouteHost, { match, request, url, app, r
     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),