opencode-plugboard 0.18.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.18.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.18.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,14 +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, 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"
 
@@ -58,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),
@@ -80,23 +84,35 @@ export default Plugin.define({
         // Aliases written as a list retry the next target before the first output (src/fallback.ts).
         // The response cache sits outside the fallbacks, so a hit never reaches a provider (src/cache.ts).
         caller: withUsage(
-          withLimits(
-            withResponseCache(
-              withFallbacks(createSessionCaller(callerDeps), {
+          // Budgets sit outside the limiter, so a budget refusal never takes a slot (src/budgets.ts).
+          withBudgets(
+            withLimits(
+              withResponseCache(
+                withFallbacks(createSessionCaller(callerDeps), {
+                  options,
+                  loadCatalog: servingCatalog,
+                  onFallback: (app) => {
+                    if (options.metrics) processMetrics().fallback(app)
+                    usage?.fallback(app)
+                  },
+                }),
                 options,
-                loadCatalog: servingCatalog,
-                onFallback: (app) => {
-                  if (options.metrics) processMetrics().fallback(app)
-                  usage?.fallback(app)
+              ),
+              () => limits,
+              processLimits(),
+              {
+                onLimited: (app, reason) => {
+                  if (options.metrics) processMetrics().limited(app, reason)
+                  usage?.limited(app)
                 },
-              }),
-              options,
+              },
             ),
-            () => limits,
-            processLimits(),
+            options.budgets,
+            usage,
+            processBudgets(),
             {
-              onLimited: (app, reason) => {
-                if (options.metrics) processMetrics().limited(app, reason)
+              onRefused: (app) => {
+                if (options.metrics) processMetrics().limited(app, "budget")
                 usage?.limited(app)
               },
             },
@@ -105,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.18.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/response.ts

@@ -7,6 +7,7 @@
  * no-op `emit`. Thinking blocks are produced only when the request asked for thinking.
  */
 import type { PlugError, PlugEvent, PlugFinish, PlugUsage } from "../contract.js"
+import { StopHoldback } from "../stop.js"
 
 type ToolCall = Extract<PlugEvent, { type: "tool-call" }>
 
@@ -76,10 +77,6 @@ const STOP_REASON: Record<Exclude<PlugFinish, "error">, string> = {
   "content-filter": "refusal",
 }
 
-/** The longest stop sequence the text ends with, if any. */
-const stopTail = (tail: string, stops: ReadonlyArray<string>): string | undefined =>
-  stops.filter((stop) => tail.endsWith(stop)).sort((a, b) => b.length - a.length)[0]
-
 const noFinish = (): PlugError => ({ status: 500, kind: "server", message: "Model stream ended without a finish event" })
 const failedRun = (): PlugError => ({ status: 500, kind: "server", message: "Model run failed" })
 
@@ -127,10 +124,9 @@ export async function runMessage(
   let finish: Exclude<PlugFinish, "error"> | undefined
   let usage: PlugUsage | undefined
   let failure: PlugError | undefined
-  // Text is held back by the longest stop sequence (`holdback` characters), so a sequence at the end of
-  // the answer can be found and removed before it is sent. Without stop sequences nothing is held.
-  const holdback = Math.max(0, ...(exchange.stop ?? []).map((stop) => stop.length))
-  let held = ""
+  // Text is held back by the longest stop sequence, so a sequence at the end of the answer can be
+  // found and removed before it is sent (src/stop.ts). Without stop sequences nothing is held.
+  const holdback = new StopHoldback(exchange.stop ?? [])
 
   const message = (extra: Record<string, unknown>) => ({
     id,
@@ -162,20 +158,8 @@ export async function runMessage(
     content.push(open.kind === "text" ? { type: "text", text: open.text } : { type: "thinking", thinking: open.text, signature: "" })
     open = undefined
   }
-  const releaseHeld = () => {
-    const out = held
-    held = ""
-    delta("text", out)
-  }
-  const text = (chunk: string) => {
-    if (holdback === 0) return delta("text", chunk)
-    held += chunk
-    if (held.length > holdback) {
-      const out = held.slice(0, held.length - holdback)
-      held = held.slice(out.length)
-      delta("text", out)
-    }
-  }
+  const releaseHeld = () => delta("text", holdback.release())
+  const text = (chunk: string) => delta("text", holdback.push(chunk))
   const delta = (kind: "text" | "thinking", text: string) => {
     if (text.length === 0) return
     start()
@@ -240,9 +224,8 @@ export async function runMessage(
     return { failure, started }
   }
   // A plain stop with no tool calls that ends on a stop sequence: the sequence is not part of the answer.
-  const matched = holdback > 0 && finish === "stop" && calls === 0 ? stopTail(held, exchange.stop ?? []) : undefined
-  if (matched !== undefined) held = held.slice(0, held.length - matched.length)
-  releaseHeld()
+  const { text: rest, matched } = holdback.finish(finish === "stop" && calls === 0)
+  delta("text", rest)
   start()
   close()
   ping()

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,
@@ -31,6 +32,8 @@ import { reportServed, type ServedInfo } from "../fallback.js"
 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"
@@ -53,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 => {
@@ -62,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> {
@@ -93,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")
@@ -102,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
@@ -129,12 +134,14 @@ 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),
+        onUsage: reportUsage(response, exchange.stream),
         onCache: reportCache(response),
       }),
       scope,

package/src/budgets.ts

@@ -0,0 +1,200 @@
+/**
+ * Per-app budgets (option `budgets`): a `ModelCaller` wrapper that refuses a call with 429
+ * `budget_exceeded` once its app has used a ceiling for the current window.
+ *
+ * Windows are UTC: a calendar day, an ISO week (Monday start) and a calendar month. The check reads
+ * what the usage records already hold for the window (`UsageRecorder.spent`, src/usage.ts): requests
+ * on the model routes that were not refused by a limit or a budget, the tokens of answered calls and
+ * their cost at list prices. A call that crosses a ceiling is still served; the next one is refused.
+ * Calls in flight are not counted until they end, so a burst can pass a ceiling by the calls it
+ * admitted. A call that finds the records unreadable is refused with 503 `budget_unavailable` rather
+ * than let through.
+ *
+ * The check runs before anything else is taken: a refused call holds no concurrency slot and spends
+ * no requests-per-minute count. `index.ts` puts this wrapper outside `withLimits` for that reason.
+ * Crossing 80% of a ceiling logs `budget.warning` once per app, budget and window (and again in the
+ * next window). The warning state lives on the process runtime, so a plugin generation keeps it.
+ */
+
+import type { Budget, BudgetMetric, BudgetWindow, Budgets } from "./config.js"
+import type { CallContext, ModelCaller, PlugError, PlugEvent, PlugRequest } from "./contract.js"
+import { errorMessage, log, logError, logWarn } from "./log.js"
+import { totalTokens, utcDate, type BudgetStatus, type DayRecord, type UsageRecorder } from "./usage.js"
+
+/** What the warnings already logged: `app|metric|window` -> the window's first day. The process-wide state (src/runtime.ts). */
+export interface BudgetState {
+  readonly warned: Map<string, string>
+}
+
+export const createBudgetState = (): BudgetState => ({ warned: new Map() })
+
+export interface BudgetOptions {
+  /** Clock in epoch ms. Tests inject one; the default is `Date.now`. */
+  readonly now?: () => number
+  /** Called once for each refused call (metrics, usage). */
+  readonly onRefused?: (app: string) => void
+}
+
+const DAY_MS = 86_400_000
+const WARN_AT = 0.8
+const METRICS: ReadonlyArray<BudgetMetric> = ["requests", "tokens", "costUsd"]
+const WINDOWS: ReadonlyArray<BudgetWindow> = ["day", "week", "month"]
+const LABEL: Record<BudgetMetric, string> = { requests: "requests", tokens: "tokens", costUsd: "cost (USD)" }
+
+/** The window that holds `at`: its first UTC day (`start`) and the instant the next one begins (`resetsAt`, epoch ms). */
+export function windowAt(window: BudgetWindow, at: number): { readonly start: string; readonly resetsAt: number } {
+  const now = new Date(at)
+  const year = now.getUTCFullYear()
+  const month = now.getUTCMonth()
+  const today = Date.UTC(year, month, now.getUTCDate())
+  if (window === "day") return { start: utcDate(today), resetsAt: today + DAY_MS }
+  if (window === "week") {
+    // getUTCDay counts from Sunday; Monday is 0 here.
+    const monday = today - ((now.getUTCDay() + 6) % 7) * DAY_MS
+    return { start: utcDate(monday), resetsAt: monday + 7 * DAY_MS }
+  }
+  return { start: utcDate(Date.UTC(year, month, 1)), resetsAt: Date.UTC(year, month + 1, 1) }
+}
+
+/** The budget that applies to `app`: `perApp`, with the app's `apps` entry replacing each metric it sets. Undefined when neither sets a metric. */
+export function budgetFor(budgets: Budgets, app: string): Budget | undefined {
+  const own = budgets.apps && Object.hasOwn(budgets.apps, app) ? budgets.apps[app] : undefined
+  const merged: Budget = { ...budgets.perApp, ...own }
+  return METRICS.some((metric) => merged[metric] !== undefined) ? merged : undefined
+}
+
+interface Ceiling {
+  readonly metric: BudgetMetric
+  readonly window: BudgetWindow
+  readonly limit: number
+}
+
+/** Every ceiling the budget sets, in a fixed order: metric, then window. */
+function ceilingsOf(budget: Budget): Ceiling[] {
+  const out: Ceiling[] = []
+  for (const metric of METRICS)
+    for (const window of WINDOWS) {
+      const limit = budget[metric]?.[window]
+      if (limit !== undefined) out.push({ metric, window, limit })
+    }
+  return out
+}
+
+/** What a window's records count against a ceiling. Requests leave out refusals, which `limited` counts. */
+function usedOf(day: DayRecord, metric: BudgetMetric): number {
+  if (metric === "requests") return day.requests - day.limited
+  if (metric === "tokens") return totalTokens(day.tokens)
+  return day.costUsd
+}
+
+interface Spent {
+  readonly day: DayRecord
+  readonly resetsAt: number
+  /** First UTC day of the window. */
+  readonly start: string
+}
+
+/** The records of the window holding `at`, from its first day to today. Memoized per call, so each window is read once. */
+function spentFor(usage: UsageRecorder, app: string, at: number): (window: BudgetWindow) => Promise<Spent> {
+  const seen = new Map<BudgetWindow, Promise<Spent>>()
+  return (window) => {
+    let found = seen.get(window)
+    if (!found) {
+      const { start, resetsAt } = windowAt(window, at)
+      seen.set(window, (found = usage.spent(app, start, utcDate(at)).then((day) => ({ day, resetsAt, start }))))
+    }
+    return found
+  }
+}
+
+/** The state of every ceiling of `budget` for `app` now: what the current window has used, and when it resets. */
+export async function budgetStatus(usage: UsageRecorder, budget: Budget, app: string, at: number): Promise<BudgetStatus[]> {
+  const spent = spentFor(usage, app, at)
+  const rows: BudgetStatus[] = []
+  for (const { metric, window, limit } of ceilingsOf(budget)) {
+    const current = await spent(window)
+    rows.push({ metric, window, limit, used: usedOf(current.day, metric), resetsAt: new Date(current.resetsAt).toISOString() })
+  }
+  return rows
+}
+
+/** The refusal for a call now, or undefined. Logs the warnings the ceilings cross (once each per window). */
+async function check(budget: Budget, app: string, usage: UsageRecorder, state: BudgetState, at: number): Promise<PlugError | undefined> {
+  const spent = spentFor(usage, app, at)
+  const exceeded: string[] = []
+  let resetsAt = 0
+  for (const { metric, window, limit } of ceilingsOf(budget)) {
+    const current = await spent(window)
+    const used = usedOf(current.day, metric)
+    if (used >= limit * WARN_AT) warnOnce(state, app, metric, window, current.start, { used, limit, resetsAt: current.resetsAt })
+    if (used >= limit) {
+      exceeded.push(`${LABEL[metric]} ${window}`)
+      resetsAt = Math.max(resetsAt, current.resetsAt)
+    }
+  }
+  if (exceeded.length === 0) return undefined
+  const retryAfterSeconds = Math.max(1, Math.ceil((resetsAt - at) / 1000))
+  log("request.budget_exceeded", { app, budgets: exceeded.join(", "), retryAfterSeconds })
+  return { status: 429, kind: "rate_limit", code: "budget_exceeded", message: `Budget for ${app} exceeded: ${exceeded.join(", ")}`, retryAfterSeconds }
+}
+
+function warnOnce(
+  state: BudgetState,
+  app: string,
+  metric: BudgetMetric,
+  window: BudgetWindow,
+  start: string,
+  figures: { readonly used: number; readonly limit: number; readonly resetsAt: number },
+): void {
+  const key = `${app}|${metric}|${window}`
+  if (state.warned.get(key) === start) return
+  state.warned.set(key, start)
+  logWarn("budget.warning", { app, budget: metric, window, used: figures.used, limit: figures.limit, resetsAt: new Date(figures.resetsAt).toISOString() })
+}
+
+/**
+ * The budget caller: each call of an app with a budget is checked first. With no budget for the app,
+ * no usage recorder, or no budgets at all, the caller is returned as it is. `budgets` is the parsed option.
+ */
+export function withBudgets(
+  inner: ModelCaller,
+  budgets: Budgets | undefined,
+  usage: UsageRecorder | undefined,
+  state: BudgetState,
+  options: BudgetOptions = {},
+): ModelCaller {
+  const now = options.now ?? Date.now
+  return {
+    stream(request, context) {
+      const budget = budgets === undefined ? undefined : budgetFor(budgets, context.app)
+      if (!usage || !budget) return inner.stream(request, context)
+      return admit(inner, budget, usage, state, now, options.onRefused, request, context)
+    },
+  }
+}
+
+async function* admit(
+  inner: ModelCaller,
+  budget: Budget,
+  usage: UsageRecorder,
+  state: BudgetState,
+  now: () => number,
+  onRefused: BudgetOptions["onRefused"],
+  request: PlugRequest,
+  context: CallContext,
+): AsyncGenerator<PlugEvent> {
+  const app = context.app
+  let refusal: PlugError | undefined
+  try {
+    refusal = await check(budget, app, usage, state, now())
+  } catch (error) {
+    logError("budget.check_failed", { app, error: errorMessage(error) })
+    refusal = { status: 503, kind: "server", code: "budget_unavailable", message: "Could not read the usage records for the budget check" }
+  }
+  if (refusal) {
+    if (refusal.status === 429) onRefused?.(app)
+    yield { type: "error", error: refusal }
+    return
+  }
+  for await (const event of inner.stream(request, context)) yield event
+}

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: [],
@@ -97,6 +99,7 @@ export function parseCompletionsRequest(body: unknown, options: PlugboardOptions
       includeUsage: streamOptions.include_usage === true,
       perPrompt: n,
       ...(body.echo === true ? { echo: prompts } : {}),
+      ...(generation.stop ? { stop: generation.stop } : {}),
     },
     ...(typeof body.reasoning_effort === "string" ? { reasoningEffort: body.reasoning_effort } : {}),
   }

package/src/completions/response.ts

@@ -8,6 +8,7 @@
 import type { PlugError, PlugEvent, PlugFinish, PlugUsage } from "../contract.js"
 import type { ChoiceCodec } from "../openai/fanout.js"
 import { encodeError, type StreamChoice, type StreamResult } from "../openai/response.js"
+import { StopHoldback, stripStopTail } from "../stop.js"
 
 /** What the encoders need besides the model events; the request decoder produces it, the model call never sees it. */
 export interface CompletionsExchange {
@@ -20,6 +21,8 @@ export interface CompletionsExchange {
   readonly perPrompt: number
   /** `echo`: each prompt, written ahead of the text of its choices. */
   readonly echo?: ReadonlyArray<string>
+  /** The request's `stop`. A plain stop whose text ends with one of these leaves the sequence out (src/stop.ts). */
+  readonly stop?: ReadonlyArray<string>
 }
 
 const FINISH_REASONS: Record<Exclude<PlugFinish, "error">, string> = {
@@ -65,6 +68,7 @@ async function collectText(events: AsyncIterable<PlugEvent>, exchange: Completio
     const error = failure ?? noFinish()
     return { status: error.status, body: encodeError(error), retryAfterSeconds: error.retryAfterSeconds }
   }
+  if (finish === "stop") text = stripStopTail(text, exchange.stop ?? []).text
   return {
     status: 200,
     body: {
@@ -106,6 +110,8 @@ async function streamText(
     const prefix = prefixOf(exchange, choice.index)
     if (prefix.length > 0) chunk(prefix)
   }
+  // A stop sequence is held back until the finish decides it (src/stop.ts).
+  const holdback = new StopHoldback(exchange.stop ?? [])
   let finish: Exclude<PlugFinish, "error"> | undefined
   let usage: PlugUsage | undefined
   let failure: PlugError | undefined
@@ -120,12 +126,15 @@ async function streamText(
       else finish = event.reason
     } else if (event.type === "text-delta" && event.text.length > 0) {
       start()
-      chunk(event.text)
+      const out = holdback.push(event.text)
+      if (out.length > 0) chunk(out)
     }
   }
   failure ??= finish ? undefined : noFinish()
   if (failure) return { failure, started }
   start()
+  const rest = holdback.finish(finish === "stop").text
+  if (rest.length > 0) chunk(rest)
   chunk("", FINISH_REASONS[finish!])
   return { started, ...(usage ? { usage } : {}) }
 }