opencode-plugboard 0.18.0 → 0.20.0

package/src/metrics.ts

@@ -62,8 +62,8 @@ export interface Metrics {
   dropped(params: ReadonlyArray<string>): void
   /** A model call failed before any output and was retried on the next target of its alias. */
   fallback(app: string): void
-  /** A call was refused with 429 by a concurrency cap (`concurrency`) or a requests-per-minute limit (`rate`). */
-  limited(app: string, reason: "concurrency" | "rate"): void
+  /** A call was refused with 429 by a concurrency cap (`concurrency`), a requests-per-minute limit (`rate`) or a budget (`budget`). */
+  limited(app: string, reason: "concurrency" | "rate" | "budget"): void
   /** A call the response cache applied to: a stored answer replayed (`hit`) or the model run (`miss`). */
   cache(app: string, result: "hit" | "miss"): void
   /** One history sweep ended. */
@@ -110,7 +110,7 @@ export function createMetrics(): Metrics {
   })
   const limited = new Counter({
     name: "plugboard_limited_total",
-    help: "Model calls refused with 429 by a concurrency cap or a requests-per-minute limit, by app and reason.",
+    help: "Model calls refused with 429 by a concurrency cap, a requests-per-minute limit or a budget, by app and reason.",
     labelNames: ["app", "reason"],
     registers: [registry],
   })

package/src/models.ts

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

package/src/openai/fanout.ts

@@ -25,6 +25,8 @@ import type { PlugError, PlugEvent, PlugRequest, PlugUsage } from "../contract.j
 import { reportServed, type ServedInfo } from "../fallback.js"
 import { reportCache } from "../cache.js"
 import { reportPolicy } from "../policy.js"
+import { reportUsage } from "../usage-header.js"
+import { SESSION_URL_HEADER, sessionUrl } from "../session/link.js"
 import { RequestAborted, boundEvents, sendError, sendJson, sseWriter, type RequestScope } from "../http.js"
 import { chatUsageChunk, collectCompletion, encodeError, streamCompletion, type OpenAiExchange, type StreamChoice, type StreamResult } from "./response.js"
 import type { RouteHost } from "./route.js"
@@ -154,7 +156,7 @@ const addUsage = (a: PlugUsage, b: PlugUsage): PlugUsage => {
   return out
 }
 
-export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls, response, scope, info, codec }: ChoicesCall): Promise<void> {
+export async function serveChoices(host: Pick<RouteHost, "caller" | "options">, { app, calls, response, scope, info, codec }: ChoicesCall): Promise<void> {
   const fail = (error: PlugError) => sendError(response, error, encodeError(error))
   // Abandoned requests (client gone, deadline passed) must never reach the model caller.
   if (scope.signal.aborted) throw scope.signal.reason
@@ -164,11 +166,15 @@ export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls
   const gscope = groupScope(scope, AbortSignal.any([scope.signal, group.signal]))
   /** History record ids as the callers report them, in choice order, for the response header (comma separated). */
   const records: Array<string | undefined> = []
+  /** The session page links of the same records, in choice order (option `historyUrl`, src/session/link.ts). */
+  const links: Array<string | undefined> = []
   // Headers: the first choice to be served wins. Body model: only a single call echoes the served model.
   const served = reportServed(response, info, (s) => {
     if (calls.length === 1) codec.setModel(s.model)
   })
   const policy = reportPolicy(response)
+  // One header for all choices: each answered call adds its tokens and cost (`x-plugboard-usage`, #52).
+  const usageHeader = reportUsage(response, codec.stream)
   // Each choice is a fresh sample: the response cache never serves or stores fan-out calls.
   const cache = reportCache(response)
   const open = (index: number) =>
@@ -176,13 +182,19 @@ export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls
       host.caller.stream(calls[index]!, {
         app,
         signal: gscope.signal,
-        onRecord: (recordID) => {
+        onRecord: (recordID, directory) => {
           if (response.headersSent || response.destroyed || !/^[\x21-\x7e]+$/.test(recordID)) return
           records[index] = recordID
           response.setHeader(SESSION_HEADER, records.filter((id) => id !== undefined).join(","))
+          if (host.options.historyUrl !== undefined) {
+            links[index] = sessionUrl(host.options.historyUrl, recordID, directory)
+            info.sessionUrl = links.filter((link) => link !== undefined).join(",")
+            response.setHeader(SESSION_URL_HEADER, info.sessionUrl)
+          }
         },
         onServed: served,
         onPolicy: policy,
+        onUsage: usageHeader,
         onCache: cache,
         noCache: calls.length > 1,
       }),

package/src/openai/request.ts

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

package/src/openai/response.ts

@@ -6,6 +6,7 @@
  */
 import type { PlugError, PlugErrorKind, PlugEvent, PlugFinish, PlugUsage } from "../contract.js"
 import type { ListedModel } from "../models.js"
+import { StopHoldback, stripStopTail } from "../stop.js"
 
 type ToolCall = Extract<PlugEvent, { type: "tool-call" }>
 
@@ -33,6 +34,8 @@ export interface OpenAiExchange {
    * stripped from the content (`unfence`).
    */
   readonly jsonObject?: boolean
+  /** The request's `stop`. 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 a streamed exchange ended. Nothing was written when `failure` is set and `started` is false: the caller answers with a real HTTP error. */
@@ -108,12 +111,12 @@ const encodePlugboard = (model: ListedModel["model"]) => ({
 /** `GET /v1/models` body. */
 export const encodeModelList = (models: ReadonlyArray<ListedModel>): object => ({
   object: "list",
-  data: models.map(({ id, ref, model }) => ({
+  data: models.map(({ id, ref, model, skill, agent }) => ({
     id,
     object: "model",
     created: 0,
     owned_by: ref.providerID,
-    plugboard: encodePlugboard(model),
+    plugboard: { ...encodePlugboard(model), ...(skill === undefined ? {} : { skill }), ...(agent === undefined ? {} : { agent }) },
   })),
 })
 
@@ -219,6 +222,7 @@ export async function collectCompletion(
     const error = failure ?? noFinish()
     return { status: error.status, body: encodeError(error), retryAfterSeconds: error.retryAfterSeconds }
   }
+  if (finish === "stop" && calls.length === 0 && exchange.structuredTool === undefined) text = stripStopTail(text, exchange.stop ?? []).text
 
   const answer = calls.find((call) => structured.isAnswer(exchange, call))
   const others = calls.filter((call) => !structured.isAnswer(exchange, call))
@@ -309,6 +313,12 @@ export async function streamCompletion(
     started = true
     chunk({ role: "assistant", content: "" })
   }
+  // 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 send = (text: string) => {
+    const out = holdback ? holdback.push(text) : text
+    if (out.length > 0) chunk({ content: out })
+  }
   // json_object: text that opens with a backtick may be a fenced answer, so it waits (as `pending`)
   // until a tool call or the finish shows the whole text; anything else streams as it comes. A
   // fenced answer therefore arrives as one chunk.
@@ -319,7 +329,7 @@ export async function streamCompletion(
     const text = unfence(pending)
     pending = ""
     start()
-    chunk({ content: text })
+    send(text)
   }
 
   for await (const event of events) {
@@ -359,10 +369,14 @@ export async function streamCompletion(
       }
       continue
     }
-    if (event.type !== "text-delta") flush()
+    if (event.type !== "text-delta") {
+      flush()
+      const rest = holdback?.release() ?? ""
+      if (rest.length > 0) chunk({ content: rest })
+    }
     start()
     if (event.type === "text-delta") {
-      if (event.text.length > 0) chunk({ content: event.text })
+      send(event.text)
     } else {
       // Tool calls arrive whole, so each goes out as one chunk with the next index.
       chunk({ tool_calls: [{ index: calls++, id: event.id, type: "function", function: { name: event.name, arguments: args(event.input) } }] })
@@ -382,6 +396,10 @@ export async function streamCompletion(
   }
   flush()
   start()
+  if (holdback) {
+    const rest = holdback.finish(finish === "stop" && calls === 0).text
+    if (rest.length > 0) chunk({ content: rest })
+  }
   if (held && isStructured) chunk({ content: structured.content(held) })
   chunk({}, finishReason(finish!, calls, isStructured))
   if (choice) return { started, ...(usage ? { usage } : {}) }

package/src/openai/route.ts

@@ -21,6 +21,7 @@
  */
 
 import type { IncomingMessage, ServerResponse } from "node:http"
+import { serveAdmin } from "../admin/route.js"
 import { DEFAULT_APP, authenticate, authenticateUsage, type PlugboardOptions } from "../config.js"
 import { isPlugError, type CatalogModel, type ModelCaller, type PlugError, type PlugRequest } from "../contract.js"
 import { buildDiscovery, buildStatus, renderDiscoveryHtml, sendText } from "../discovery.js"
@@ -46,13 +47,18 @@ import { NO_APP, outcomeLabel, type Metrics } from "../metrics.js"
 import { filterByCapability, listAvailableModels, parseCapability, resolveModel } from "../models.js"
 import { reportCache } from "../cache.js"
 import { reportPolicy } from "../policy.js"
+import { reportUsage } from "../usage-header.js"
 import { isMessagesPath, serveMessages } from "../anthropic/route.js"
 import { serveCompletions } from "../completions/route.js"
 import { serveResponses } from "../responses/route.js"
 import { liveOptions, processMetrics, processStatus, type RuntimeStatus } from "../runtime.js"
+import { budgetFor, budgetStatus } from "../budgets.js"
+import type { KeyStore } from "../keys.js"
 import type { UsageRecorder } from "../usage.js"
 import { DASHBOARD_ROUTES } from "../dashboard/page.js"
 import { serveDashboard } from "../dashboard/assets.js"
+import { bodyUser, noteEndUser } from "../user.js"
+import { setSessionLink } from "../session/link.js"
 import { chatCodec, serveChoices } from "./fanout.js"
 import { parseChatRequest } from "./request.js"
 import { collectCompletion, encodeError, encodeModelList, streamCompletion } from "./response.js"
@@ -70,6 +76,8 @@ export interface RouteHost {
   readonly status?: () => RuntimeStatus
   /** Per-app usage (`src/usage.ts`): fed from the request log point, and served by `GET /v1/usage` when present. */
   readonly usage?: UsageRecorder
+  /** Runtime app keys (src/keys.ts, #55): their digests authenticate, and the admin routes (src/admin/route.ts) read them. */
+  readonly keys?: KeyStore
 }
 
 const SESSION_HEADER = "x-plugboard-session"
@@ -114,6 +122,8 @@ interface RequestInfo extends ServedInfo {
   failed?: string
   /** Sampling parameters dropped for this model (comma list), when any. */
   dropped?: string
+  /** The end user the body named, when kept (src/user.ts). */
+  user?: string
 }
 
 export function createOpenAiRoute(routeHost: RouteHost) {
@@ -121,6 +131,8 @@ export function createOpenAiRoute(routeHost: RouteHost) {
   const metrics = routeHost.options.metrics ? (routeHost.metrics ?? processMetrics()) : undefined
   const runtimeStatus = routeHost.status ?? processStatus
   const host: RouteHost = metrics ? { ...routeHost, caller: metered(routeHost.caller, metrics) } : routeHost
+  /** The runtime app keys that authenticate (loaded from storage on first use, #55). */
+  const runtimeDigests = async () => (host.keys ? await host.keys.digests() : [])
   /** Routes with a handler of their own. `GET /metrics` exists only when enabled; otherwise it is an unknown path. */
   const known = (route: string) =>
     KNOWN_ROUTES.includes(route) ||
@@ -154,7 +166,9 @@ export function createOpenAiRoute(routeHost: RouteHost) {
     const path = url.pathname
     const modelId = request.method === "GET" && path.startsWith(MODEL_PREFIX) && path.length > MODEL_PREFIX.length ? decodeSegment(path.slice(MODEL_PREFIX.length)) : undefined
     const gemini = matchGeminiRoute(request.method, path)
-    if (gemini) googleErrors.add(response)
+    // Any /v1beta path is Google's API, even one that matches no Gemini route (#150): its errors use Google's body.
+    const googleShaped = gemini !== undefined || path === "/v1beta" || path.startsWith("/v1beta/")
+    if (googleShaped) googleErrors.add(response)
     const route = gemini?.route ?? `${request.method} ${modelId !== undefined ? "/v1/models/{id}" : path}`
     // Arbitrary client paths stay out of the log.
     info.route = gemini || modelId !== undefined || known(route) || route === "GET /healthz" ? route : "unknown"
@@ -172,7 +186,7 @@ export function createOpenAiRoute(routeHost: RouteHost) {
       const keyed = Object.keys(host.options.keys).length > 0
       let app: string | undefined = keyed ? undefined : DEFAULT_APP
       if (keyed && request.headers.authorization !== undefined) {
-        const auth = authenticate(liveOptions(host.options), request.headers.authorization)
+        const auth = authenticate(liveOptions(host.options), request.headers.authorization, await runtimeDigests())
         if (isPlugError(auth)) return fail(response, auth)
         app = auth.app
       }
@@ -188,12 +202,25 @@ export function createOpenAiRoute(routeHost: RouteHost) {
     // Usage has its own credentials: the admin key reads every app, any other key only its own app (`authenticateUsage`).
     if (route === "GET /v1/usage" && host.usage) return serveUsage(request, response, url, host.usage, info)
 
+    // Runtime app keys (#55): the admin routes answer the admin key only, and are a 404 without `adminKey`.
+    if (path === "/v1/admin/keys" || path.startsWith("/v1/admin/keys/"))
+      return serveAdmin({ options: liveOptions(host.options), keys: host.keys }, { path, request, response, scope, info })
+
     // Authenticate before anything reveals which routes exist: an unauthenticated caller sees 401 for every path but /healthz and the first-run pages.
     // Gemini clients also send the key as `x-goog-api-key` or `?key=` (see `geminiAuthorization`).
-    const auth = authenticate(liveOptions(host.options), gemini ? geminiAuthorization(request, url) : request.headers.authorization)
+    const auth = authenticate(liveOptions(host.options), googleShaped ? geminiAuthorization(request, url) : request.headers.authorization, await runtimeDigests())
     if (isPlugError(auth)) return fail(response, auth)
     info.app = auth.app
 
+    // A /v1beta path no Gemini route matches: the AI SDK and LangChain send a model id with a slash and no `models/` prefix (#150).
+    if (googleShaped && !gemini)
+      return fail(response, {
+        status: 404,
+        kind: "not_found",
+        code: "not_found",
+        message: `No Gemini route for ${request.method} ${path}. Expected POST /v1beta/models/{model}:generateContent or POST /v1beta/models/{model}:streamGenerateContent; the path must start with /v1beta/models/. GET /v1beta/models lists the models.`,
+      })
+
     if (!gemini && modelId === undefined && !known(route)) {
       return fail(response, {
         status: 404,
@@ -240,6 +267,7 @@ export function createOpenAiRoute(routeHost: RouteHost) {
     if (unsupported) return fail(response, unsupported)
 
     const body = await readJsonBody(request, scope.signal)
+    noteEndUser(response, info, bodyUser(body))
     if (route === "POST /v1/responses") return serveResponses(host, { app: auth.app, body, response, scope, info })
     if (route === "POST /v1/completions") return serveCompletions(host, { app: auth.app, body, response, scope, info })
     const parsed = parseChatRequest(body, host.options)
@@ -267,13 +295,15 @@ export function createOpenAiRoute(routeHost: RouteHost) {
       host.caller.stream(call, {
         app: auth.app,
         signal: scope.signal,
-        onRecord: (recordID) => {
+        onRecord: (recordID, directory) => {
           if (response.headersSent || response.destroyed || !/^[\x21-\x7e]+$/.test(recordID)) return
           response.setHeader(SESSION_HEADER, recordID)
+          setSessionLink(response, info, host.options.historyUrl, recordID, directory)
         },
         // An alias with fallbacks: report which target answered, and echo it as the response model.
         onServed: reportServed(response, info, (served) => void (exchange.model = served.model)),
         onPolicy: reportPolicy(response),
+        onUsage: reportUsage(response, exchange.stream),
         onCache: reportCache(response),
       }),
       scope,
@@ -304,7 +334,7 @@ export function createOpenAiRoute(routeHost: RouteHost) {
 
   /** `GET /v1/usage?from=&to=&app=`. An app key may name only its own app (another one is a 403); the admin key may name any app or none. */
   async function serveUsage(request: IncomingMessage, response: ServerResponse, url: URL, usage: UsageRecorder, info: RequestInfo): Promise<void> {
-    const who = authenticateUsage(liveOptions(host.options), request.headers.authorization)
+    const who = authenticateUsage(liveOptions(host.options), request.headers.authorization, await runtimeDigests())
     if (isPlugError(who)) return fail(response, who)
     const app = url.searchParams.get("app") ?? undefined
     if (!who.admin) {
@@ -316,8 +346,17 @@ export function createOpenAiRoute(routeHost: RouteHost) {
       from: url.searchParams.get("from") ?? undefined,
       to: url.searchParams.get("to") ?? undefined,
       app: who.admin ? app : who.app,
+      user: url.searchParams.get("user") || undefined,
     })
     if (isPlugError(report)) return fail(response, report)
+    // Each app's budget state, read from its current window rather than from the report's range (src/budgets.ts).
+    if (host.options.budgets) {
+      const at = Date.now()
+      for (const [name, entry] of Object.entries(report.apps)) {
+        const budget = budgetFor(host.options.budgets, name)
+        if (budget) entry.budgets = await budgetStatus(usage, budget, name, at)
+      }
+    }
     return sendJson(response, 200, report)
   }
 
@@ -374,10 +413,10 @@ export function createOpenAiRoute(routeHost: RouteHost) {
       } catch {}
       const ms = Date.now() - started
       metrics?.requestFinished({ app: info.app ?? NO_APP, route: info.route, status: response.statusCode, outcome: outcomeLabel(outcome, response.statusCode), ms })
-      if (info.app !== undefined) host.usage?.request({ app: info.app, route: info.route, status: response.statusCode, outcome: outcomeLabel(outcome, response.statusCode), ms })
+      if (info.app !== undefined) host.usage?.request({ app: info.app, route: info.route, status: response.statusCode, outcome: outcomeLabel(outcome, response.statusCode), ms, ...(info.user === undefined ? {} : { user: info.user }) })
       // Probes and scrapes that succeed are not worth a line each.
       if ((info.route !== "GET /healthz" && info.route !== "GET /metrics") || outcome !== "ok") {
-        const fields = { id, route: info.route, app: info.app, model: info.model, served: info.served, fallbacks: info.fallbacks, dropped: info.dropped, status: response.statusCode, ms, outcome, error }
+        const fields = { id, route: info.route, app: info.app, user: info.user, session_url: info.sessionUrl, model: info.model, served: info.served, fallbacks: info.fallbacks, dropped: info.dropped, status: response.statusCode, ms, outcome, error }
         if (outcome === "error" || response.statusCode >= 500) logError("request.failed", fields)
         else log("request", fields)
       }

package/src/responses/request.ts

@@ -2,13 +2,15 @@
  * OpenAI Responses request -> neutral `PlugRequest` plus the `ResponsesExchange` the response
  * encoder needs.
  *
- * Pure function: no I/O. Stateless subset: the caller sends the whole conversation in `input`
- * each time, which is how history already works. Anything that needs server-side state
- * (`previous_response_id`, `conversation`, `item_reference`, `background`) or a hosted tool is
- * rejected with 400 `unsupported_parameter` naming the field. The route resolves `model` to a
+ * Pure function: no I/O. The caller sends the whole conversation in `input` each time, which is
+ * how history already works. An `item_reference` is resolved through the `resolve` argument (the
+ * route passes the per-app store of recent answers, src/responses/store.ts; #147). Anything else that
+ * needs server-side state (`previous_response_id`, `conversation`, `background`) or a hosted tool
+ * is rejected with 400 `unsupported_parameter` naming the field. The route resolves `model` to a
  * `ModelRef` afterwards, which is why the request omits `ref`.
  */
 import type { PlugboardOptions } from "../config.js"
+import { bodyUser, userField } from "../user.js"
 import {
   isPlugError,
   type PlugError,
@@ -121,7 +123,23 @@ const assistantText = (content: unknown, param: string): string | PlugError => {
  * assistant message, the shape the Chat Completions front-end produces, so a parallel-call turn
  * is one message followed by its results.
  */
-const parseInput = (input: unknown): { system: string[]; messages: PlugMessage[] } | PlugError => {
+/** The output item an `item_reference` names, or undefined when the app's store does not hold it. */
+export type ItemResolver = (itemId: string) => JsonObject | undefined
+
+/** An `item_reference` is the output item of an earlier answer, decoded as that item (#147). */
+const resolveReference = (item: JsonObject, param: string, resolve: ItemResolver | undefined): JsonObject | PlugError => {
+  if (typeof item.id !== "string" || item.id.length === 0) return bad("item_reference needs the id of an output item", `${param}.id`)
+  const found = resolve?.(item.id)
+  if (found === undefined)
+    return bad(
+      `item_reference "${item.id}" is not known to plugboard: it keeps the output of recent answers for an hour, per app. Send the earlier items in full, or send store: false (Vercel AI SDK: providerOptions.openai.store = false)`,
+      `${param}.id`,
+      "item_not_found",
+    )
+  return found
+}
+
+const parseInput = (input: unknown, resolve: ItemResolver | undefined): { system: string[]; messages: PlugMessage[] } | PlugError => {
   if (typeof input === "string") return { system: [], messages: [{ role: "user", content: [{ type: "text", text: input }] }] }
   if (!Array.isArray(input) || input.length === 0) return bad("input must be a string or a non-empty array of items", "input")
 
@@ -134,9 +152,11 @@ const parseInput = (input: unknown): { system: string[]; messages: PlugMessage[]
     pending = undefined
   }
 
-  for (const [index, item] of input.entries()) {
+  for (const [index, given] of input.entries()) {
     const param = `input[${index}]`
-    if (!isRecord(item)) return bad("Each input item must be an object", param)
+    if (!isRecord(given)) return bad("Each input item must be an object", param)
+    const item = given.type === "item_reference" ? resolveReference(given, param, resolve) : given
+    if (isPlugError(item)) return item
     const type = item.type ?? (item.role !== undefined ? "message" : undefined)
     switch (type) {
       case "message": {
@@ -192,11 +212,6 @@ const parseInput = (input: unknown): { system: string[]; messages: PlugMessage[]
       // Reasoning items carry no content plugboard can replay; they are dropped.
       case "reasoning":
         break
-      case "item_reference":
-        return unsupported(
-          "item_reference needs server-side state, which plugboard does not keep; send the full items instead (Vercel AI SDK: providerOptions.openai.store = false)",
-          `${param}.type`,
-        )
       default:
         return unsupported(`Unsupported input item type "${String(type)}"`, `${param}.type`)
     }
@@ -296,7 +311,7 @@ const checkUnsupported = (body: JsonObject): PlugError | undefined => {
   if (body.truncation != null && body.truncation !== "disabled") return unsupported('Only truncation "disabled" is supported', "truncation")
 }
 
-export function parseResponsesRequest(body: unknown, options: PlugboardOptions): ParsedResponses | PlugError {
+export function parseResponsesRequest(body: unknown, options: PlugboardOptions, resolve?: ItemResolver): ParsedResponses | PlugError {
   if (!isRecord(body)) return bad("Request body must be a JSON object")
   if (typeof body.model !== "string" || body.model.length === 0) return bad("model is required", "model")
   if (body.input == null) return bad("input is required", "input")
@@ -305,7 +320,7 @@ export function parseResponsesRequest(body: unknown, options: PlugboardOptions):
   if (body.instructions != null && typeof body.instructions !== "string") return bad("instructions must be a string", "instructions")
   if (body.reasoning != null && !isRecord(body.reasoning)) return bad("reasoning must be an object", "reasoning")
 
-  const parsed = parseInput(body.input)
+  const parsed = parseInput(body.input, resolve)
   if (isPlugError(parsed)) return parsed
   const callerTools = parseTools(body.tools)
   if (!Array.isArray(callerTools)) return callerTools
@@ -339,6 +354,7 @@ export function parseResponsesRequest(body: unknown, options: PlugboardOptions):
   const instructions = typeof body.instructions === "string" && body.instructions.length > 0 ? [body.instructions] : []
   const system = [...instructions, ...parsed.system, ...(format.instruction ? [format.instruction] : [])]
   const request: Omit<PlugRequest, "ref"> = {
+    ...userField(bodyUser(body)),
     model: body.model,
     system,
     messages: parsed.messages,

package/src/responses/route.ts

@@ -15,10 +15,13 @@ import { boundEvents, sendError, sendJson, sseWriter, type RequestScope } from "
 import { resolveModel } from "../models.js"
 import { reportCache } from "../cache.js"
 import { reportPolicy } from "../policy.js"
+import { reportUsage } from "../usage-header.js"
+import { setSessionLink } from "../session/link.js"
 import { encodeError } from "../openai/response.js"
 import type { RouteHost } from "../openai/route.js"
 import { parseResponsesRequest } from "./request.js"
 import { runResponse, sseFrame } from "./response.js"
+import { findItem, rememberAnswer } from "./store.js"
 
 const SESSION_HEADER = "x-plugboard-session"
 
@@ -34,7 +37,7 @@ export interface ResponsesCall {
 export async function serveResponses(host: RouteHost, { app, body, response, scope, info }: ResponsesCall): Promise<void> {
   const fail = (error: PlugError) => sendError(response, error, encodeError(error))
 
-  const parsed = parseResponsesRequest(body, host.options)
+  const parsed = parseResponsesRequest(body, host.options, (itemId) => findItem(app, itemId))
   if (isPlugError(parsed)) return fail(parsed)
   const catalog = await scope.race(host.loadCatalog())
   const ref = resolveModel(host.options, parsed.request.model, catalog, parsed.reasoningEffort)
@@ -49,12 +52,14 @@ export async function serveResponses(host: RouteHost, { app, body, response, sco
     host.caller.stream(call, {
       app,
       signal: scope.signal,
-      onRecord: (recordID) => {
+      onRecord: (recordID, directory) => {
         if (response.headersSent || response.destroyed || !/^[\x21-\x7e]+$/.test(recordID)) return
         response.setHeader(SESSION_HEADER, recordID)
+        setSessionLink(response, info, host.options.historyUrl, recordID, directory)
       },
       onServed: reportServed(response, info, (served) => void (exchange.model = served.model)),
       onPolicy: reportPolicy(response),
+      onUsage: reportUsage(response, exchange.stream),
       onCache: reportCache(response),
     }),
     scope,
@@ -62,11 +67,12 @@ export async function serveResponses(host: RouteHost, { app, body, response, sco
 
   if (exchange.stream) {
     const sse = sseWriter(response, scope.signal)
-    const { failure } = await runResponse(sse.paced(events), exchange, (event) => sse.write(sseFrame(event)), () => sse.started)
+    const run = await runResponse(sse.paced(events), exchange, (event) => sse.write(sseFrame(event)), () => sse.started)
+    if (run.response && !run.failure) rememberAnswer(app, run.response)
     if (!sse.started && !response.headersSent) {
-      if (!scope.signal.aborted || scope.timedOut) fail(failure ?? { status: 502, kind: "server", message: "No response from the model" })
+      if (!scope.signal.aborted || scope.timedOut) fail(run.failure ?? { status: 502, kind: "server", message: "No response from the model" })
     } else {
-      if (failure) info.failed = failure.code ?? failure.kind
+      if (run.failure) info.failed = run.failure.code ?? run.failure.kind
       if (!response.writableEnded) response.end()
     }
     return
@@ -74,5 +80,6 @@ export async function serveResponses(host: RouteHost, { app, body, response, sco
 
   const run = await runResponse(events, exchange, () => {})
   if (run.failure || !run.response) return fail(run.failure ?? { status: 502, kind: "server", message: "No response from the model" })
+  rememberAnswer(app, run.response)
   sendJson(response, 200, run.response)
 }