opencode-plugboard 0.19.0 → 0.21.0

package/src/config.ts

@@ -3,9 +3,10 @@
 import { createHash, timingSafeEqual } from "node:crypto"
 import type { CacheConfig } from "./cache.js"
 import { isPlugError, type PlugError } from "./contract.js"
-import { allowedBy, parseModelRef } from "./models.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"
@@ -21,6 +22,11 @@ export interface PlugboardOptions {
   readonly models: ReadonlyArray<string>
   /** Alias -> `provider/model[#variant]`. Targets must also pass the allowlist. */
   readonly aliases: Readonly<Record<string, string>>
+  /**
+   * Agent name -> `provider/model[#variant]` (option `agents`): each is listed as `agent/<name>` and runs its
+   * OpenCode agent's system prompt on that model. The model must pass the allowlist.
+   */
+  readonly agents: Readonly<Record<string, string>>
   /**
    * Alias -> the targets after the first, in order, for an alias written as an array. `aliases` holds the
    * first target, so everything that resolves an alias keeps working; the model caller retries the rest
@@ -58,6 +64,8 @@ export interface PlugboardOptions {
   readonly usage: UsageConfig
   /** A key that may read every app's usage on `GET /v1/usage`. Compared like app keys; must differ from every one of them. */
   readonly adminKey?: string
+  /** A template for the OpenCode session page of each request: `{id}`, and optional `{directory}` (see src/session/link.ts, #77). */
+  readonly historyUrl?: string
 }
 
 /** Option `usage` after defaults: on, and days of history kept. */
@@ -81,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. */
@@ -99,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). */
@@ -131,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,
@@ -139,12 +172,12 @@ const DEFAULTS = {
   requestTimeoutMs: 600_000,
 } as const
 
-const KNOWN = new Set(["listen", "keys", "adminKey", "apps", "models", "aliases", "maxTools", "maxN", "requestTimeoutMs", "remoteImages", "history", "dropUnsupportedParams", "logFormat", "metrics", "modelIds", "limits", "budgets", "cache", "usage"])
+const KNOWN = new Set(["listen", "keys", "adminKey", "apps", "models", "aliases", "agents", "maxTools", "maxN", "requestTimeoutMs", "remoteImages", "history", "dropUnsupportedParams", "logFormat", "metrics", "modelIds", "limits", "budgets", "cache", "usage", "historyUrl"])
 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
@@ -217,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"])
 
@@ -252,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[] }),
@@ -259,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)
 }
@@ -296,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,
   }
 }
 
@@ -396,6 +469,55 @@ function parseBudgets(raw: unknown, keys: Readonly<Record<string, string>>): Bud
   return { ...(perApp === undefined ? {} : { perApp }), ...(raw.apps === undefined ? {} : { apps }) }
 }
 
+const AGENT_KNOWN = new Set(["name", "model"])
+/** An OpenCode agent name: letters, digits, `_` and `-`, starting with a letter or digit. */
+const AGENT_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/
+
+/**
+ * Option `agents`: `{ name, model }` per OpenCode agent to expose. `model` is required and must pass the
+ * allowlist, so an agent's own configured model never runs outside `models` (the agent's model setting is
+ * not read). Names must be unique.
+ */
+function parseAgents(raw: unknown, models: ReadonlyArray<string>): Record<string, string> {
+  if (raw === undefined) return {}
+  if (!Array.isArray(raw)) throw new Error("plugboard option `agents` must be an array of { name, model } objects")
+  const entries: Array<[string, string]> = []
+  for (const item of raw) {
+    if (!isRecord(item)) throw new Error("plugboard option `agents` entries must be objects of the form { name, model }")
+    for (const key of Object.keys(item))
+      if (!AGENT_KNOWN.has(key)) throw new Error(`Unknown plugboard option \`agents.${key}\` (known: ${[...AGENT_KNOWN].join(", ")})`)
+    const { name, model } = item
+    if (typeof name !== "string" || !AGENT_NAME.test(name)) throw new Error(`plugboard agent name \`${String(name)}\` must match ${AGENT_NAME} (an OpenCode agent name)`)
+    if (entries.some(([known]) => known === name)) throw new Error(`plugboard agent \`${name}\` is listed more than once in \`agents\``)
+    if (typeof model !== "string" || !ALIAS_TARGET.test(model))
+      throw new Error(`plugboard agent \`${name}\` must set \`model\` to \`provider/model\` or \`provider/model#variant\``)
+    if (!allowedBy(models as string[], parseModelRef(model)!))
+      throw new Error(`plugboard agent \`${name}\` model \`${model}\` is not allowed by the \`models\` option`)
+    entries.push([name, model])
+  }
+  return Object.fromEntries(entries)
+}
+
+/**
+ * Option `historyUrl` (#77): an http(s) URL template that must contain `{id}`. Its only other placeholder is
+ * `{directory}`, so a typo such as `{sesion}` fails at load instead of producing a link that is wrong.
+ */
+function parseHistoryUrl(value: unknown): string | undefined {
+  if (value === undefined) return undefined
+  const at = "plugboard option `historyUrl`"
+  if (typeof value !== "string" || !value.includes("{id}")) throw new Error(`${at} must be a URL template with {id} (for example http://host:4096/session/{id})`)
+  const unknown = (value.match(/\{[^{}]*\}/g) ?? []).find((placeholder) => placeholder !== "{id}" && placeholder !== "{directory}")
+  if (unknown !== undefined) throw new Error(`${at} has the unknown placeholder ${unknown} (known: {id}, {directory})`)
+  let url: URL
+  try {
+    url = new URL(value.replaceAll("{id}", "x").replaceAll("{directory}", "x"))
+  } catch {
+    throw new Error(`${at} must be an http(s) URL template`)
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error(`${at} must be http or https`)
+  return value
+}
+
 /** Validates raw plugin options and applies defaults. Throws `Error` with an actionable message. */
 export function parseOptions(raw: unknown): PlugboardOptions {
   if (raw !== undefined && raw !== null && !isRecord(raw)) throw new Error("plugboard options must be an object")
@@ -452,6 +574,14 @@ export function parseOptions(raw: unknown): PlugboardOptions {
     const chain = Array.isArray(target) ? target : [target]
     if (chain.length === 0) throw new Error(`plugboard alias \`${alias}\` must list at least one target`)
     for (const entry of chain) {
+      // A skill target binds one model and takes no fallbacks; like a list entry it must pass the allowlist at load.
+      if (typeof entry === "string" && entry.startsWith(SKILL_PREFIX)) {
+        const parsed = parseAliasTarget(entry)
+        if (parsed?.skill === undefined) throw new Error(`plugboard alias \`${alias}\` skill target \`${entry}\` must be \`skill:<id>@provider/model\` or \`skill:<id>@provider/model#variant\``)
+        if (Array.isArray(target)) throw new Error(`plugboard alias \`${alias}\` binds a skill, so it takes one target and no list of fallbacks`)
+        if (!allowedBy(models as string[], parsed.ref)) throw new Error(`plugboard alias \`${alias}\` target \`${entry}\` is not allowed by the \`models\` option`)
+        continue
+      }
       if (typeof entry !== "string" || !ALIAS_TARGET.test(entry))
         throw new Error(`plugboard alias \`${alias}\` must target \`provider/model\` or \`provider/model#variant\` (or a list of them)`)
       // A list is new, so it is strict: a target the allowlist would refuse can never serve, so fail at load.
@@ -465,6 +595,7 @@ export function parseOptions(raw: unknown): PlugboardOptions {
   }
   const aliases: Record<string, string> = Object.fromEntries(aliasEntries)
   const fallbacks: Record<string, string[]> = Object.fromEntries(fallbackEntries)
+  const agents = parseAgents(input.agents, models as string[])
 
   const maxTools = positiveInt(input.maxTools, "maxTools", DEFAULTS.maxTools, 1024)
   const apps = parseApps(input.apps, { keys, aliases, maxTools })
@@ -493,6 +624,7 @@ export function parseOptions(raw: unknown): PlugboardOptions {
   if (budgets !== undefined && !usage.enabled) throw new Error("plugboard option `budgets` needs `usage` enabled: budgets are counted from the usage records")
   if (budgets !== undefined && usage.retentionDays < widestWindowDays(budgets))
     throw new Error(`plugboard option \`usage.retentionDays\` must be at least ${widestWindowDays(budgets)} for the budget windows in use (a month is 31 days, a week 7): older days are deleted and would stop counting`)
+  const historyUrl = parseHistoryUrl(input.historyUrl)
 
   return {
     listen: { host, port: port ?? DEFAULTS.port },
@@ -500,6 +632,7 @@ export function parseOptions(raw: unknown): PlugboardOptions {
     apps,
     models: models as string[],
     aliases,
+    agents,
     fallbacks,
     maxTools,
     maxN: positiveInt(input.maxN, "maxN", DEFAULTS.maxN, 64),
@@ -515,6 +648,7 @@ export function parseOptions(raw: unknown): PlugboardOptions {
     usage,
     ...(budgets === undefined ? {} : { budgets }),
     ...(typeof input.adminKey === "string" ? { adminKey: input.adminKey } : {}),
+    ...(historyUrl === undefined ? {} : { historyUrl }),
   }
 }
 
@@ -543,24 +677,32 @@ function digestsOf(keys: Readonly<Record<string, string>>): ReadonlyArray<readon
 /** Who may read `GET /v1/usage`: the admin key (every app), or one app (`default` when keyless). */
 export type UsageScope = { readonly admin: true } | { readonly admin: false; readonly app: string }
 
+/** The digest of a runtime key (src/keys.ts), with its app: checked like a config key (#55). */
+export type RuntimeDigest = readonly [app: string, digest: Buffer]
+
 /** The admin key is checked first; any other valid key (or keyless mode) is an app, as `authenticate` decides. */
-export function authenticateUsage(options: PlugboardOptions, authorization: string | undefined): UsageScope | PlugError {
+export function authenticateUsage(options: PlugboardOptions, authorization: string | undefined, runtime: ReadonlyArray<RuntimeDigest> = []): UsageScope | PlugError {
   const bearer = /^Bearer\s+(\S+)\s*$/i.exec(authorization ?? "")?.[1]
   if (options.adminKey !== undefined && bearer !== undefined && timingSafeEqual(sha256(bearer), sha256(options.adminKey))) return { admin: true }
-  const auth = authenticate(options, authorization)
+  const auth = authenticate(options, authorization, runtime)
   if (isPlugError(auth)) return auth
   return { admin: false, app: auth.app }
 }
 
-/** No keys -> app `default`; with keys every request needs `Authorization: Bearer <key>`. */
-export function authenticate(options: PlugboardOptions, authorization: string | undefined): { app: string } | PlugError {
+/**
+ * No config keys -> app `default` (keyless), as before. With config keys every request needs
+ * `Authorization: Bearer <key>`. A runtime key (#55) matches like a config key, so it names its app
+ * whenever it is presented. It never makes a keyless server require a key, so deleting the last
+ * runtime key cannot open or close access by itself.
+ */
+export function authenticate(options: PlugboardOptions, authorization: string | undefined, runtime: ReadonlyArray<RuntimeDigest> = []): { app: string } | PlugError {
   const entries = digestsOf(options.keys)
-  if (entries.length === 0) return { app: DEFAULT_APP }
   const token = /^Bearer\s+(\S+)\s*$/i.exec(authorization ?? "")?.[1]
-  if (!token) return UNAUTHORIZED
+  if (token === undefined) return entries.length === 0 ? { app: DEFAULT_APP } : UNAUTHORIZED
   const digest = sha256(token)
   let app: string | undefined
   // Every key is compared, no early exit.
-  for (const [name, expected] of entries) if (timingSafeEqual(digest, expected)) app = name
-  return app === undefined ? UNAUTHORIZED : { app }
+  for (const [name, expected] of [...entries, ...runtime]) if (timingSafeEqual(digest, expected)) app = name
+  if (app !== undefined) return { app }
+  return entries.length === 0 ? { app: DEFAULT_APP } : UNAUTHORIZED
 }

package/src/contract.ts

@@ -114,6 +114,8 @@ export interface PlugRequest {
   readonly tools: ReadonlyArray<PlugTool>
   readonly toolChoice?: PlugToolChoice
   readonly generation: PlugGeneration
+  /** The end user the caller named, when kept (src/user.ts, #57). Labels the session title and the usage counts. */
+  readonly user?: string
 }
 
 // ---------------------------------------------------------------- events
@@ -172,7 +174,7 @@ export interface CallContext {
   /** Aborted on client disconnect or timeout. */
   readonly signal: AbortSignal
   /** Called once, before the first event, with the id of the history record this call writes (if any). */
-  readonly onRecord?: (recordID: string) => void
+  readonly onRecord?: (recordID: string, directory?: string) => void
   /**
    * Called once, before the first event, only for a request whose model is an alias with fallbacks
    * (`src/fallback.ts`): which target answered and how many earlier targets failed first. A front-end
@@ -192,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." },
@@ -92,6 +93,14 @@ function endpoints(options: PlugboardOptions): ReadonlyArray<Endpoint> {
         ]
       : []),
     ...(options.metrics ? [{ method: "GET", path: "/metrics", auth: true, description: "Prometheus metrics." }] : []),
+    // The admin key only (option `adminKey`); without it these paths are a 404 (src/admin/route.ts).
+    ...(options.adminKey === undefined
+      ? []
+      : [
+          { method: "GET", path: "/v1/admin/keys", auth: true, description: "Admin: the config and runtime app keys, without key values." },
+          { method: "POST", path: "/v1/admin/keys", auth: true, description: "Admin: a new app key for `{ app }`, returned once." },
+          { method: "DELETE", path: "/v1/admin/keys/{keyId}", auth: true, description: "Admin: revoke a runtime app key." },
+        ]),
   ]
 }
 
@@ -276,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
@@ -284,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
@@ -303,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/fallback.ts

@@ -51,6 +51,8 @@ export const FALLBACKS_HEADER = "x-plugboard-fallbacks"
 export interface ServedInfo {
   served?: string
   fallbacks?: number
+  /** The session page link of the request (option `historyUrl`, src/session/link.ts), for the log line. */
+  sessionUrl?: string
 }
 
 /**
@@ -90,9 +92,9 @@ async function* chain(inner: ModelCaller, deps: FallbackDeps, request: PlugReque
   let attempt = 0
   for (;;) {
     // The history id of this attempt: handed on only if the attempt is the one that answers (or the last).
-    let recordID: string | undefined
+    let recorded: { id: string; directory?: string } | undefined
     const next = attempt === 0 ? request : retarget(deps.options, request, ref)
-    const iterator = inner.stream(next, { ...context, onRecord: (id) => void (recordID = id) })[Symbol.asyncIterator]()
+    const iterator = inner.stream(next, { ...context, onRecord: (id, directory) => void (recorded = { id, directory }) })[Symbol.asyncIterator]()
 
     let first: IteratorResult<PlugEvent> | undefined
     let thrown: { readonly error: unknown } | undefined
@@ -124,7 +126,7 @@ async function* chain(inner: ModelCaller, deps: FallbackDeps, request: PlugReque
     }
 
     // Answered, ran out of targets, or the request ended: this attempt's outcome is the response.
-    if (recordID !== undefined) report(context, recordID)
+    if (recorded !== undefined) report(context, recorded)
     if (thrown) throw thrown.error
     if (first!.done) return
     // An error is not an answer: a call that fails (non-retryable, or on its last target) reports no served model.
@@ -153,9 +155,9 @@ async function resolveRest(deps: FallbackDeps, request: PlugRequest, app: string
   }
 }
 
-const report = (context: CallContext, recordID: string): void => {
+const report = (context: CallContext, recorded: { readonly id: string; readonly directory?: string }): void => {
   try {
-    context.onRecord?.(recordID)
+    context.onRecord?.(recorded.id, recorded.directory)
   } catch {}
 }
 

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,12 +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"
@@ -111,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)
@@ -134,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)
@@ -157,13 +160,15 @@ export async function serveGemini(host: RouteHost, { match, request, url, app, r
     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, match.stream),
+      onServerTools: reportServerTools(response, match.stream),
       onCache: reportCache(response),
     }),
     scope,
@@ -187,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)
 }