opencode-plugboard 0.18.0 → 0.20.0

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
@@ -50,12 +55,16 @@ export interface PlugboardOptions {
   readonly modelIds: ModelIds
   /** Concurrency caps and requests per minute per app (see `src/limits.ts`). Absent: unlimited. */
   readonly limits?: Limits
+  /** Per-app budgets (see `src/budgets.ts`): ceilings on requests, tokens and cost per UTC day, week or month. Needs `usage`. Absent: no budgets. */
+  readonly budgets?: Budgets
   /** Opt-in exact-match response cache (see `src/cache.ts`). Absent: off. */
   readonly cache?: CacheConfig
   /** Per-app usage statistics (see `src/usage.ts`): recorded and served by `GET /v1/usage` and the RPC. */
   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. */
@@ -99,6 +108,34 @@ export interface Limits {
   readonly apps?: Readonly<Record<string, LimitCaps>>
 }
 
+/** What a budget counts: HTTP requests on the model routes (refusals by `limits` or budgets left out), tokens, or cost in USD. */
+export type BudgetMetric = "requests" | "tokens" | "costUsd"
+/** The windows a budget resets on: a UTC calendar day, an ISO week (Monday start) or a calendar month (UTC). */
+export type BudgetWindow = "day" | "week" | "month"
+
+/** Ceilings per window. A window that is not set has no ceiling. */
+export interface BudgetWindows {
+  readonly day?: number
+  readonly week?: number
+  readonly month?: number
+}
+
+/** One set of ceilings. A metric that is not set is unlimited. `costUsd` is an estimate at list prices. */
+export interface Budget {
+  readonly requests?: BudgetWindows
+  readonly tokens?: BudgetWindows
+  readonly costUsd?: BudgetWindows
+}
+
+/**
+ * Option `budgets`. `perApp` applies to every app; `apps.<name>` replaces `perApp` metric by metric for
+ * that app (its `requests` replaces `perApp.requests`, the other metrics still come from `perApp`).
+ */
+export interface Budgets {
+  readonly perApp?: Budget
+  readonly apps?: Readonly<Record<string, Budget>>
+}
+
 export const APP_NAME_PATTERN = /^[a-z0-9-]+$/
 export const DEFAULT_APP = "default"
 const DEFAULTS = {
@@ -109,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", "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. */
@@ -304,6 +341,117 @@ function parseCache(value: unknown, keys: Readonly<Record<string, string>>): Cac
   return { ttlSeconds, maxEntries, maxBytes, apps: [...new Set(value.apps as string[])] }
 }
 
+const BUDGET_METRICS: ReadonlyArray<BudgetMetric> = ["requests", "tokens", "costUsd"]
+const BUDGET_WINDOWS: ReadonlyArray<BudgetWindow> = ["day", "week", "month"]
+/** The most days a window can span: a month is up to 31. Retention must keep at least that many, or a budget would count from pruned records. */
+const WINDOW_DAYS: Readonly<Record<BudgetWindow, number>> = { day: 1, week: 7, month: 31 }
+
+/** The longest window any ceiling of `budgets` uses, in days (0 without budgets). */
+function widestWindowDays(budgets: Budgets | undefined): number {
+  let most = 0
+  for (const budget of [budgets?.perApp, ...Object.values(budgets?.apps ?? {})])
+    for (const metric of [budget?.requests, budget?.tokens, budget?.costUsd])
+      for (const window of Object.keys(metric ?? {}) as BudgetWindow[]) most = Math.max(most, WINDOW_DAYS[window])
+  return most
+}
+
+/**
+ * Validates `budgets`: `{ perApp?, apps? }`, each a budget of `requests`, `tokens` and `costUsd`, each of
+ * those a map of window (`day`, `week`, `month`) to a positive limit. Counts are integers, costs any positive
+ * number of USD. An `apps` entry must name a configured app, as in `limits`.
+ */
+function parseBudgets(raw: unknown, keys: Readonly<Record<string, string>>): Budgets | undefined {
+  if (raw === undefined) return undefined
+  if (!isRecord(raw)) throw new Error("plugboard option `budgets` must be an object")
+  for (const key of Object.keys(raw))
+    if (key !== "perApp" && key !== "apps") throw new Error(`Unknown plugboard option \`budgets.${key}\` (known: perApp, apps)`)
+
+  const budget = (value: unknown, at: string): Budget => {
+    if (!isRecord(value)) throw new Error(`plugboard option \`${at}\` must be an object`)
+    for (const key of Object.keys(value))
+      if (!BUDGET_METRICS.includes(key as BudgetMetric)) throw new Error(`Unknown plugboard option \`${at}.${key}\` (known: ${BUDGET_METRICS.join(", ")})`)
+    const parsed: Record<string, Record<string, number>> = {}
+    for (const metric of BUDGET_METRICS) {
+      const windows = value[metric]
+      if (windows === undefined) continue
+      const field = `${at}.${metric}`
+      if (!isRecord(windows)) throw new Error(`plugboard option \`${field}\` must be an object of window (${BUDGET_WINDOWS.join(", ")}) to limit`)
+      const limits: Record<string, number> = {}
+      for (const window of Object.keys(windows)) {
+        if (!BUDGET_WINDOWS.includes(window as BudgetWindow)) throw new Error(`Unknown plugboard option \`${field}.${window}\` (known: ${BUDGET_WINDOWS.join(", ")})`)
+        const limit = windows[window]
+        if (limit === undefined) continue
+        if (metric === "costUsd") {
+          if (typeof limit !== "number" || !Number.isFinite(limit) || limit <= 0) throw new Error(`plugboard option \`${field}.${window}\` must be a positive number of USD`)
+          limits[window] = limit
+        } else limits[window] = positiveInt(limit, `${field}.${window}`, 0, Number.MAX_SAFE_INTEGER)
+      }
+      parsed[metric] = limits
+    }
+    return parsed as Budget
+  }
+
+  const perApp = raw.perApp === undefined ? undefined : budget(raw.perApp, "budgets.perApp")
+  if (raw.apps !== undefined && !isRecord(raw.apps)) throw new Error("plugboard option `budgets.apps` must be an object of app name -> budget")
+  const apps: Record<string, Budget> = {}
+  for (const [app, value] of Object.entries(isRecord(raw.apps) ? raw.apps : {})) {
+    const at = `budgets.apps.${app}`
+    const configured = app === DEFAULT_APP ? Object.keys(keys).length === 0 : Object.hasOwn(keys, app)
+    if (!configured) throw new Error(`plugboard option \`${at}\` must name a configured app (a key in \`keys\`; \`${DEFAULT_APP}\` only without keys)`)
+    apps[app] = budget(value, at)
+  }
+  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")
@@ -360,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.
@@ -373,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 })
@@ -397,6 +554,11 @@ export function parseOptions(raw: unknown): PlugboardOptions {
   const limits = parseLimits(input.limits, keys)
   const cache = parseCache(input.cache, keys)
   const usage = parseUsage(input.usage)
+  const budgets = parseBudgets(input.budgets, keys)
+  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 },
@@ -404,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),
@@ -417,7 +580,9 @@ export function parseOptions(raw: unknown): PlugboardOptions {
     ...(limits === undefined ? {} : { limits }),
     ...(cache ? { cache } : {}),
     usage,
+    ...(budgets === undefined ? {} : { budgets }),
     ...(typeof input.adminKey === "string" ? { adminKey: input.adminKey } : {}),
+    ...(historyUrl === undefined ? {} : { historyUrl }),
   }
 }
 
@@ -446,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
@@ -186,6 +188,20 @@ export interface CallContext {
   readonly onCache?: (result: "hit" | "miss") => void
   /** Bypass the response cache for this call. Fan-out sets it: each choice of `n` above 1 repeats one request and must be a fresh sample. */
   readonly noCache?: boolean
+  /**
+   * Called once per answered call, before its finish event, when usage recording is on (`withUsage`,
+   * src/usage.ts): the call's tokens and USD cost. Front-ends set `x-plugboard-usage` from it while the
+   * headers are open, so a stream (headers sent first) never gets it.
+   */
+  readonly onUsage?: (totals: CallTotals) => void
+}
+
+/** One answered call's totals for the caller: `inputTokens` and `outputTokens` as the response body reports them (cache reads inside input, reasoning inside output), and `costUsd` when the model has a price. */
+export interface CallTotals {
+  readonly inputTokens: number
+  readonly outputTokens: number
+  readonly cacheReadTokens: number
+  readonly costUsd?: number
 }
 
 /** The target of an alias that answered: `provider/model[#variant]`, and the targets tried before it. */

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/request.ts

@@ -439,6 +439,7 @@ export function parseGeminiRequest(model: string, stream: boolean, body: unknown
       stream,
       ...(respond ? { structuredTool: RESPOND_TOOL, ...(format.wrap ? { wrapped: true } : {}), ...(withCallerTools ? { callerTools: true } : {}) } : {}),
       ...(format.instruction ? { jsonObject: true } : {}),
+      ...(generation.stop ? { stop: generation.stop } : {}),
     },
     ...(reasoningEffort ? { reasoningEffort } : {}),
   }

package/src/gemini/response.ts

@@ -9,6 +9,7 @@
 import type { PlugError, PlugErrorKind, PlugEvent, PlugFinish, PlugUsage } from "../contract.js"
 import type { ListedModel } from "../models.js"
 import { unfence } from "../openai/response.js"
+import { StopHoldback } from "../stop.js"
 import { WRAP_KEY } from "./request.js"
 
 type ToolCall = Extract<PlugEvent, { type: "tool-call" }>
@@ -30,6 +31,8 @@ export interface GeminiExchange {
   readonly callerTools?: boolean
   /** `responseMimeType: application/json` without a schema: a single code fence around JSON text is stripped. */
   readonly jsonObject?: boolean
+  /** The request's `generationConfig.stopSequences`. A plain stop whose text ends with one of these leaves the sequence out (src/stop.ts). Not applied to structured output. */
+  readonly stop?: ReadonlyArray<string>
 }
 
 /** How an exchange ended. Nothing was emitted when `failure` is set and `started` is false: the caller answers with a real HTTP error. */
@@ -160,10 +163,18 @@ export async function runGenerate(events: AsyncIterable<PlugEvent>, exchange: Ge
     else parts.push(part)
     emit(envelope([part]))
   }
+  // A stop sequence is held back until the finish decides it (src/stop.ts). Structured output has none.
+  const holdback = exchange.structuredTool === undefined ? new StopHoldback(exchange.stop ?? []) : undefined
   const text = (delta: string) => {
-    if (delta.length > 0) push({ text: delta })
+    const out = holdback ? holdback.push(delta) : delta
+    if (out.length > 0) push({ text: out })
+  }
+  const releaseHeld = () => {
+    const rest = holdback?.release() ?? ""
+    if (rest.length > 0) push({ text: rest })
   }
   const toolCall = (call: ToolCall) => {
+    releaseHeld()
     push({ functionCall: { name: call.name, args: argsOf(call.input) } })
     calls++
   }
@@ -221,6 +232,10 @@ export async function runGenerate(events: AsyncIterable<PlugEvent>, exchange: Ge
   failure ??= finish ? (passthrough ? undefined : structuredFailure(exchange, finish, answered)) : noFinish()
   if (failure) return { failure, started }
   flush()
+  if (holdback) {
+    const rest = holdback.finish(finish === "stop" && calls === 0).text
+    if (rest.length > 0) push({ text: rest })
+  }
   if (held && !passthrough) text(structuredText(exchange, held))
   const candidate = { finishReason: FINISH_REASONS[finish!] }
   const extra = usage ? { usageMetadata: encodeUsage(usage) } : {}

package/src/gemini/route.ts

@@ -21,6 +21,8 @@ import { boundEvents, checkJsonContentType, readJsonBody, sendError, sendJson, s
 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"
@@ -156,12 +158,14 @@ 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),
+      onUsage: reportUsage(response, match.stream),
       onCache: reportCache(response),
     }),
     scope,

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/log.ts

@@ -142,5 +142,8 @@ export const log = (event: string, fields?: LogFields): void => state().logger.i
 
 export const logError = (event: string, fields?: LogFields): void => state().logger.error(record(event, fields))
 
+/** A line for something that needs attention but did not fail a request (a budget at 80%). Info-level destination, `warn` in the level field. */
+export const logWarn = (event: string, fields?: LogFields): void => state().logger.warn(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))