opencode-plugboard 0.20.0 → 0.21.1

package/src/anthropic/route.ts

@@ -12,12 +12,13 @@
  */
 
 import type { IncomingMessage, ServerResponse } from "node:http"
-import { authenticate } from "../config.js"
+import { authenticate, bodyLimits } from "../config.js"
 import { liveOptions } from "../runtime.js"
 import { bodyUserId, noteEndUser } from "../user.js"
 import { isPlugError, type PlugError, type PlugRequest } from "../contract.js"
 import {
   BodyError,
+  bodyPlugError,
   RequestAborted,
   boundEvents,
   checkJsonContentType,
@@ -31,7 +32,7 @@ import {
 import { reportServed, type ServedInfo } from "../fallback.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 { setSessionLink } from "../session/link.js"
 import { dropRejected } from "../openai/sampling.js"
@@ -85,7 +86,7 @@ export async function serveMessages(host: RouteHost, call: MessagesCall): Promis
     // Answer in this route's error shape, then rethrow: the shared handler logs the outcome and
     // finds the response already sent.
     if (!response.headersSent) {
-      if (caught instanceof BodyError) fail({ status: caught.status, kind: "invalid_request", message: caught.message }, caught.status === 413)
+      if (caught instanceof BodyError) fail(bodyPlugError(caught), caught.status !== 400)
       else if (caught instanceof RequestAborted) {
         if (caught.kind === "timeout") fail(scope.timeoutError, true)
       } else fail({ status: 500, kind: "server", message: "Internal server error" })
@@ -105,7 +106,7 @@ export async function serveMessages(host: RouteHost, call: MessagesCall): Promis
     const unsupported = checkJsonContentType(request)
     if (unsupported) return fail(unsupported)
 
-    const body = await readJsonBody(request, scope.signal)
+    const body = await readJsonBody(request, scope.signal, bodyLimits(host.options))
     noteEndUser(response, info, bodyUserId(body))
     // count_tokens takes the message body without max_tokens; the parser needs one, so a placeholder stands in
     // (the count never uses it). A max_tokens the client did send is still validated.
@@ -142,6 +143,7 @@ export async function serveMessages(host: RouteHost, call: MessagesCall): Promis
         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,

package/src/cache.ts

@@ -118,18 +118,22 @@ function append(events: PlugEvent[], event: { readonly type: "text-delta" | "rea
   else events.push({ type: event.type, text: event.text })
 }
 
-/** Wraps `inner`: hits are replayed, misses stream through and are stored when they qualify. */
+/**
+ * Wraps `inner`: hits are replayed, misses stream through and are stored when they qualify. `bypass(model, app)`
+ * decides per call that the cache is not used: a persona model, or an app whose answers depend on live OpenCode
+ * tool output (`serverTools`, #82). Both conditions live in the one predicate the runtime passes.
+ */
 export function cachedCaller(
   inner: ModelCaller,
   config: CacheConfig,
   store: CacheStore,
   count?: CacheCounter,
-  bypass?: (model: string) => boolean,
+  bypass?: (model: string, app: string) => boolean,
 ): ModelCaller {
   const apps = config.apps ? new Set(config.apps) : undefined
   return {
     async *stream(request: PlugRequest, context: CallContext): AsyncIterable<PlugEvent> {
-      if (context.noCache || bypass?.(request.model) || (apps && !apps.has(context.app))) return yield* inner.stream(request, context)
+      if (context.noCache || bypass?.(request.model, context.app) || (apps && !apps.has(context.app))) return yield* inner.stream(request, context)
       const key = cacheKey(context.app, request)
       const hit = store.get(key)
       if (hit) {
@@ -161,9 +165,16 @@ export function cachedCaller(
       }
       const recorded: PlugEvent[] = []
       let storable = true
+      // Text bytes seen so far. An answer over `maxBytes` could never be stored, so capture stops there and frees what it kept (#153).
+      let captured = 0
       for await (const event of inner.stream(request, forward)) {
-        if (event.type === "text-delta" || event.type === "reasoning-delta") append(recorded, event)
-        else if (event.type === "finish") {
+        if (event.type === "text-delta" || event.type === "reasoning-delta") {
+          captured += Buffer.byteLength(event.text)
+          if (captured > config.maxBytes) {
+            storable = false
+            recorded.length = 0
+          } else if (storable) append(recorded, event)
+        } else if (event.type === "finish") {
           // Stored before the event is handed on, so a consumer that stops reading at `finish` still fills the cache.
           if (storable && CACHEABLE_FINISH.has(event.reason) && recorded.length > 0 && !context.signal.aborted)
             store.set(key, { events: [...recorded, { type: "finish", reason: event.reason }], ...(served ? { served } : {}), ...(policy?.length ? { policy } : {}) })

package/src/completions/request.ts

@@ -9,9 +9,9 @@
  * `ref`.
  */
 import type { PlugboardOptions } from "../config.js"
-import { isPlugError, type PlugError, type PlugRequest } from "../contract.js"
+import { isPlugError, type PlugError, type PlugRequest, type PlugToolChoice } from "../contract.js"
 import { bodyUser, userField } from "../user.js"
-import { parseChoiceCount, parseGeneration } from "../openai/request.js"
+import { RESPOND_TOOL, parseChoiceCount, parseGeneration, parseResponseFormat } from "../openai/request.js"
 import type { CompletionsExchange } from "./response.js"
 
 export interface ParsedCompletions {
@@ -80,16 +80,23 @@ export function parseCompletionsRequest(body: unknown, options: PlugboardOptions
     )
   const generation = parseGeneration(body)
   if (isPlugError(generation)) return generation
+  // The same response_format as Chat Completions: json_schema is the forced `respond` tool, json_object an instruction.
+  const format = parseResponseFormat(body.response_format)
+  if (isPlugError(format)) return format
 
   const suffix = typeof body.suffix === "string" && body.suffix.length > 0 ? body.suffix : undefined
+  const system = [...(suffix ? [SUFFIX_INSTRUCTION(suffix)] : []), ...(format.instruction ? [format.instruction] : [])]
+  const tools = format.structured ? [format.structured] : []
+  const toolChoice: PlugToolChoice | undefined = format.structured ? { type: "tool", name: RESPOND_TOOL } : undefined
   const streamOptions = isRecord(body.stream_options) ? body.stream_options : {}
   return {
     requests: prompts.map((prompt) => ({
       model: body.model as string,
       ...userField(bodyUser(body)),
-      system: suffix ? [SUFFIX_INSTRUCTION(suffix)] : [],
+      system,
       messages: [{ role: "user", content: [{ type: "text", text: prompt }] }],
-      tools: [],
+      tools,
+      ...(toolChoice ? { toolChoice } : {}),
       generation,
     })),
     n,
@@ -100,6 +107,8 @@ export function parseCompletionsRequest(body: unknown, options: PlugboardOptions
       perPrompt: n,
       ...(body.echo === true ? { echo: prompts } : {}),
       ...(generation.stop ? { stop: generation.stop } : {}),
+      ...(format.structured ? { structuredTool: RESPOND_TOOL, structuredSchema: format.structured.parameters } : {}),
+      ...(format.instruction ? { jsonObject: true } : {}),
     },
     ...(typeof body.reasoning_effort === "string" ? { reasoningEffort: body.reasoning_effort } : {}),
   }

package/src/completions/response.ts

@@ -5,9 +5,9 @@
  * Reasoning deltas and tool calls are dropped: the legacy format has neither, and the request
  * offers no tools. `logprobs` is always null.
  */
-import type { PlugError, PlugEvent, PlugFinish, PlugUsage } from "../contract.js"
+import { isPlugError, type PlugError, type PlugEvent, type PlugFinish, type PlugUsage } from "../contract.js"
 import type { ChoiceCodec } from "../openai/fanout.js"
-import { encodeError, type StreamChoice, type StreamResult } from "../openai/response.js"
+import { args, encodeError, structuredMissing, textFallback, unfence, type CollectedChoice, type StreamChoice, type StreamResult } from "../openai/response.js"
 import { StopHoldback, stripStopTail } from "../stop.js"
 
 /** What the encoders need besides the model events; the request decoder produces it, the model call never sees it. */
@@ -23,6 +23,12 @@ export interface CompletionsExchange {
   readonly echo?: ReadonlyArray<string>
   /** The request's `stop`. A plain stop whose text ends with one of these leaves the sequence out (src/stop.ts). */
   readonly stop?: ReadonlyArray<string>
+  /** `response_format: json_schema`: the name of the forced tool whose input is the answer (`respond`). The answer is its arguments as text. */
+  readonly structuredTool?: string
+  /** The caller's `json_schema`: a text answer is taken when the model skipped the call and its text is that JSON (`textFallback`). */
+  readonly structuredSchema?: Readonly<Record<string, unknown>>
+  /** `response_format: json_object`: a single markdown fence around the answer is stripped (`unfence`). */
+  readonly jsonObject?: boolean
 }
 
 const FINISH_REASONS: Record<Exclude<PlugFinish, "error">, string> = {
@@ -46,15 +52,31 @@ const encodeUsage = (usage: PlugUsage) => {
 
 const prefixOf = (exchange: CompletionsExchange, index: number) => exchange.echo?.[Math.floor(index / exchange.perPrompt)] ?? ""
 
-/** One choice as a complete body: `choices[0]` carries the text, `usage` the totals. */
-async function collectText(events: AsyncIterable<PlugEvent>, exchange: CompletionsExchange, index: number): Promise<{ status: number; body: object; retryAfterSeconds?: number }> {
+/** A choice's settled answer: its text, the finish reason and the usage. */
+interface Settled {
+  readonly text: string
+  readonly reason: Exclude<PlugFinish, "error">
+  readonly usage?: PlugUsage
+  /** The structured answer came from the text (see `textFallback`), not the respond call. */
+  readonly fallback?: boolean
+}
+
+/**
+ * Reads one whole choice. A structured answer is the arguments of the `respond` call (the text is
+ * ignored); a json_object answer loses one code fence. Without the call a structured choice fails,
+ * as in Chat Completions (`structuredMissing`).
+ */
+async function settle(events: AsyncIterable<PlugEvent>, exchange: CompletionsExchange): Promise<Settled | PlugError> {
   let text = ""
+  let answer: string | undefined
   let finish: Exclude<PlugFinish, "error"> | undefined
   let usage: PlugUsage | undefined
   let failure: PlugError | undefined
   for await (const event of events) {
     if (event.type === "text-delta") text += event.text
-    else if (event.type === "finish") {
+    else if (event.type === "tool-call") {
+      if (exchange.structuredTool !== undefined && event.name === exchange.structuredTool) answer ??= args(event.input)
+    } else if (event.type === "finish") {
       usage = event.usage ?? usage
       if (event.reason === "error") failure ??= failedRun()
       else finish = event.reason
@@ -64,20 +86,31 @@ async function collectText(events: AsyncIterable<PlugEvent>, exchange: Completio
     }
   }
   if (!failure && !finish) failure = noFinish()
-  if (failure || !finish) {
-    const error = failure ?? noFinish()
-    return { status: error.status, body: encodeError(error), retryAfterSeconds: error.retryAfterSeconds }
+  if (failure || !finish) return failure ?? noFinish()
+  if (exchange.structuredTool !== undefined) {
+    if (answer !== undefined) return { text: answer, reason: finish, usage }
+    const fallback = exchange.structuredSchema === undefined ? undefined : textFallback(text, exchange.structuredSchema)
+    if (fallback === undefined) return structuredMissing(exchange.structuredTool)
+    return { text: fallback, reason: finish, usage, fallback: true }
   }
   if (finish === "stop") text = stripStopTail(text, exchange.stop ?? []).text
+  return { text: exchange.jsonObject ? unfence(text) : text, reason: finish, usage }
+}
+
+/** One choice as a complete body: `choices[0]` carries the text, `usage` the totals. */
+async function collectText(events: AsyncIterable<PlugEvent>, exchange: CompletionsExchange, index: number): Promise<CollectedChoice> {
+  const settled = await settle(events, exchange)
+  if (isPlugError(settled)) return { status: settled.status, body: encodeError(settled), retryAfterSeconds: settled.retryAfterSeconds }
   return {
+    ...(settled.fallback ? { structuredFallback: true } : {}),
     status: 200,
     body: {
       id: `cmpl-${crypto.randomUUID().replaceAll("-", "").slice(0, 29)}`,
       object: "text_completion",
       created: now(),
       model: exchange.model,
-      choices: [{ text: prefixOf(exchange, index) + text, index: 0, logprobs: null, finish_reason: FINISH_REASONS[finish] }],
-      ...(usage ? { usage: encodeUsage(usage) } : {}),
+      choices: [{ text: prefixOf(exchange, index) + settled.text, index: 0, logprobs: null, finish_reason: FINISH_REASONS[settled.reason] }],
+      ...(settled.usage ? { usage: encodeUsage(settled.usage) } : {}),
     },
   }
 }
@@ -110,6 +143,15 @@ async function streamText(
     const prefix = prefixOf(exchange, choice.index)
     if (prefix.length > 0) chunk(prefix)
   }
+  if (exchange.structuredTool !== undefined || exchange.jsonObject) {
+    // A structured or json_object answer is only known at the end (the call, the fence), so it is written as one chunk.
+    const settled = await settle(events, exchange)
+    if (isPlugError(settled)) return { failure: settled, started: false }
+    start()
+    if (settled.text.length > 0) chunk(settled.text)
+    chunk("", FINISH_REASONS[settled.reason])
+    return { started, ...(settled.usage ? { usage: settled.usage } : {}) }
+  }
   // A stop sequence is held back until the finish decides it (src/stop.ts).
   const holdback = new StopHoldback(exchange.stop ?? [])
   let finish: Exclude<PlugFinish, "error"> | undefined

package/src/config.ts

@@ -6,6 +6,7 @@ import { isPlugError, type PlugError } from "./contract.js"
 import { allowedBy, parseAliasTarget, parseModelRef, SKILL_PREFIX } from "./models.js"
 import { parseAllowEntry, type RemoteImages } from "./session/media.js"
 import type { HistoryLimits } from "./session/prune.js"
+import { SEED_PREFIX } from "./session/seeds.js"
 
 /** How `/v1/models` spells a model id: the canonical `provider/model#variant`, a UI-safe slug, or both. Resolution accepts either. */
 export type ModelIds = "canonical" | "slugs" | "both"
@@ -88,6 +89,13 @@ export interface AppPolicy {
   readonly tools: boolean
   /** Lowers the global `maxTools` for this app. */
   readonly maxTools?: number
+  /**
+   * Exact OpenCode tool ids this app's sessions may run themselves (option `apps.<name>.serverTools`).
+   * Absent: none, the session denies every real tool. Trusted apps only, see docs/configuration.md.
+   */
+  readonly serverTools?: ReadonlyArray<string>
+  /** Server-tool steps one request may run before the turn is stopped (option `maxServerToolSteps`). */
+  readonly maxServerToolSteps?: number
 }
 
 /** One set of caps. A field that is not set is unlimited. */
@@ -106,8 +114,24 @@ export interface Limits {
   readonly maxConcurrent?: number
   readonly perApp?: LimitCaps
   readonly apps?: Readonly<Record<string, LimitCaps>>
+  /**
+   * Bytes of request bodies buffered at once, across every request in the process (`readJsonBody` in
+   * `src/http.ts`). A body that would go over it is refused with 503 `server_busy` before it is read. Not per app.
+   */
+  readonly maxBodyBytesInFlight?: number
+  /** Milliseconds a request body may take to arrive in full; a slower one is refused with 408. */
+  readonly bodyReadTimeoutMs?: number
 }
 
+/** The bounds `readJsonBody` applies before it buffers a request body (see `bodyLimits`). */
+export interface BodyLimits {
+  readonly maxBytesInFlight: number
+  readonly readTimeoutMs: number
+}
+
+/** Defaults of `limits.maxBodyBytesInFlight` (128 MiB) and `limits.bodyReadTimeoutMs` (30 s). */
+export const BODY_LIMIT_DEFAULTS: BodyLimits = { maxBytesInFlight: 128 * 1024 * 1024, readTimeoutMs: 30_000 }
+
 /** What a budget counts: HTTP requests on the model routes (refusals by `limits` or budgets left out), tokens, or cost in USD. */
 export type BudgetMetric = "requests" | "tokens" | "costUsd"
 /** The windows a budget resets on: a UTC calendar day, an ISO week (Monday start) or a calendar month (UTC). */
@@ -138,6 +162,8 @@ export interface Budgets {
 
 export const APP_NAME_PATTERN = /^[a-z0-9-]+$/
 export const DEFAULT_APP = "default"
+/** Server-tool steps per request when `maxServerToolSteps` is not set. */
+export const DEFAULT_SERVER_TOOL_STEPS = 8
 const DEFAULTS = {
   host: "127.0.0.1",
   port: 4010,
@@ -151,7 +177,7 @@ const USAGE_KNOWN = new Set(["enabled", "retentionDays"])
 const USAGE_DEFAULTS = { enabled: true, retentionDays: 90 } as const
 /** Ten years: keeps a day-keyed store bounded and a range query well inside its limits. */
 const MAX_RETENTION_DAYS = 3650
-const LIMITS_KNOWN = new Set(["maxConcurrent", "perApp", "apps"])
+const LIMITS_KNOWN = new Set(["maxConcurrent", "perApp", "apps", "maxBodyBytesInFlight", "bodyReadTimeoutMs"])
 const LIMIT_CAP_KNOWN = new Set(["maxConcurrent", "requestsPerMinute"])
 /** Largest cap accepted: far above any provider's limit, and keeps the error messages short. */
 const MAX_LIMIT = 1_000_000
@@ -224,7 +250,26 @@ function mergedKeys(keys: unknown, apps: unknown): Array<[string, unknown]> {
   return [...merged]
 }
 
-const APP_KNOWN = new Set(["key", "models", "system", "systemMode", "tools", "maxTools"])
+const APP_KNOWN = new Set(["key", "models", "system", "systemMode", "tools", "maxTools", "serverTools", "maxServerToolSteps"])
+const SERVER_TOOL_PATTERN = /^[A-Za-z0-9_.:-]+$/
+const MAX_SERVER_TOOLS = 32
+const MAX_SERVER_TOOL_STEPS = 100
+
+/** `apps.<name>.serverTools`: exact OpenCode tool ids. No wildcards, no duplicates, and not the seeds or CodeMode's `execute`. */
+function parseServerTools(value: unknown, at: string): string[] {
+  if (!Array.isArray(value) || value.length === 0 || value.length > MAX_SERVER_TOOLS)
+    throw new Error(`${at}.serverTools must be an array of 1 to ${MAX_SERVER_TOOLS} OpenCode tool ids`)
+  const tools: string[] = []
+  for (const tool of value) {
+    if (typeof tool !== "string" || !SERVER_TOOL_PATTERN.test(tool))
+      throw new Error(`${at}.serverTools entry \`${String(tool)}\` must be an exact OpenCode tool id (letters, digits, \`_\`, \`.\`, \`:\`, \`-\`; no wildcards)`)
+    if (tool === "execute") throw new Error(`${at}.serverTools cannot name \`execute\`: it is OpenCode's CodeMode tool and would run every tool it wraps`)
+    if (tool.startsWith(SEED_PREFIX)) throw new Error(`${at}.serverTools cannot name \`${tool}\`: plugboard's own seed tools are reserved`)
+    if (tools.includes(tool)) throw new Error(`${at}.serverTools lists \`${tool}\` twice`)
+    tools.push(tool)
+  }
+  return tools
+}
 const SYSTEM_MODES: ReadonlySet<string> = new Set(["prepend", "append", "replace"])
 const MODEL_IDS: ReadonlySet<string> = new Set(["canonical", "slugs", "both"])
 
@@ -259,6 +304,12 @@ function parseApps(
     if (value.systemMode !== undefined && value.system === undefined) throw new Error(`${at}.systemMode needs \`system\``)
     if (value.tools !== undefined && typeof value.tools !== "boolean") throw new Error(`${at}.tools must be a boolean`)
     const maxTools = value.maxTools === undefined ? undefined : positiveInt(value.maxTools, `apps.${app}.maxTools`, 0, context.maxTools)
+    if (value.serverTools !== undefined && app === DEFAULT_APP)
+      throw new Error(`${at}.serverTools needs a key: the keyless app cannot run OpenCode tools; name the app and give it a key`)
+    const serverTools = value.serverTools === undefined ? undefined : parseServerTools(value.serverTools, at)
+    if (value.maxServerToolSteps !== undefined && serverTools === undefined) throw new Error(`${at}.maxServerToolSteps needs \`serverTools\``)
+    const maxServerToolSteps =
+      value.maxServerToolSteps === undefined ? undefined : positiveInt(value.maxServerToolSteps, `apps.${app}.maxServerToolSteps`, DEFAULT_SERVER_TOOL_STEPS, MAX_SERVER_TOOL_STEPS)
 
     const policy: AppPolicy = {
       ...(value.models === undefined ? {} : { models: value.models as string[] }),
@@ -266,9 +317,12 @@ function parseApps(
       systemMode: (value.systemMode as SystemMode | undefined) ?? "prepend",
       tools: value.tools !== false,
       ...(maxTools === undefined ? {} : { maxTools }),
+      ...(serverTools === undefined ? {} : { serverTools }),
+      ...(maxServerToolSteps === undefined ? {} : { maxServerToolSteps }),
     }
     // An app that only carries a key has no policy to look up.
-    if (value.models !== undefined || value.system !== undefined || value.tools !== undefined || maxTools !== undefined) entries.push([app, policy])
+    if (value.models !== undefined || value.system !== undefined || value.tools !== undefined || maxTools !== undefined || serverTools !== undefined)
+      entries.push([app, policy])
   }
   return Object.fromEntries(entries)
 }
@@ -303,6 +357,18 @@ function parseLimits(raw: unknown, keys: Readonly<Record<string, string>>): Limi
     ...(raw.maxConcurrent === undefined ? {} : { maxConcurrent: positiveInt(raw.maxConcurrent, "limits.maxConcurrent", 0, MAX_LIMIT) }),
     ...(raw.perApp === undefined ? {} : { perApp: parseCaps(raw.perApp, "limits.perApp") }),
     ...(appsRaw === undefined ? {} : { apps }),
+    ...(raw.maxBodyBytesInFlight === undefined
+      ? {}
+      : { maxBodyBytesInFlight: positiveInt(raw.maxBodyBytesInFlight, "limits.maxBodyBytesInFlight", 0, Number.MAX_SAFE_INTEGER) }),
+    ...(raw.bodyReadTimeoutMs === undefined ? {} : { bodyReadTimeoutMs: positiveInt(raw.bodyReadTimeoutMs, "limits.bodyReadTimeoutMs", 0, MAX_TIMER_MS) }),
+  }
+}
+
+/** The body limits in force for these options (`limits.maxBodyBytesInFlight`, `limits.bodyReadTimeoutMs`), or the defaults. */
+export function bodyLimits(options: Pick<PlugboardOptions, "limits">): BodyLimits {
+  return {
+    maxBytesInFlight: options.limits?.maxBodyBytesInFlight ?? BODY_LIMIT_DEFAULTS.maxBytesInFlight,
+    readTimeoutMs: options.limits?.bodyReadTimeoutMs ?? BODY_LIMIT_DEFAULTS.readTimeoutMs,
   }
 }
 

package/src/contract.ts

@@ -194,6 +194,12 @@ export interface CallContext {
    * headers are open, so a stream (headers sent first) never gets it.
    */
   readonly onUsage?: (totals: CallTotals) => void
+  /**
+   * Called once when the call ends, only if OpenCode ran server tools for it (option `apps.<name>.serverTools`),
+   * with how many. Front-ends set `x-plugboard-server-tools` from it while the headers are open, so a stream
+   * (headers sent first) never gets it, and a choice of `n` adds to the count of the others.
+   */
+  readonly onServerTools?: (count: number) => void
 }
 
 /** One answered call's totals for the caller: `inputTokens` and `outputTokens` as the response body reports them (cache reads inside input, reasoning inside output), and `costUsd` when the model has a price. */

package/src/discovery.ts

@@ -67,6 +67,7 @@ export const ENDPOINTS: ReadonlyArray<Endpoint> = [
   { method: "GET", path: "/", auth: false, description: "This page." },
   { method: "GET", path: "/v1", auth: false, description: "This page as JSON." },
   { method: "GET", path: "/healthz", auth: false, description: "Liveness: {\"ok\":true}." },
+  { method: "GET", path: "/readyz", auth: false, description: "Readiness: {\"ready\":true}, or 503 {\"ready\":false,\"reason\"} until the backend can serve." },
   { method: "GET", path: "/v1/models", auth: true, description: "Models this app may call (OpenAI shape)." },
   { method: "GET", path: "/v1/models/{id}", auth: true, description: "One model." },
   { method: "POST", path: "/v1/chat/completions", auth: true, description: "OpenAI Chat Completions." },
@@ -284,6 +285,29 @@ ${sections.join("\n")}
 `
 }
 
+/** The facts `/readyz` decides from (`RuntimeStatus` in src/runtime.ts). */
+export interface ReadinessFacts {
+  readonly generations: number
+  readonly servingConfirmed: boolean
+  readonly pumpRunning: boolean
+  readonly catalogLoaded: boolean
+  readonly configError?: { readonly message: string }
+}
+
+/**
+ * `GET /readyz` (#160): whether the backend can serve a request. The reason names the first piece
+ * that is missing, in the order a person fixes them. A recorded options error comes first and is
+ * its own message (#159); nothing else from the config is shown.
+ */
+export function readiness(facts: ReadinessFacts): { ready: true } | { ready: false; reason: string } {
+  if (facts.configError) return { ready: false, reason: facts.configError.message }
+  if (facts.generations === 0) return { ready: false, reason: "no plugboard generation is live; the server is reloading or the plugin is not loaded" }
+  if (!facts.servingConfirmed) return { ready: false, reason: "no app directory has been used since start; one model request to an app confirms it" }
+  if (!facts.pumpRunning) return { ready: false, reason: "the event pump is not running; the next request to an app starts it" }
+  if (!facts.catalogLoaded) return { ready: false, reason: "the model catalog has not loaded yet" }
+  return { ready: true }
+}
+
 /** `GET /v1/status`: authenticated runtime facts. `models` is absent when the catalog could not be loaded. */
 export function buildStatus(input: {
   readonly options: PlugboardOptions
@@ -292,6 +316,7 @@ export function buildStatus(input: {
     readonly runtimeVersion: number
     readonly listener?: { readonly host: string; readonly port: number; readonly bound: boolean }
     readonly servingConfirmed: boolean
+    readonly configError?: { readonly message: string; readonly at: number }
   }
   readonly catalog?: ReadonlyArray<CatalogModel>
   readonly now?: number
@@ -311,5 +336,7 @@ export function buildStatus(input: {
     sessionGuards: runtime.guards,
     models: catalog ? { catalog: catalog.length, available: listAvailableModels(options, catalog, app).length } : { error: "catalog_unavailable" },
     metrics: options.metrics,
+    // The plugin options error the last Location to load the plugin hit (#159); absent when options parse.
+    ...(runtime.configError ? { configError: { message: runtime.configError.message, at: new Date(runtime.configError.at).toISOString() } } : {}),
   }
 }

package/src/gemini/request.ts

@@ -351,7 +351,7 @@ const parseGeneration = (config: JsonObject): PlugGeneration | PlugError => {
 }
 
 /** `responseMimeType` / `responseSchema` / `responseJsonSchema`: same outcomes as `response_format` in the other front-ends. */
-const parseResponseFormat = (config: JsonObject): { structured?: PlugTool; wrap?: boolean; instruction?: string } | PlugError => {
+const parseResponseFormat = (config: JsonObject): { structured?: PlugTool; schema?: JsonObject; wrap?: boolean; instruction?: string } | PlugError => {
   const mime = field(config, "responseMimeType")
   const schema = field(config, "responseJsonSchema") ?? field(config, "responseSchema")
   if (mime != null && typeof mime !== "string") return bad("responseMimeType must be a string", "generationConfig.responseMimeType")
@@ -364,6 +364,7 @@ const parseResponseFormat = (config: JsonObject): { structured?: PlugTool; wrap?
   const wrap = converted.type !== undefined && converted.type !== "object"
   return {
     wrap,
+    schema: converted,
     structured: {
       name: RESPOND_TOOL,
       description: "Give your final answer by calling this tool with JSON matching its schema.",
@@ -437,7 +438,7 @@ export function parseGeminiRequest(model: string, stream: boolean, body: unknown
     exchange: {
       model,
       stream,
-      ...(respond ? { structuredTool: RESPOND_TOOL, ...(format.wrap ? { wrapped: true } : {}), ...(withCallerTools ? { callerTools: true } : {}) } : {}),
+      ...(respond ? { structuredTool: RESPOND_TOOL, ...(format.schema ? { structuredSchema: format.schema } : {}), ...(format.wrap ? { wrapped: true } : {}), ...(withCallerTools ? { callerTools: true } : {}) } : {}),
       ...(format.instruction ? { jsonObject: true } : {}),
       ...(generation.stop ? { stop: generation.stop } : {}),
     },

package/src/gemini/response.ts

@@ -8,7 +8,7 @@
  */
 import type { PlugError, PlugErrorKind, PlugEvent, PlugFinish, PlugUsage } from "../contract.js"
 import type { ListedModel } from "../models.js"
-import { unfence } from "../openai/response.js"
+import { structuredMissing, textFallback, unfence } from "../openai/response.js"
 import { StopHoldback } from "../stop.js"
 import { WRAP_KEY } from "./request.js"
 
@@ -33,6 +33,8 @@ export interface GeminiExchange {
   readonly jsonObject?: boolean
   /** The request's `generationConfig.stopSequences`. A plain stop whose text ends with one of these leaves the sequence out (src/stop.ts). Not applied to structured output. */
   readonly stop?: ReadonlyArray<string>
+  /** The caller's schema as sent (converted): a text answer is taken when the model skipped the call (`textFallback`, #173). */
+  readonly structuredSchema?: Readonly<Record<string, unknown>>
 }
 
 /** How an exchange ended. Nothing was emitted when `failure` is set and `started` is false: the caller answers with a real HTTP error. */
@@ -42,6 +44,8 @@ export interface GenerateRun {
   readonly started: boolean
   /** The aggregated response (non-streaming body). Absent on failure. */
   readonly response?: object
+  /** The structured answer came from the final text, not the respond call (`textFallback`). */
+  readonly structuredFallback?: boolean
 }
 
 type Part = Record<string, unknown>
@@ -121,20 +125,6 @@ const structuredText = (exchange: GeminiExchange, call: ToolCall): string => {
   return typeof input === "string" && !exchange.wrapped ? input : JSON.stringify(input ?? {})
 }
 
-/**
- * Structured-output projection, as in the other front-ends: the text is exactly the first
- * `respond` call; prose and other calls are suppressed. Without an answer the exchange fails,
- * except when the model stopped for `length` or `content-filter`.
- */
-const structuredFailure = (exchange: GeminiExchange, 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`,
-      }
 
 export async function runGenerate(events: AsyncIterable<PlugEvent>, exchange: GeminiExchange, emit: (chunk: object) => void): Promise<GenerateRun> {
   const responseId = crypto.randomUUID().replaceAll("-", "").slice(0, 22)
@@ -145,11 +135,15 @@ export async function runGenerate(events: AsyncIterable<PlugEvent>, exchange: Ge
     responseId,
   })
 
+  // Only a non-streamed body needs the aggregated parts: a stream is already on the wire, so nothing grows (#153).
+  const aggregate = !exchange.stream
   /** The aggregated parts: adjacent text merges into one part. */
   const parts: Part[] = []
   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
@@ -158,9 +152,11 @@ export async function runGenerate(events: AsyncIterable<PlugEvent>, exchange: Ge
 
   const push = (part: Part) => {
     started = true
-    const last = parts.at(-1)
-    if (typeof part.text === "string" && last && typeof last.text === "string") last.text += part.text
-    else parts.push(part)
+    if (aggregate) {
+      const last = parts.at(-1)
+      if (typeof part.text === "string" && last && typeof last.text === "string") last.text += part.text
+      else parts.push(part)
+    }
     emit(envelope([part]))
   }
   // A stop sequence is held back until the finish decides it (src/stop.ts). Structured output has none.
@@ -212,6 +208,7 @@ export async function runGenerate(events: AsyncIterable<PlugEvent>, exchange: Ge
         }
         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) {
@@ -229,7 +226,9 @@ export async function runGenerate(events: AsyncIterable<PlugEvent>, exchange: Ge
   }
 
   const passthrough = exchange.callerTools === true && calls > 0
-  failure ??= finish ? (passthrough ? undefined : structuredFailure(exchange, finish, answered)) : noFinish()
+  const fallback = exchange.structuredTool !== undefined && !passthrough && !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) return { failure, started }
   flush()
   if (holdback) {
@@ -237,12 +236,13 @@ export async function runGenerate(events: AsyncIterable<PlugEvent>, exchange: Ge
     if (rest.length > 0) push({ text: rest })
   }
   if (held && !passthrough) text(structuredText(exchange, held))
+  if (fallback !== undefined) text(fallback)
   const candidate = { finishReason: FINISH_REASONS[finish!] }
   const extra = usage ? { usageMetadata: encodeUsage(usage) } : {}
   // The last chunk carries the finish reason and usage, with an empty text part as Google's does.
   emit(envelope([{ text: "" }], extra, candidate))
   started = true
-  return { started, response: envelope(parts.length > 0 ? parts : [{ text: "" }], extra, candidate) }
+  return { started, response: envelope(parts.length > 0 ? parts : [{ text: "" }], extra, candidate), ...(fallback !== undefined ? { structuredFallback: true } : {}) }
 }
 
 /** SSE frame of one stream chunk (`alt=sse`): `data: <json>`, no event name and no `[DONE]`. */

package/src/gemini/route.ts

@@ -17,13 +17,15 @@
 import type { IncomingMessage, ServerResponse } from "node:http"
 import { isPlugError, type PlugError, type PlugRequest } from "../contract.js"
 import { reportServed, type ServedInfo } from "../fallback.js"
+import { bodyLimits } from "../config.js"
 import { boundEvents, checkJsonContentType, readJsonBody, sendError, sendJson, sseWriter, type RequestScope } from "../http.js"
 import { listAvailableModels, 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 { setSessionLink } from "../session/link.js"
 import type { RouteHost } from "../openai/route.js"
+import { STRUCTURED_FALLBACK_HEADER } from "../openai/response.js"
 import { dropRejected } from "../openai/sampling.js"
 import { estimateTokens } from "../anthropic/tokens.js"
 import { parseGeminiRequest } from "./request.js"
@@ -112,7 +114,7 @@ export async function serveGemini(host: RouteHost, { match, request, url, app, r
   if (match.op === "count") {
     const unsupported = checkJsonContentType(request)
     if (unsupported) return fail(unsupported)
-    const parsed = parseGeminiRequest(match.model, false, countBody(await readJsonBody(request, scope.signal)), host.options)
+    const parsed = parseGeminiRequest(match.model, false, countBody(await readJsonBody(request, scope.signal, bodyLimits(host.options))), host.options)
     if (isPlugError(parsed)) return fail(parsed)
     const catalog = await scope.race(host.loadCatalog())
     const ref = resolveModel(host.options, match.model, catalog, parsed.reasoningEffort)
@@ -135,7 +137,7 @@ export async function serveGemini(host: RouteHost, { match, request, url, app, r
     return fail({ status: 400, kind: "invalid_request", code: "unsupported_parameter", param: "alt", message: "streamGenerateContent needs the query parameter alt=sse" })
   const unsupported = checkJsonContentType(request)
   if (unsupported) return fail(unsupported)
-  const body = await readJsonBody(request, scope.signal)
+  const body = await readJsonBody(request, scope.signal, bodyLimits(host.options))
 
   const parsed = parseGeminiRequest(match.model, match.stream, body, host.options)
   if (isPlugError(parsed)) return fail(parsed)
@@ -166,6 +168,7 @@ export async function serveGemini(host: RouteHost, { match, request, url, app, r
       onServed: reportServed(response, info, (served) => void (exchange.model = served.model)),
       onPolicy: reportPolicy(response),
       onUsage: reportUsage(response, match.stream),
+      onServerTools: reportServerTools(response, match.stream),
       onCache: reportCache(response),
     }),
     scope,
@@ -189,5 +192,6 @@ export async function serveGemini(host: RouteHost, { match, request, url, app, r
 
   const run = await runGenerate(events, exchange, () => {})
   if (run.failure || !run.response) return fail(run.failure ?? { status: 502, kind: "server", message: "No response from the model" })
+  if (run.structuredFallback) response.setHeader(STRUCTURED_FALLBACK_HEADER, "text")
   sendJson(response, 200, run.response)
 }