opencode-plugboard 0.20.0 → 0.21.1

package/src/http.ts

@@ -6,7 +6,7 @@
 
 import type { IncomingMessage, ServerResponse } from "node:http"
 import { raceAbort } from "./abort.js"
-import { isLoopbackHost, type PlugboardOptions } from "./config.js"
+import { BODY_LIMIT_DEFAULTS, type BodyLimits, isLoopbackHost, type PlugboardOptions } from "./config.js"
 import type { PlugError, PlugEvent } from "./contract.js"
 
 const MAX_BODY_BYTES = 32 * 1024 * 1024
@@ -19,16 +19,44 @@ const DEADLINE_GRACE_MS = 2_000
 /** An SSE stream idle for this long gets a comment line, so a client with a header or idle timeout keeps waiting for a model that is still reasoning. */
 const KEEPALIVE_MS = 15_000
 
-/** A request body that cannot be accepted: too large, or not JSON. `status` is the HTTP status to answer with. */
+/**
+ * A request body that cannot be accepted: too large, not JSON, not complete in time (408), or refused
+ * because the process has no room for it (503). `status` is the HTTP status to answer with; `code` and
+ * `retryAfterSeconds` go to the wire (`bodyPlugError`).
+ */
 export class BodyError extends Error {
   constructor(
     readonly status: number,
     message: string,
+    readonly code?: string,
+    readonly retryAfterSeconds?: number,
   ) {
     super(message)
   }
 }
 
+/** The `PlugError` a refused body answers with: `server_busy` (503) is a server kind, a slow body (408) a timeout. */
+export function bodyPlugError(error: BodyError): PlugError {
+  const kind: PlugError["kind"] = error.status === 503 ? "server" : error.status === 408 ? "timeout" : "invalid_request"
+  return {
+    status: error.status,
+    kind,
+    message: error.message,
+    ...(error.code === undefined ? {} : { code: error.code }),
+    ...(error.retryAfterSeconds === undefined ? {} : { retryAfterSeconds: error.retryAfterSeconds }),
+  }
+}
+
+/** Process-wide bytes of request bodies being read. On `globalThis` under a versioned key (I6), so every plugin generation shares one budget. */
+interface BodyBudget {
+  inFlight: number
+}
+const BODY_BUDGET = Symbol.for("opencode-plugboard.body-budget/1")
+const bodyBudget = (): BodyBudget => {
+  const slot = globalThis as Record<symbol, BodyBudget | undefined>
+  return (slot[BODY_BUDGET] ??= { inFlight: 0 })
+}
+
 /** Why a request's work was abandoned: the client went away, or the deadline passed. It is the abort reason of `RequestScope.signal`. */
 export class RequestAborted extends Error {
   constructor(readonly kind: "disconnected" | "timeout") {
@@ -105,21 +133,40 @@ export function beginRequest(request: IncomingMessage, response: ServerResponse,
 }
 
 /**
- * Reads the body as JSON (an empty body is `{}`). Rejects with `BodyError` (413, 400), the abort
- * reason of `signal` or the stream's error. On rejection the rest of the body is discarded, not
+ * Reads the body as JSON (an empty body is `{}`). Rejects with `BodyError` (413, 400, 408 or 503), the
+ * abort reason of `signal` or the stream's error. On rejection the rest of the body is discarded, not
  * buffered, so the response can still be delivered (see `finishRequest`).
+ *
+ * Bounded before it is buffered (#156, invariant I28). The bytes held by every body being read in the
+ * process stay within `limits.maxBytesInFlight`: a declared Content-Length is charged before the first
+ * byte is read, a body without one as it arrives, and a body that would go over is refused with 503
+ * `server_busy` (Retry-After 1). A body not complete within `limits.readTimeoutMs` is refused with 408.
  */
-export function readJsonBody(request: IncomingMessage, signal: AbortSignal): Promise<unknown> {
+export function readJsonBody(request: IncomingMessage, signal: AbortSignal, limits: BodyLimits = BODY_LIMIT_DEFAULTS): Promise<unknown> {
   return new Promise((resolve, reject) => {
-    const declared = Number(request.headers["content-length"])
-    if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+    const declared = Math.max(0, Number(request.headers["content-length"]) || 0)
+    if (declared > MAX_BODY_BYTES) {
       request.resume()
       return reject(new BodyError(413, "Request body too large"))
     }
     if (signal.aborted) return reject(signal.reason)
+    const budget = bodyBudget()
     const chunks: Buffer[] = []
     let size = 0
+    // Bytes this read holds in the budget. Released on every exit: complete, refused or abandoned.
+    let held = 0
+    const charge = (bytes: number): boolean => {
+      if (budget.inFlight + bytes > limits.maxBytesInFlight) return false
+      budget.inFlight += bytes
+      held += bytes
+      return true
+    }
+    const busy = () => new BodyError(503, "Too many request bodies are being read; retry shortly", "server_busy", 1)
+    let timer: ReturnType<typeof setTimeout> | undefined
     const cleanup = () => {
+      clearTimeout(timer)
+      budget.inFlight -= held
+      held = 0
       request.off("data", onData)
       request.off("error", onError)
       request.off("end", onEnd)
@@ -134,6 +181,7 @@ export function readJsonBody(request: IncomingMessage, signal: AbortSignal): Pro
     const onData = (chunk: Buffer) => {
       size += chunk.length
       if (size > MAX_BODY_BYTES) return stop(new BodyError(413, "Request body too large"))
+      if (size > held && !charge(size - held)) return stop(busy())
       chunks.push(chunk)
     }
     const onError = (error: Error) => stop(error)
@@ -146,6 +194,16 @@ export function readJsonBody(request: IncomingMessage, signal: AbortSignal): Pro
         reject(new BodyError(400, "Request body is not valid JSON"))
       }
     }
+    // The declared length is charged before the first byte is read, so a refusal costs no buffering.
+    if (declared > 0 && !charge(declared)) {
+      request.resume()
+      return reject(busy())
+    }
+    timer = setTimeout(
+      () => stop(new BodyError(408, `Request body was not received within ${limits.readTimeoutMs} ms (option limits.bodyReadTimeoutMs)`, "body_read_timeout")),
+      limits.readTimeoutMs,
+    )
+    timer.unref?.()
     request.on("data", onData)
     request.on("error", onError)
     request.on("end", onEnd)

package/src/openai/fanout.ts

@@ -24,11 +24,21 @@ import type { ServerResponse } from "node:http"
 import type { PlugError, PlugEvent, PlugRequest, PlugUsage } from "../contract.js"
 import { reportServed, type ServedInfo } from "../fallback.js"
 import { reportCache } from "../cache.js"
-import { reportPolicy } from "../policy.js"
+import { reportPolicy, reportServerTools } 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 {
+  STRUCTURED_FALLBACK_HEADER,
+  chatUsageChunk,
+  collectCompletion,
+  encodeError,
+  streamCompletion,
+  type CollectedChoice,
+  type OpenAiExchange,
+  type StreamChoice,
+  type StreamResult,
+} from "./response.js"
 import type { RouteHost } from "./route.js"
 
 const SESSION_HEADER = "x-plugboard-session"
@@ -40,7 +50,7 @@ export interface ChoiceCodec {
   /** Prefix of the shared stream id (`chatcmpl-`, `cmpl-`). */
   readonly idPrefix: string
   /** One choice as a complete JSON body with `choices[0]` and `usage`. */
-  collect(events: AsyncIterable<PlugEvent>, index: number): Promise<{ status: number; body: object; retryAfterSeconds?: number }>
+  collect(events: AsyncIterable<PlugEvent>, index: number): Promise<CollectedChoice>
   /** One choice of the shared stream: this choice's chunks only (see `StreamChoice`). */
   streamChoice(events: AsyncIterable<PlugEvent>, write: (chunk: string) => void, choice: StreamChoice): Promise<StreamResult>
   /** The final chunk with the summed usage (`include_usage`). */
@@ -175,6 +185,8 @@ export async function serveChoices(host: Pick<RouteHost, "caller" | "options">,
   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)
+  // One header for all choices too: the server tool calls of every choice add up (`x-plugboard-server-tools`).
+  const serverToolsHeader = reportServerTools(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) =>
@@ -195,6 +207,7 @@ export async function serveChoices(host: Pick<RouteHost, "caller" | "options">,
         onServed: served,
         onPolicy: policy,
         onUsage: usageHeader,
+        onServerTools: serverToolsHeader,
         onCache: cache,
         noCache: calls.length > 1,
       }),
@@ -202,8 +215,8 @@ export async function serveChoices(host: Pick<RouteHost, "caller" | "options">,
     )
 
   if (!codec.stream) {
-    const results = await new Promise<Array<{ status: number; body: object; retryAfterSeconds?: number }>>((resolve, reject) => {
-      const done: Array<{ status: number; body: object; retryAfterSeconds?: number }> = []
+    const results = await new Promise<CollectedChoice[]>((resolve, reject) => {
+      const done: CollectedChoice[] = []
       let left = calls.length
       calls.forEach((_, index) => {
         codec.collect(open(index), index).then(
@@ -223,6 +236,7 @@ export async function serveChoices(host: Pick<RouteHost, "caller" | "options">,
       })
     })
     const first = results[0]!
+    if (results.some((result) => result.structuredFallback)) response.setHeader(STRUCTURED_FALLBACK_HEADER, "text")
     return sendJson(response, first.status, results.length === 1 ? first.body : mergeBodies(results.map((result) => result.body)), { retryAfterSeconds: first.retryAfterSeconds })
   }
 

package/src/openai/request.ts

@@ -32,7 +32,7 @@ export interface ParsedChat {
 }
 
 /** Name of the forced tool that carries structured output. */
-const RESPOND_TOOL = "respond"
+export const RESPOND_TOOL = "respond"
 
 /** The most stop sequences OpenAI accepts. */
 const MAX_STOP = 4
@@ -196,14 +196,14 @@ const parseToolChoice = (raw: unknown): PlugToolChoice | undefined | PlugError =
 }
 
 /** System instruction for `json_object`: no schema, so the caller's prompt describes the keys (OpenAI semantics). */
-const JSON_OBJECT_INSTRUCTION = "Respond with a single valid JSON object only."
+export const JSON_OBJECT_INSTRUCTION = "Respond with a single valid JSON object only."
 
 /**
  * `json_schema` -> the `respond` tool (`structured`; forced unless the caller also sends tools).
  * `json_object` -> a system instruction and plain text content (`instruction`): there is no schema
  * to force a tool with.
  */
-const parseResponseFormat = (raw: unknown): { structured?: PlugTool; instruction?: string } | PlugError => {
+export const parseResponseFormat = (raw: unknown): { structured?: PlugTool; instruction?: string } | PlugError => {
   if (raw == null) return {}
   if (!isRecord(raw)) return bad("response_format must be an object", "response_format")
   if (raw.type === "text") return {}
@@ -339,7 +339,7 @@ export function parseChatRequest(body: unknown, options: PlugboardOptions): Pars
       model: body.model,
       stream: body.stream === true,
       includeUsage: streamOptions.include_usage === true,
-      ...(respond ? { structuredTool: RESPOND_TOOL, ...(withCallerTools ? { callerTools: true } : {}) } : {}),
+      ...(respond ? { structuredTool: RESPOND_TOOL, structuredSchema: respond.parameters, ...(withCallerTools ? { callerTools: true } : {}) } : {}),
       ...(format.instruction ? { jsonObject: true } : {}),
       ...(generation.stop ? { stop: generation.stop } : {}),
     },

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. */
@@ -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,28 +166,99 @@ 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 {
+  // The whole text (fenced or not), else the one fenced block inside prose: Claude, told not to call
+  // tools, skips `respond` and answers "Here is the JSON: ```json {...}```" (found by the live suite).
+  const fenced = [...text.matchAll(FENCE_ANYWHERE)].map((match) => match[1]!.trim())
+  const candidates = [unfence(text.trim()), ...(fenced.length === 1 ? fenced : [])]
+  for (const candidate of candidates) {
+    let value: unknown
+    try {
+      value = JSON.parse(candidate)
+    } catch {
+      continue
+    }
+    if (matchesSchema(value, schema)) return candidate
+  }
+  return undefined
+}
+
+/** Every fenced code block (```json or a bare ```) anywhere in the text. */
+const FENCE_ANYWHERE = /```[ \t]*(?:json)?[ \t]*\r?\n([\s\S]*?)\r?\n?[ \t]*```/gi
+
 /** One markdown code fence (```json or a bare ```) around the whole text. */
 const FENCED = /^```[ \t]*(?:json)?[ \t]*\r?\n([\s\S]*?)\r?\n?[ \t]*```$/i
 
@@ -195,10 +280,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 +311,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 +320,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 +344,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 +387,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 +444,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 +472,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 +489,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`
@@ -22,11 +22,12 @@
 
 import type { IncomingMessage, ServerResponse } from "node:http"
 import { serveAdmin } from "../admin/route.js"
-import { DEFAULT_APP, authenticate, authenticateUsage, type PlugboardOptions } from "../config.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,
@@ -46,7 +47,7 @@ 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"
@@ -61,7 +62,7 @@ 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. */
@@ -171,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 })
 
@@ -180,6 +181,12 @@ 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)) {
@@ -266,7 +273,7 @@ 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 })
@@ -304,6 +311,7 @@ export function createOpenAiRoute(routeHost: RouteHost) {
         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,
@@ -329,6 +337,7 @@ 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 })
   }
 
@@ -387,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"
@@ -414,8 +423,9 @@ export function createOpenAiRoute(routeHost: RouteHost) {
       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, ...(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") {
+      // 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

@@ -386,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 } : {}),
   }