opencode-plugboard 0.19.0 → 0.21.0

package/src/openai/response.ts

@@ -36,6 +36,20 @@ export interface OpenAiExchange {
   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>
+  /** The caller's `json_schema`, checked against a text answer when the model skipped the respond call (`textFallback`). */
+  readonly structuredSchema?: Readonly<Record<string, unknown>>
+}
+
+/** Set on a complete answer that came from the final text, not the respond call (`textFallback`). */
+export const STRUCTURED_FALLBACK_HEADER = "x-plugboard-structured-fallback"
+
+/** One choice as a complete JSON body, with the status to send it with. */
+export interface CollectedChoice {
+  readonly status: number
+  readonly body: object
+  readonly retryAfterSeconds?: number
+  /** The structured answer was taken from the text (the response carries `STRUCTURED_FALLBACK_HEADER`). */
+  readonly structuredFallback?: boolean
 }
 
 /** How a streamed exchange ended. Nothing was written when `failure` is set and `started` is false: the caller answers with a real HTTP error. */
@@ -111,12 +125,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 }) },
   })),
 })
 
@@ -132,7 +146,7 @@ const encodeUsage = (usage: PlugUsage) => {
   }
 }
 
-const args = (input: unknown) => (typeof input === "string" ? input : JSON.stringify(input ?? {}))
+export const args = (input: unknown) => (typeof input === "string" ? input : JSON.stringify(input ?? {}))
 
 /**
  * Final finish_reason. Tool calls force `tool_calls` even when the upstream says `stop`;
@@ -152,26 +166,88 @@ const noFinish = (): PlugError => ({
 
 const failedRun = (): PlugError => ({ status: 500, kind: "server", message: "Model run failed" })
 
+/** The 502 for a structured turn that ended without its answer (the forced tool, or a valid JSON text). Shared with the legacy completions encoder. */
+export const structuredMissing = (tool: string): PlugError => ({
+  status: 502,
+  kind: "server",
+  code: "structured_output_missing",
+  message: `The model finished without calling the \`${tool}\` tool, so there is no structured output`,
+})
+
 /**
  * Structured-output projection, shared by the JSON and SSE encoders so both give the same body.
  * In structured mode (`exchange.structuredTool` set) the content is exactly the arguments of
  * the first call to that tool: prose, reasoning and any other tool call are suppressed, and
- * later calls to it are ignored. Without an answer the exchange fails, except when the model
- * stopped for `length` or `content-filter`, which keep their finish reasons with empty content.
+ * later calls to it are ignored. Without an answer the exchange fails with 502 (#172): a turn that
+ * ends with no structured output is never a 200 with empty content, whatever its finish reason.
  */
 const structured = {
   isAnswer: (exchange: OpenAiExchange, call: ToolCall) => exchange.structuredTool !== undefined && call.name === exchange.structuredTool,
   content: (call: ToolCall) => args(call.input),
   /** The failure for a finished structured exchange, if any. */
-  failure: (exchange: OpenAiExchange, finish: Exclude<PlugFinish, "error">, answered: boolean): PlugError | undefined =>
-    exchange.structuredTool === undefined || answered || finish === "length" || finish === "content-filter"
-      ? undefined
-      : {
-          status: 502,
-          kind: "server",
-          code: "structured_output_missing",
-          message: `The model finished without calling the \`${exchange.structuredTool}\` tool, so there is no structured output`,
-        },
+  failure: (exchange: OpenAiExchange, answered: boolean): PlugError | undefined =>
+    exchange.structuredTool === undefined || answered ? undefined : structuredMissing(exchange.structuredTool),
+}
+
+const isObjectValue = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value)
+
+const hasOwn = (value: Record<string, unknown>, key: string) => Object.prototype.hasOwnProperty.call(value, key)
+
+/** Whether a parsed JSON value has one JSON Schema type (`integer` is a whole number; an unknown type matches anything). */
+const hasType = (value: unknown, type: unknown): boolean => {
+  switch (type) {
+    case "object":
+      return isObjectValue(value)
+    case "array":
+      return Array.isArray(value)
+    case "string":
+      return typeof value === "string"
+    case "number":
+      return typeof value === "number"
+    case "integer":
+      return Number.isInteger(value)
+    case "boolean":
+      return typeof value === "boolean"
+    case "null":
+      return value === null
+    default:
+      return true
+  }
+}
+
+/**
+ * The part of JSON Schema checked on a text answer. The runtime carries no schema library (ajv is a
+ * dev dependency), so this is deliberately small: the top-level `type` (one type or a list), the
+ * top-level `required` keys, and the `type` of each top-level property that is present. Anything
+ * else in the schema (enum, nested objects, formats, additionalProperties) is not checked.
+ */
+export function matchesSchema(value: unknown, schema: Readonly<Record<string, unknown>>): boolean {
+  const types = Array.isArray(schema.type) ? schema.type : schema.type === undefined ? undefined : [schema.type]
+  if (types !== undefined && !types.some((type) => hasType(value, type))) return false
+  if (!isObjectValue(value)) return true
+  const required = Array.isArray(schema.required) ? schema.required : []
+  if (!required.every((key) => typeof key === "string" && hasOwn(value, key))) return false
+  if (!isObjectValue(schema.properties)) return true
+  return Object.entries(schema.properties).every(([key, property]) => {
+    if (!hasOwn(value, key) || !isObjectValue(property) || property.type === undefined) return true
+    const propertyTypes = Array.isArray(property.type) ? property.type : [property.type]
+    return propertyTypes.some((type) => hasType(value[key], type))
+  })
+}
+
+/**
+ * The answer of a structured turn that never called the respond tool, when its final text is the JSON
+ * the schema asks for (one code fence is stripped first). Undefined for any other text.
+ */
+export function textFallback(text: string, schema: Readonly<Record<string, unknown>>): string | undefined {
+  const candidate = unfence(text.trim())
+  let value: unknown
+  try {
+    value = JSON.parse(candidate)
+  } catch {
+    return undefined
+  }
+  return matchesSchema(value, schema) ? candidate : undefined
 }
 
 /** One markdown code fence (```json or a bare ```) around the whole text. */
@@ -195,10 +271,7 @@ export function unfence(text: string): string {
 const newId = () => `chatcmpl-${crypto.randomUUID().replaceAll("-", "").slice(0, 29)}`
 const now = () => Math.floor(Date.now() / 1000)
 
-export async function collectCompletion(
-  events: AsyncIterable<PlugEvent>,
-  exchange: OpenAiExchange,
-): Promise<{ status: number; body: object; retryAfterSeconds?: number }> {
+export async function collectCompletion(events: AsyncIterable<PlugEvent>, exchange: OpenAiExchange): Promise<CollectedChoice> {
   let text = ""
   const calls: ToolCall[] = []
   let finish: Exclude<PlugFinish, "error"> | undefined
@@ -229,7 +302,8 @@ export async function collectCompletion(
   // With the caller's tools offered, a call to one of them wins over the structured answer.
   const passthrough = exchange.callerTools === true && others.length > 0
   const isStructured = exchange.structuredTool !== undefined && !passthrough
-  const missing = passthrough ? undefined : structured.failure(exchange, finish, answer !== undefined)
+  const fallback = isStructured && answer === undefined && exchange.structuredSchema !== undefined ? textFallback(text, exchange.structuredSchema) : undefined
+  const missing = passthrough ? undefined : structured.failure(exchange, answer !== undefined || fallback !== undefined)
   if (missing) return { status: missing.status, body: encodeError(missing) }
   const toolCalls = isStructured ? [] : others
   const message: Record<string, unknown> = {
@@ -237,7 +311,7 @@ export async function collectCompletion(
     content: isStructured
       ? answer
         ? structured.content(answer)
-        : null
+        : (fallback ?? null)
       : exchange.structuredTool === undefined && text.length > 0
         ? exchange.jsonObject
           ? unfence(text)
@@ -261,6 +335,7 @@ export async function collectCompletion(
       choices: [{ index: 0, message, logprobs: null, finish_reason: finishReason(finish, toolCalls.length, isStructured) }],
       ...(usage ? { usage: encodeUsage(usage) } : {}),
     },
+    ...(fallback !== undefined ? { structuredFallback: true } : {}),
   }
 }
 
@@ -303,6 +378,8 @@ export async function streamCompletion(
   let started = false
   let calls = 0
   let answered = false
+  /** The text of a structured turn (not streamed): it is the answer only if the respond call never comes. */
+  let collected = ""
   /** With caller tools offered the structured answer waits for the finish: a caller tool call in the same step replaces it. */
   let held: ToolCall | undefined
   let finish: Exclude<PlugFinish, "error"> | undefined
@@ -358,6 +435,7 @@ export async function streamCompletion(
         }
         continue
       }
+      if (event.type === "text-delta") collected += event.text
       if (!(exchange.callerTools && event.type === "tool-call")) continue
     }
     if (exchange.jsonObject && event.type === "text-delta" && !passing) {
@@ -385,7 +463,8 @@ export async function streamCompletion(
 
   const passthrough = exchange.callerTools === true && calls > 0
   const isStructured = exchange.structuredTool !== undefined && !passthrough
-  failure ??= finish ? (passthrough ? undefined : structured.failure(exchange, finish, answered)) : noFinish()
+  const fallback = isStructured && !answered && exchange.structuredSchema !== undefined ? textFallback(collected, exchange.structuredSchema) : undefined
+  failure ??= finish ? (passthrough ? undefined : structured.failure(exchange, answered || fallback !== undefined)) : noFinish()
   if (failure) {
     if (!started) return { failure, started }
     if (!choice) {
@@ -401,6 +480,7 @@ export async function streamCompletion(
     if (rest.length > 0) chunk({ content: rest })
   }
   if (held && isStructured) chunk({ content: structured.content(held) })
+  if (fallback !== undefined) chunk({ content: fallback })
   chunk({}, finishReason(finish!, calls, isStructured))
   if (choice) return { started, ...(usage ? { usage } : {}) }
   if (exchange.includeUsage && usage) frame(chatUsageChunk(exchange.model, id, created, usage))

package/src/openai/route.ts

@@ -1,5 +1,5 @@
 /**
- * OpenAI front-end route table: `GET /healthz`, `GET /v1/models`, `GET /v1/models/{id}`,
+ * OpenAI front-end route table: `GET /healthz`, `GET /readyz`, `GET /v1/models`, `GET /v1/models/{id}`,
  * `POST /v1/chat/completions` (`n` > 1 through `./fanout.ts`), and the dispatch of `POST /v1/responses`
  * and `POST /v1/completions` to `src/responses/route.ts` and `src/completions/route.ts`.
  * Observability and first-run routes (`src/discovery.ts`, `src/metrics.ts`): `GET /` and `GET /v1`
@@ -21,11 +21,13 @@
  */
 
 import type { IncomingMessage, ServerResponse } from "node:http"
-import { DEFAULT_APP, authenticate, authenticateUsage, type PlugboardOptions } from "../config.js"
+import { serveAdmin } from "../admin/route.js"
+import { DEFAULT_APP, authenticate, authenticateUsage, bodyLimits, 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"
+import { buildDiscovery, buildStatus, readiness, renderDiscoveryHtml, sendText } from "../discovery.js"
 import {
   BodyError,
+  bodyPlugError,
   RequestAborted,
   beginRequest,
   boundEvents,
@@ -45,19 +47,22 @@ import { errorMessage, log, logError, withRequestId } from "../log.js"
 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 { reportPolicy, reportServerTools } 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"
+import { STRUCTURED_FALLBACK_HEADER, collectCompletion, encodeError, encodeModelList, streamCompletion } from "./response.js"
 import { dropRejected } from "./sampling.js"
 
 /** What the serving generation supplies per request. */
@@ -72,6 +77,8 @@ export interface RouteHost {
   readonly status?: () => RuntimeStatus
   /** Per-app usage (`src/usage.ts`): fed from the request log point, and served by `GET /v1/usage` when present. */
   readonly usage?: UsageRecorder
+  /** Runtime app keys (src/keys.ts, #55): their digests authenticate, and the admin routes (src/admin/route.ts) read them. */
+  readonly keys?: KeyStore
 }
 
 const SESSION_HEADER = "x-plugboard-session"
@@ -116,6 +123,8 @@ interface RequestInfo extends ServedInfo {
   failed?: string
   /** Sampling parameters dropped for this model (comma list), when any. */
   dropped?: string
+  /** The end user the body named, when kept (src/user.ts). */
+  user?: string
 }
 
 export function createOpenAiRoute(routeHost: RouteHost) {
@@ -123,6 +132,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) ||
@@ -161,7 +172,7 @@ export function createOpenAiRoute(routeHost: RouteHost) {
     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"
+    info.route = gemini || modelId !== undefined || known(route) || route === "GET /healthz" || route === "GET /readyz" ? route : "unknown"
     // Anthropic Messages: its own error shape and x-api-key auth, so it takes the request from here.
     if (isMessagesPath(path)) return serveMessages(host, { path, request, response, scope, info })
 
@@ -170,13 +181,19 @@ export function createOpenAiRoute(routeHost: RouteHost) {
 
     if (route === "GET /healthz") return sendJson(response, 200, { ok: true })
 
+    // Readiness (#160): no key, like /healthz. 503 until a generation serves, the pump runs and the catalog has loaded.
+    if (route === "GET /readyz") {
+      const verdict = readiness(runtimeStatus())
+      return sendJson(response, verdict.ready ? 200 : 503, verdict)
+    }
+
     // First-run pages: reachable without a key, so what they show depends on the caller (`buildDiscovery`).
     // With `keys` set, a request without credentials gets the minimal page; wrong credentials are a 401.
     if (DISCOVERY_ROUTES.includes(route)) {
       const keyed = Object.keys(host.options.keys).length > 0
       let app: string | undefined = keyed ? undefined : DEFAULT_APP
       if (keyed && request.headers.authorization !== undefined) {
-        const auth = authenticate(liveOptions(host.options), request.headers.authorization)
+        const auth = authenticate(liveOptions(host.options), request.headers.authorization, await runtimeDigests())
         if (isPlugError(auth)) return fail(response, auth)
         app = auth.app
       }
@@ -192,9 +209,13 @@ export function createOpenAiRoute(routeHost: RouteHost) {
     // Usage has its own credentials: the admin key reads every app, any other key only its own app (`authenticateUsage`).
     if (route === "GET /v1/usage" && host.usage) return serveUsage(request, response, url, host.usage, info)
 
+    // Runtime app keys (#55): the admin routes answer the admin key only, and are a 404 without `adminKey`.
+    if (path === "/v1/admin/keys" || path.startsWith("/v1/admin/keys/"))
+      return serveAdmin({ options: liveOptions(host.options), keys: host.keys }, { path, request, response, scope, info })
+
     // Authenticate before anything reveals which routes exist: an unauthenticated caller sees 401 for every path but /healthz and the first-run pages.
     // Gemini clients also send the key as `x-goog-api-key` or `?key=` (see `geminiAuthorization`).
-    const auth = authenticate(liveOptions(host.options), googleShaped ? geminiAuthorization(request, url) : request.headers.authorization)
+    const auth = authenticate(liveOptions(host.options), googleShaped ? geminiAuthorization(request, url) : request.headers.authorization, await runtimeDigests())
     if (isPlugError(auth)) return fail(response, auth)
     info.app = auth.app
 
@@ -252,7 +273,8 @@ export function createOpenAiRoute(routeHost: RouteHost) {
     const unsupported = checkJsonContentType(request)
     if (unsupported) return fail(response, unsupported)
 
-    const body = await readJsonBody(request, scope.signal)
+    const body = await readJsonBody(request, scope.signal, bodyLimits(host.options))
+    noteEndUser(response, info, bodyUser(body))
     if (route === "POST /v1/responses") return serveResponses(host, { app: auth.app, body, response, scope, info })
     if (route === "POST /v1/completions") return serveCompletions(host, { app: auth.app, body, response, scope, info })
     const parsed = parseChatRequest(body, host.options)
@@ -280,14 +302,16 @@ 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),
+        onServerTools: reportServerTools(response, exchange.stream),
         onCache: reportCache(response),
       }),
       scope,
@@ -313,12 +337,13 @@ export function createOpenAiRoute(routeHost: RouteHost) {
     }
 
     const result = await collectCompletion(events, exchange)
+    if (result.structuredFallback) response.setHeader(STRUCTURED_FALLBACK_HEADER, "text")
     sendJson(response, result.status, result.body, { retryAfterSeconds: result.retryAfterSeconds })
   }
 
   /** `GET /v1/usage?from=&to=&app=`. An app key may name only its own app (another one is a 403); the admin key may name any app or none. */
   async function serveUsage(request: IncomingMessage, response: ServerResponse, url: URL, usage: UsageRecorder, info: RequestInfo): Promise<void> {
-    const who = authenticateUsage(liveOptions(host.options), request.headers.authorization)
+    const who = authenticateUsage(liveOptions(host.options), request.headers.authorization, await runtimeDigests())
     if (isPlugError(who)) return fail(response, who)
     const app = url.searchParams.get("app") ?? undefined
     if (!who.admin) {
@@ -330,6 +355,7 @@ export function createOpenAiRoute(routeHost: RouteHost) {
       from: url.searchParams.get("from") ?? undefined,
       to: url.searchParams.get("to") ?? undefined,
       app: who.admin ? app : who.app,
+      user: url.searchParams.get("user") || undefined,
     })
     if (isPlugError(report)) return fail(response, report)
     // Each app's budget state, read from its current window rather than from the report's range (src/budgets.ts).
@@ -370,8 +396,8 @@ export function createOpenAiRoute(routeHost: RouteHost) {
           }
         } else if (caught instanceof BodyError) {
           outcome = `body_${caught.status}`
-          // 413: the client may still be sending; answer, then close (see `finishRequest`).
-          fail(response, { status: caught.status, kind: "invalid_request", message: caught.message }, caught.status === 413)
+          // Every refusal but an invalid body (400) may leave the client still sending: answer, then close (see `finishRequest`).
+          fail(response, bodyPlugError(caught), caught.status !== 400)
         } else {
           // Unexpected: the message goes to the log only; the client gets a generic one.
           outcome = "error"
@@ -396,10 +422,11 @@ 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 })
-      // 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 }
+      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. A readiness probe is never logged: it repeats until the backend is ready.
+      const probe = info.route === "GET /readyz" || ((info.route === "GET /healthz" || info.route === "GET /metrics") && outcome === "ok")
+      if (!probe) {
+        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/policy.ts

@@ -4,6 +4,7 @@ import type { ServerResponse } from "node:http"
 import type { PolicyNote } from "./contract.js"
 
 export const POLICY_HEADER = "x-plugboard-policy"
+export const SERVER_TOOLS_HEADER = "x-plugboard-server-tools"
 
 /**
  * The `CallContext.onPolicy` of a route: `x-plugboard-policy` (the notes, comma separated) while the
@@ -15,3 +16,18 @@ export function reportPolicy(response: ServerResponse): (notes: ReadonlyArray<Po
     response.setHeader(POLICY_HEADER, notes.join(","))
   }
 }
+
+/**
+ * The `CallContext.onServerTools` of a route: `x-plugboard-server-tools` with the number of server tool calls
+ * OpenCode ran for the answer, while the headers are open. Choices of `n` add up (each one reports once,
+ * when it ends, and the body is not sent before all of them). A stream gets no callback: its headers go first.
+ */
+export function reportServerTools(response: ServerResponse, stream: boolean): ((count: number) => void) | undefined {
+  if (stream) return undefined
+  let total = 0
+  return (count) => {
+    if (count <= 0 || response.headersSent || response.destroyed) return
+    total += count
+    response.setHeader(SERVER_TOOLS_HEADER, String(total))
+  }
+}

package/src/responses/request.ts

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

package/src/responses/response.ts

@@ -7,6 +7,7 @@
  * call passes a no-op `emit`. Reasoning deltas are dropped (no reasoning items are produced).
  */
 import type { PlugError, PlugEvent, PlugFinish, PlugUsage } from "../contract.js"
+import { structuredMissing, textFallback } from "../openai/response.js"
 
 type ToolCall = Extract<PlugEvent, { type: "tool-call" }>
 
@@ -25,6 +26,8 @@ export interface ResponsesExchange {
    * answer is the message text only when the step called no caller tool.
    */
   readonly callerTools?: boolean
+  /** The caller's `text.format` schema: a text answer is taken when the model skipped the respond call (`textFallback`, #173). */
+  readonly structuredSchema?: Readonly<Record<string, unknown>>
 }
 
 /** A stream event as emitted: `type` is also the SSE event name. */
@@ -37,6 +40,8 @@ export interface ResponseRun {
   readonly started: boolean
   /** The final response object (completed, incomplete or failed once started). */
   readonly response?: object
+  /** The structured answer came from the final text, not the respond call (`textFallback`). */
+  readonly structuredFallback?: boolean
 }
 
 type Item = Record<string, unknown>
@@ -63,21 +68,6 @@ const failedRun = (): PlugError => ({ status: 500, kind: "server", message: "Mod
 /** SSE frame of one stream event: `event: <type>` then `data: <json>`. */
 export const sseFrame = (event: ResponsesStreamEvent): string => `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`
 
-/**
- * Structured-output projection, same rules as the Chat Completions front-end: in structured mode
- * the message text is exactly the arguments of the first call to the `respond` tool; prose and
- * other calls are suppressed. Without an answer the exchange fails, except when the model
- * stopped for `length` or `content-filter`, which keep their status with empty output.
- */
-const structuredFailure = (exchange: ResponsesExchange, finish: Exclude<PlugFinish, "error">, answered: boolean): PlugError | undefined =>
-  exchange.structuredTool === undefined || answered || finish === "length" || finish === "content-filter"
-    ? undefined
-    : {
-        status: 502,
-        kind: "server",
-        code: "structured_output_missing",
-        message: `The model finished without calling the \`${exchange.structuredTool}\` tool, so there is no structured output`,
-      }
 
 /**
  * `committed`: whether the transport already committed a 200 stream before any event was emitted
@@ -114,6 +104,8 @@ export async function runResponse(
   let started = false
   let calls = 0
   let answered = false
+  /** The text of a structured turn (not emitted): it is the answer only if the respond call never comes (#173). */
+  let collected = ""
   /** With caller tools offered the structured answer waits for the finish: a caller tool call in the same step replaces it. */
   let held: ToolCall | undefined
   let finish: Exclude<PlugFinish, "error"> | undefined
@@ -199,6 +191,7 @@ export async function runResponse(
         }
         continue
       }
+      if (event.type === "text-delta") collected += event.text
       if (!(exchange.callerTools && event.type === "tool-call")) continue
     }
     if (event.type === "text-delta") text(event.text)
@@ -207,7 +200,9 @@ export async function runResponse(
 
   const passthrough = exchange.callerTools === true && calls > 0
   const structuredAnswer = exchange.structuredTool !== undefined && !passthrough
-  failure ??= finish ? (passthrough ? undefined : structuredFailure(exchange, finish, answered)) : noFinish()
+  const fallback = structuredAnswer && !answered && exchange.structuredSchema !== undefined ? textFallback(collected, exchange.structuredSchema) : undefined
+  const missing = passthrough || answered || fallback !== undefined || exchange.structuredTool === undefined ? undefined : structuredMissing(exchange.structuredTool)
+  failure ??= finish ? missing : noFinish()
   if (failure) {
     if (!started && !committed()) return { failure, started }
     start()
@@ -221,6 +216,7 @@ export async function runResponse(
   }
   start()
   if (held && structuredAnswer) text(args(held.input))
+  if (fallback !== undefined) text(fallback)
   closeMessage()
   const incomplete = finish === "length" ? "max_output_tokens" : finish === "content-filter" ? "content_filter" : undefined
   const response = envelope(incomplete ? "incomplete" : "completed", items, {
@@ -228,5 +224,5 @@ export async function runResponse(
     ...(usage ? { usage: encodeUsage(usage) } : {}),
   })
   send(incomplete ? "response.incomplete" : "response.completed", { response })
-  return { started, response }
+  return { started, response, ...(fallback !== undefined ? { structuredFallback: true } : {}) }
 }

package/src/responses/route.ts

@@ -14,9 +14,10 @@ import { reportServed, type ServedInfo } from "../fallback.js"
 import { boundEvents, sendError, sendJson, sseWriter, type RequestScope } from "../http.js"
 import { resolveModel } from "../models.js"
 import { reportCache } from "../cache.js"
-import { reportPolicy } from "../policy.js"
+import { reportPolicy, reportServerTools } from "../policy.js"
 import { reportUsage } from "../usage-header.js"
-import { encodeError } from "../openai/response.js"
+import { setSessionLink } from "../session/link.js"
+import { STRUCTURED_FALLBACK_HEADER, encodeError } from "../openai/response.js"
 import type { RouteHost } from "../openai/route.js"
 import { parseResponsesRequest } from "./request.js"
 import { runResponse, sseFrame } from "./response.js"
@@ -51,13 +52,15 @@ 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),
+      onServerTools: reportServerTools(response, exchange.stream),
       onCache: reportCache(response),
     }),
     scope,
@@ -79,5 +82,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)
+  if (run.structuredFallback) response.setHeader(STRUCTURED_FALLBACK_HEADER, "text")
   sendJson(response, 200, run.response)
 }

package/src/rpc.ts

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