opencode-plugboard 0.21.2 → 0.23.0

package/README.md

@@ -3,6 +3,10 @@
 [![npm](https://img.shields.io/npm/v/opencode-plugboard)](https://www.npmjs.com/package/opencode-plugboard)
 [![license](https://img.shields.io/npm/l/opencode-plugboard)](https://github.com/jjjermiah/opencode-plugboard/blob/main/LICENSE)
 [![CI](https://github.com/jjjermiah/opencode-plugboard/actions/workflows/ci.yml/badge.svg)](https://github.com/jjjermiah/opencode-plugboard/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/jjjermiah/opencode-plugboard/badge)](https://scorecard.dev/viewer/?uri=github.com/jjjermiah/opencode-plugboard)
+<!-- OpenSSF Best Practices: register at https://www.bestpractices.dev first (answers in docs/best-practices.md). Then replace <id> with the project id and uncomment the next line:
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/<id>/badge)](https://www.bestpractices.dev/projects/<id>)
+-->
 
 Plugboard is an OpenCode V2 plugin. It turns your OpenCode server into one HTTP API that OpenAI, Anthropic and Gemini compatible apps can call with their own key.
 
@@ -43,7 +47,7 @@ export PLUGBOARD_KEY_MY_APP=choose-a-long-random-string
 {
   "plugins": [
     {
-      "package": "opencode-plugboard@0.21.2",
+      "package": "opencode-plugboard@0.22.0",
       "options": {
         "keys": { "my-app": "{env:PLUGBOARD_KEY_MY_APP}" },
         "models": ["anthropic/claude-sonnet-4-6", "github-copilot/*", "opencode-go/glm-5.3-flash"],
@@ -125,7 +129,7 @@ Nothing is exposed by accident. A model is callable only if `models` lists it, a
 A model outside the list gets a 404:
 
 ```json
-{"error": {"message": "Model openai/gpt-5 is not available", "code": "model_not_found", "type": "not_found_error", "param": null}}
+{"error": {"message": "Model openai/gpt-5 is not available", "code": "model_not_found", "type": "not_found_error", "param": "model"}}
 ```
 
 #### Per-app policy
@@ -229,7 +233,7 @@ retry-after: 12
 {"error": {"message": "Too many requests per minute", "code": "rate_limit_exceeded", "type": "rate_limit_error", "param": null}}
 ```
 
-A full concurrency cap returns `too_many_requests` with `retry-after: 1`. The limits live in the server process, so a restart clears them.
+A full concurrency cap returns `too_many_requests` with `retry-after: 1`. The `code` is on the OpenAI and Gemini routes; the Anthropic `/v1/messages` error has a `type` and a `message` only (see [Anthropic Messages](https://jjjermiah.github.io/opencode-plugboard/messages)). The limits live in the server process, so a restart clears them.
 
 #### Response cache
 
@@ -390,7 +394,7 @@ A server shared by a Discord bot, n8n, Open WebUI and a coding agent, with most
 {
   "plugins": [
     {
-      "package": "opencode-plugboard@0.21.2",
+      "package": "opencode-plugboard@0.22.0",
       "options": {
         // Reachable from the LAN. Non-loopback hosts refuse to start without keys.
         "listen": { "host": "10.0.1.50", "port": 4010 },
@@ -460,6 +464,17 @@ One page per client, with the config, a chat, a tool call, structured output and
 | pydantic-ai | [pydantic-ai][client-pydantic-ai] | pass with `OpenAIChatModel` |
 | Open WebUI | [open-webui][client-open-webui] | pass over its HTTP API; no browser, no structured output in its UI |
 | n8n | [n8n][client-n8n] | pass with "Use Responses API" off |
+| Claude Code | [claude-code][client-claude-code] | pass: text and a tool turn through `/v1/messages`; needs `maxTools` above 36 |
+| Codex CLI | [codex-cli][client-codex-cli] | docs only, not run yet (Responses API) |
+| Continue | [continue][client-continue] | docs only, not run yet |
+| Kilo Code | [kilo-code][client-kilo-code] | docs only, not run yet |
+| LibreChat | [librechat][client-librechat] | docs only, not run yet |
+| Zed | [zed][client-zed] | docs only, not run yet |
+| OpenAI Agents SDK (Python) | [openai-agents][client-openai-agents] | pass on Responses and Chat Completions: text, stream, tools, structured output |
+| LiteLLM (as a client) | [litellm-client][client-litellm] | pass: text, stream, tools |
+| Instructor | [instructor][client-instructor] | pass: TOOLS, JSON_SCHEMA and partial streaming modes |
+| DSPy | [dspy][client-dspy] | pass: Predict, ChainOfThought, typed output |
+| Aider | [aider][client-aider] | pass: one scripted `--message` run |
 | Anything else | [any-app][client-any-app] | base URL, key, model id |
 
 Each run drove the client's own SDK or API against a dev server at an earlier commit: a plain chat, a tool round trip, streaming, an image and structured output on `fast`, a Claude model and a ChatGPT model. A pass is not a clean sweep, and the notes say where it was not. The latest full run is in [compat/results/release-candidate.md][release-candidate].
@@ -538,4 +553,15 @@ Not affiliated with or endorsed by OpenAI, Anthropic, Google, GitHub or Microsof
 [client-pydantic-ai]: https://jjjermiah.github.io/opencode-plugboard/clients/pydantic-ai
 [client-open-webui]: https://jjjermiah.github.io/opencode-plugboard/clients/open-webui
 [client-n8n]: https://jjjermiah.github.io/opencode-plugboard/clients/n8n
+[client-claude-code]: https://jjjermiah.github.io/opencode-plugboard/clients/claude-code
+[client-codex-cli]: https://jjjermiah.github.io/opencode-plugboard/clients/codex-cli
+[client-continue]: https://jjjermiah.github.io/opencode-plugboard/clients/continue
+[client-kilo-code]: https://jjjermiah.github.io/opencode-plugboard/clients/kilo-code
+[client-librechat]: https://jjjermiah.github.io/opencode-plugboard/clients/librechat
+[client-zed]: https://jjjermiah.github.io/opencode-plugboard/clients/zed
+[client-openai-agents]: https://jjjermiah.github.io/opencode-plugboard/clients/openai-agents
+[client-litellm]: https://jjjermiah.github.io/opencode-plugboard/clients/litellm-client
+[client-instructor]: https://jjjermiah.github.io/opencode-plugboard/clients/instructor
+[client-dspy]: https://jjjermiah.github.io/opencode-plugboard/clients/dspy
+[client-aider]: https://jjjermiah.github.io/opencode-plugboard/clients/aider
 [client-any-app]: https://jjjermiah.github.io/opencode-plugboard/clients/any-app

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-plugboard",
-  "version": "0.21.2",
+  "version": "0.23.0",
   "type": "module",
   "license": "MIT",
   "description": "Use the ChatGPT, Claude, Copilot and OpenCode Go logins in your OpenCode server from any app: an OpenCode V2 plugin serving OpenAI, Anthropic and Gemini compatible APIs.",
@@ -32,6 +32,7 @@
     "flake-hunt": "bun .github/scripts/flake-hunt.ts",
     "coverage-manifest": "bun .github/scripts/coverage-manifest.ts",
     "live-matrix": "bun test/live/matrix.ts",
+    "compat:python": "uv run --project compat/py python compat/py/clients/run_all.py",
     "build:tui": "bun .github/scripts/build-tui.ts",
     "prepack": "bun run build:tui",
     "smoke:pack": "bun .github/scripts/smoke-pack.ts",

package/src/anthropic/request.ts

@@ -9,6 +9,7 @@
  * afterwards, which is why the request omits `ref`.
  */
 import type { PlugboardOptions } from "../config.js"
+import { imageProblem } from "../image.js"
 import { bodyUserId, userField } from "../user.js"
 import {
   isPlugError,
@@ -54,7 +55,10 @@ const mediaPart = (block: JsonObject, at: string, what: "image" | "document"): P
   if (source.type === "base64") {
     if (typeof source.media_type !== "string" || !MEDIA_TYPE.test(source.media_type)) return bad(`${at}.source.media_type: must be a media type such as image/png`)
     if (typeof source.data !== "string") return bad(`${at}.source.data: must be a base64 string`)
-    return { type: "media", url: `data:${source.media_type};base64,${source.data}`, mediaType: source.media_type }
+    const url = `data:${source.media_type};base64,${source.data}`
+    const problem = what === "image" ? imageProblem(url) : undefined
+    if (problem) return bad(`${at}.source.data: ${problem}`)
+    return { type: "media", url, mediaType: source.media_type }
   }
   if (source.type === "url") {
     if (typeof source.url !== "string" || source.url.length === 0) return bad(`${at}.source.url: must be a non-empty string`)

package/src/anthropic/route.ts

@@ -12,7 +12,7 @@
  */
 
 import type { IncomingMessage, ServerResponse } from "node:http"
-import { authenticate, bodyLimits } from "../config.js"
+import { authenticate, bodyLimits, historyTemplate } from "../config.js"
 import { liveOptions } from "../runtime.js"
 import { bodyUserId, noteEndUser } from "../user.js"
 import { isPlugError, type PlugError, type PlugRequest } from "../contract.js"
@@ -138,7 +138,7 @@ export async function serveMessages(host: RouteHost, call: MessagesCall): Promis
         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)
+          setSessionLink(response, info, historyTemplate(host.options, auth.app), recordID, directory)
         },
         onServed: reportServed(response, info, (served) => void (exchange.model = served.model)),
         onPolicy: reportPolicy(response),

package/src/completions/request.ts

@@ -59,6 +59,7 @@ export function parseCompletionsRequest(body: unknown, options: PlugboardOptions
   if (!isRecord(body)) return bad("Request body must be a JSON object")
   if (typeof body.model !== "string" || body.model.length === 0) return bad("model is required", "model")
   if (body.prompt == null) return bad("prompt is required", "prompt")
+  if (body.stream != null && typeof body.stream !== "boolean") return bad("stream must be a boolean", "stream")
 
   if (body.logprobs != null) return unsupported("logprobs is not supported", "logprobs")
   if (body.best_of != null) {

package/src/completions/response.ts

@@ -90,7 +90,7 @@ async function settle(events: AsyncIterable<PlugEvent>, exchange: CompletionsExc
   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)
+    if (fallback === undefined) return structuredMissing()
     return { text: fallback, reason: finish, usage, fallback: true }
   }
   if (finish === "stop") text = stripStopTail(text, exchange.stop ?? []).text

package/src/config.ts

@@ -68,6 +68,16 @@ export interface PlugboardOptions {
   readonly historyUrl?: string
 }
 
+/**
+ * The session link template that applies to `app` (#280): its own `apps.<name>.historyUrl` when set, `undefined`
+ * when that is `false`, else the global `historyUrl`. Routes call this with the authenticated app.
+ */
+export function historyTemplate(options: Pick<PlugboardOptions, "apps" | "historyUrl">, app: string): string | undefined {
+  const own = appPolicy(options, app)?.historyUrl
+  if (own === false) return undefined
+  return own ?? options.historyUrl
+}
+
 /** Option `usage` after defaults: on, and days of history kept. */
 export interface UsageConfig {
   readonly enabled: boolean
@@ -96,6 +106,11 @@ export interface AppPolicy {
   readonly serverTools?: ReadonlyArray<string>
   /** Server-tool steps one request may run before the turn is stopped (option `maxServerToolSteps`). */
   readonly maxServerToolSteps?: number
+  /**
+   * This app's session link template (option `apps.<name>.historyUrl`), or `false` for none. Absent: the global
+   * `historyUrl`. Look the effective template up with `historyTemplate`.
+   */
+  readonly historyUrl?: string | false
 }
 
 /** One set of caps. A field that is not set is unlimited. */
@@ -250,7 +265,7 @@ function mergedKeys(keys: unknown, apps: unknown): Array<[string, unknown]> {
   return [...merged]
 }
 
-const APP_KNOWN = new Set(["key", "models", "system", "systemMode", "tools", "maxTools", "serverTools", "maxServerToolSteps"])
+const APP_KNOWN = new Set(["key", "models", "system", "systemMode", "tools", "maxTools", "serverTools", "maxServerToolSteps", "historyUrl"])
 const SERVER_TOOL_PATTERN = /^[A-Za-z0-9_.:-]+$/
 const MAX_SERVER_TOOLS = 32
 const MAX_SERVER_TOOL_STEPS = 100
@@ -311,6 +326,8 @@ function parseApps(
     const maxServerToolSteps =
       value.maxServerToolSteps === undefined ? undefined : positiveInt(value.maxServerToolSteps, `apps.${app}.maxServerToolSteps`, DEFAULT_SERVER_TOOL_STEPS, MAX_SERVER_TOOL_STEPS)
 
+    // `false` turns the link off for this app; a string is its own template (validated like the global one).
+    const historyUrl = value.historyUrl === false ? false : parseHistoryUrl(value.historyUrl, `plugboard option \`apps.${app}.historyUrl\``)
     const policy: AppPolicy = {
       ...(value.models === undefined ? {} : { models: value.models as string[] }),
       ...(value.system === undefined ? {} : { system: value.system as string }),
@@ -319,9 +336,10 @@ function parseApps(
       ...(maxTools === undefined ? {} : { maxTools }),
       ...(serverTools === undefined ? {} : { serverTools }),
       ...(maxServerToolSteps === undefined ? {} : { maxServerToolSteps }),
+      ...(historyUrl === undefined ? {} : { historyUrl }),
     }
     // 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 || serverTools !== undefined)
+    if (value.models !== undefined || value.system !== undefined || value.tools !== undefined || maxTools !== undefined || serverTools !== undefined || historyUrl !== undefined)
       entries.push([app, policy])
   }
   return Object.fromEntries(entries)
@@ -502,9 +520,8 @@ function parseAgents(raw: unknown, models: ReadonlyArray<string>): Record<string
  * 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 {
+function parseHistoryUrl(value: unknown, at = "plugboard option `historyUrl`"): 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})`)

package/src/contract.ts

@@ -176,10 +176,9 @@ export interface CallContext {
   /** Called once, before the first event, with the id of the history record this call writes (if any). */
   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
-   * uses it for `x-plugboard-model` and the `model` it echoes. A call that fails on every target never
-   * reports it.
+   * Called once, before the first event, for every answered call (`src/fallback.ts`): which target answered
+   * and how many earlier targets failed first. A front-end uses it for `x-plugboard-model`, and the `model`
+   * it echoes when `chain` is set. A call that fails never reports it.
    */
   readonly onServed?: (served: ServedModel) => void
   /** Called once, before the first event, with each change the app's policy made that the caller sent for. Front-ends report them in the `x-plugboard-policy` header. */
@@ -210,10 +209,14 @@ export interface CallTotals {
   readonly costUsd?: number
 }
 
-/** The target of an alias that answered: `provider/model[#variant]`, and the targets tried before it. */
+/**
+ * The target that answered: `provider/model[#variant]`, and the targets tried before it. `chain` is set
+ * when the request named a list alias, the only case where the response body echoes the target.
+ */
 export interface ServedModel {
   readonly model: string
   readonly fallbacks: number
+  readonly chain?: boolean
 }
 
 /** The seam between the core and a backend (the session backend now, `ctx.llm.stream` possibly later). */

package/src/fallback.ts

@@ -56,10 +56,11 @@ export interface ServedInfo {
 }
 
 /**
- * The `CallContext.onServed` of a route: `x-plugboard-model` (and `x-plugboard-fallbacks` when targets
- * failed first) while the headers are still open, and the log fields. The first call wins, so several
- * choices of one request report the first answer. `then` runs for that first call (a single-call route
- * echoes the served model in the body there).
+ * The `CallContext.onServed` of a route: `x-plugboard-model` on every answer (alias or canonical id), and
+ * `x-plugboard-fallbacks` when targets failed first, while the headers are still open, plus the log fields.
+ * The first call wins, so several choices of one request report the first answer. `then` runs only for a
+ * list alias (`served.chain`): a single-call route echoes the target in the body for those, and keeps the
+ * model the caller sent for every other request.
  */
 export function reportServed(response: ServerResponse, info: ServedInfo, then?: (served: ServedModel) => void): (served: ServedModel) => void {
   return (served) => {
@@ -70,7 +71,7 @@ export function reportServed(response: ServerResponse, info: ServedInfo, then?:
       response.setHeader(MODEL_HEADER, served.model)
       if (served.fallbacks > 0) response.setHeader(FALLBACKS_HEADER, String(served.fallbacks))
     }
-    then?.(served)
+    if (served.chain) then?.(served)
   }
 }
 
@@ -80,12 +81,27 @@ export const isRetryable = (error: PlugError): boolean => error.code !== undefin
 export function withFallbacks(inner: ModelCaller, deps: FallbackDeps): ModelCaller {
   return {
     stream(request, context) {
-      if (!Object.hasOwn(deps.options.fallbacks, request.model)) return inner.stream(request, context)
+      if (!Object.hasOwn(deps.options.fallbacks, request.model)) return reportPlain(inner.stream(request, context), context, request.ref)
       return chain(inner, deps, request, context)
     },
   }
 }
 
+/**
+ * A call that is not a list alias: no retry, but the answer still names its model (`x-plugboard-model`, #279).
+ * Reported before the first non-error event, so a failed call reports nothing, as in `chain`.
+ */
+async function* reportPlain(events: AsyncIterable<PlugEvent>, context: CallContext, ref: ModelRef): AsyncGenerator<PlugEvent> {
+  let reported = false
+  for await (const event of events) {
+    if (!reported && event.type !== "error") {
+      reported = true
+      context.onServed?.({ model: refToString(ref), fallbacks: 0 })
+    }
+    yield event
+  }
+}
+
 async function* chain(inner: ModelCaller, deps: FallbackDeps, request: PlugRequest, context: CallContext): AsyncGenerator<PlugEvent> {
   let rest: ModelRef[] | undefined
   let ref = request.ref
@@ -130,7 +146,7 @@ async function* chain(inner: ModelCaller, deps: FallbackDeps, request: PlugReque
     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.
-    if (reason === undefined && first!.value.type !== "error") context.onServed?.({ model: refToString(ref), fallbacks: attempt })
+    if (reason === undefined && first!.value.type !== "error") context.onServed?.({ model: refToString(ref), fallbacks: attempt, chain: true })
     try {
       yield first!.value
       for (let step = await iterator.next(); !step.done; step = await iterator.next()) yield step.value

package/src/gemini/request.ts

@@ -13,6 +13,7 @@
  * API also accepts.
  */
 import type { PlugboardOptions } from "../config.js"
+import { imageProblem } from "../image.js"
 import {
   isPlugError,
   type PlugError,
@@ -212,7 +213,10 @@ const parseContents = (raw: unknown): PlugMessage[] | PlugError => {
         if (role === "model") return unsupported("inlineData is not supported in a model turn", `${at}.inlineData`)
         if (!isRecord(inline) || typeof inline.data !== "string" || typeof inline.mimeType !== "string")
           return bad("inlineData needs mimeType and base64 data", `${at}.inlineData`)
-        parts.push({ type: "media", url: dataUrl(inline.mimeType, inline.data), mediaType: inline.mimeType })
+        const url = dataUrl(inline.mimeType, inline.data)
+        const problem = inline.mimeType.toLowerCase().startsWith("image/") ? imageProblem(url) : undefined
+        if (problem) return bad(problem, `${at}.inlineData`, "invalid_image")
+        parts.push({ type: "media", url, mediaType: inline.mimeType })
       } else if (file !== undefined) {
         if (role === "model") return unsupported("fileData is not supported in a model turn", `${at}.fileData`)
         const uri = isRecord(file) ? field(file, "fileUri") : undefined

package/src/gemini/response.ts

@@ -227,7 +227,7 @@ export async function runGenerate(events: AsyncIterable<PlugEvent>, exchange: Ge
 
   const passthrough = exchange.callerTools === true && calls > 0
   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)
+  const missing = passthrough || answered || fallback !== undefined || exchange.structuredTool === undefined ? undefined : structuredMissing()
   failure ??= finish ? missing : noFinish()
   if (failure) return { failure, started }
   flush()

package/src/gemini/route.ts

@@ -17,7 +17,7 @@
 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 { bodyLimits, historyTemplate } 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"
@@ -163,7 +163,7 @@ export async function serveGemini(host: RouteHost, { match, request, url, app, r
       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)
+        setSessionLink(response, info, historyTemplate(host.options, app), recordID, directory)
       },
       onServed: reportServed(response, info, (served) => void (exchange.model = served.model)),
       onPolicy: reportPolicy(response),

package/src/image.ts

@@ -0,0 +1,49 @@
+/**
+ * The check every image part of a request gets in its decoder (#286), so a caller's bad image is a 400
+ * before any session, preparation or budget work. Only `data:` URLs are checked here: a `data:` image must
+ * carry an `image/*` media type, well-formed base64, and bytes that start with a PNG, JPEG, GIF or WebP
+ * signature (the formats the providers take). Any other URL is not checked here; remote images are checked
+ * when they are fetched (src/session/media.ts).
+ *
+ * Pure: no node imports. `Buffer` is the global, and only the first 12 decoded bytes are read.
+ */
+
+const DATA_URL = /^data:([^,]*);base64,(.*)$/s
+const BASE64 = /^[A-Za-z0-9+/]*={0,2}$/
+
+/** The image signatures plugboard accepts, checked on the first bytes of the decoded data. */
+const SIGNATURES: ReadonlyArray<(head: Buffer) => boolean> = [
+  (head) => head[0] === 0x89 && head[1] === 0x50 && head[2] === 0x4e && head[3] === 0x47,
+  (head) => head[0] === 0xff && head[1] === 0xd8 && head[2] === 0xff,
+  (head) => head.subarray(0, 4).toString("latin1") === "GIF8",
+  (head) => head.subarray(0, 4).toString("latin1") === "RIFF" && head.subarray(8, 12).toString("latin1") === "WEBP",
+]
+
+/**
+ * The message for a file part (`file_data`, Chat Completions or Responses `input_file`) that cannot be sent (#288).
+ * Only a PDF given as a `data:application/pdf;base64,` URL is accepted: the compatibility matrix sends one on
+ * OpenAI Chat. A bare base64 string has no media type, and any other type is refused here instead of failing
+ * later in backend preparation.
+ */
+export function pdfProblem(url: string): string | undefined {
+  const match = /^data:application\/pdf;base64,(.*)$/is.exec(url)
+  if (!match) return "File data must be a PDF data URL (data:application/pdf;base64,...); other file types are not supported"
+  const data = match[1]!
+  if (data.length === 0 || !BASE64.test(data) || data.length % 4 === 1) return "File data is not valid base64"
+  return Buffer.from(data.slice(0, 8), "base64").subarray(0, 4).toString("latin1") === "%PDF" ? undefined : "File data is not a PDF"
+}
+
+/** The message for a `data:` image URL that cannot be sent to a provider, or undefined when it can (or is not a data URL). */
+export function imageProblem(url: string): string | undefined {
+  if (!url.startsWith("data:")) return undefined
+  const match = DATA_URL.exec(url)
+  if (!match) return "Image data URL must be base64 encoded, for example data:image/png;base64,..."
+  const mediaType = match[1]!.split(";")[0]!.trim().toLowerCase()
+  if (!mediaType.startsWith("image/")) return "Image data URL must have an image/* media type"
+  const data = match[2]!
+  if (data.length === 0) return "Image data URL has no data"
+  if (!BASE64.test(data) || data.length % 4 === 1) return "Image data URL is not valid base64"
+  // 16 base64 characters decode to the 12 bytes the signatures need.
+  const head = Buffer.from(data.slice(0, 16), "base64")
+  return SIGNATURES.some((matches) => matches(head)) ? undefined : "Image data URL is not a PNG, JPEG, GIF or WebP image"
+}

package/src/openai/fanout.ts

@@ -26,6 +26,7 @@ import { reportServed, type ServedInfo } from "../fallback.js"
 import { reportCache } from "../cache.js"
 import { reportPolicy, reportServerTools } from "../policy.js"
 import { reportUsage } from "../usage-header.js"
+import { historyTemplate } from "../config.js"
 import { SESSION_URL_HEADER, sessionUrl } from "../session/link.js"
 import { RequestAborted, boundEvents, sendError, sendJson, sseWriter, type RequestScope } from "../http.js"
 import {
@@ -198,8 +199,9 @@ export async function serveChoices(host: Pick<RouteHost, "caller" | "options">,
           if (response.headersSent || response.destroyed || !/^[\x21-\x7e]+$/.test(recordID)) return
           records[index] = recordID
           response.setHeader(SESSION_HEADER, records.filter((id) => id !== undefined).join(","))
-          if (host.options.historyUrl !== undefined) {
-            links[index] = sessionUrl(host.options.historyUrl, recordID, directory)
+          const template = historyTemplate(host.options, app)
+          if (template !== undefined) {
+            links[index] = sessionUrl(template, recordID, directory)
             info.sessionUrl = links.filter((link) => link !== undefined).join(",")
             response.setHeader(SESSION_URL_HEADER, info.sessionUrl)
           }

package/src/openai/request.ts

@@ -6,6 +6,7 @@
  * the request omits `ref`.
  */
 import type { PlugboardOptions } from "../config.js"
+import { imageProblem, pdfProblem } from "../image.js"
 import { bodyUser, userField } from "../user.js"
 import {
   isPlugError,
@@ -80,10 +81,13 @@ const userParts = (content: unknown, param: string): PlugPart[] | PlugError => {
     if (item.type === "text" && typeof item.text === "string") parts.push({ type: "text", text: item.text })
     else if (item.type === "image_url" && isRecord(item.image_url) && typeof item.image_url.url === "string") {
       const url = item.image_url.url
+      const problem = imageProblem(url)
+      if (problem) return bad(problem, `${at}.image_url.url`, "invalid_image")
       parts.push({ type: "media", url, ...(dataUrlType(url) ? { mediaType: dataUrlType(url) } : {}) })
     } else if (item.type === "file" && isRecord(item.file) && typeof item.file.file_data === "string") {
-      const data = item.file.file_data
-      const url = data.startsWith("data:") ? data : `data:application/octet-stream;base64,${data}`
+      const url = item.file.file_data
+      const problem = pdfProblem(url)
+      if (problem) return bad(problem, `${at}.file.file_data`, "invalid_file")
       parts.push({ type: "media", url, mediaType: dataUrlType(url) })
     } else return bad(`Unsupported content part type "${String(item.type)}"`, `${at}.type`, "unsupported_parameter")
   }
@@ -279,6 +283,7 @@ export function parseChatRequest(body: unknown, options: PlugboardOptions): Pars
   // Parameters the session backend cannot honour are rejected, not ignored.
   const n = parseChoiceCount(body, options)
   if (typeof n === "object") return n
+  if (body.stream != null && typeof body.stream !== "boolean") return bad("stream must be a boolean", "stream")
   if (body.logprobs === true) return bad("logprobs is not supported", "logprobs", "unsupported_parameter")
   if (body.top_logprobs != null) return bad("top_logprobs is not supported", "top_logprobs", "unsupported_parameter")
 

package/src/openai/response.ts

@@ -166,12 +166,15 @@ 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 => ({
+/**
+ * The 502 for a structured turn that ended without its answer (no forced-tool call, and no text that is the
+ * schema's JSON). Shared by every front-end. The message names no internal tool: the caller never sees one (#282).
+ */
+export const structuredMissing = (): PlugError => ({
   status: 502,
   kind: "server",
   code: "structured_output_missing",
-  message: `The model finished without calling the \`${tool}\` tool, so there is no structured output`,
+  message: "The model did not return JSON matching the response schema. Say the expected JSON, with its keys and types, in the prompt.",
 })
 
 /**
@@ -186,7 +189,7 @@ const structured = {
   content: (call: ToolCall) => args(call.input),
   /** The failure for a finished structured exchange, if any. */
   failure: (exchange: OpenAiExchange, answered: boolean): PlugError | undefined =>
-    exchange.structuredTool === undefined || answered ? undefined : structuredMissing(exchange.structuredTool),
+    exchange.structuredTool === undefined || answered ? undefined : structuredMissing(),
 }
 
 const isObjectValue = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value)

package/src/openai/route.ts

@@ -22,7 +22,7 @@
 
 import type { IncomingMessage, ServerResponse } from "node:http"
 import { serveAdmin } from "../admin/route.js"
-import { DEFAULT_APP, authenticate, authenticateUsage, bodyLimits, type PlugboardOptions } from "../config.js"
+import { DEFAULT_APP, authenticate, authenticateUsage, bodyLimits, historyTemplate, type PlugboardOptions } from "../config.js"
 import { isPlugError, type CatalogModel, type ModelCaller, type PlugError, type PlugRequest } from "../contract.js"
 import { buildDiscovery, buildStatus, readiness, renderDiscoveryHtml, sendText } from "../discovery.js"
 import {
@@ -209,6 +209,15 @@ export function createOpenAiRoute(routeHost: RouteHost) {
     // Usage has its own credentials: the admin key reads every app, any other key only its own app (`authenticateUsage`).
     if (route === "GET /v1/usage" && host.usage) return serveUsage(request, response, url, host.usage, info)
 
+    // `/metrics` with `adminKey` set: the admin key alone (#285). Its series name every app, so an app key may not read them.
+    // Without `adminKey` it keeps the `/v1` authentication, and any app key sees every app's series (documented).
+    if (route === "GET /metrics" && metrics && host.options.adminKey !== undefined) {
+      const who = authenticateUsage(liveOptions(host.options), request.headers.authorization, await runtimeDigests())
+      if (isPlugError(who)) return fail(response, who)
+      if (!who.admin) return fail(response, { status: 403, kind: "permission", code: "admin_key_required", message: "Metrics need the admin key (option `adminKey`)" })
+      return sendText(response, 200, metrics.contentType, await metrics.render(runtimeStatus()))
+    }
+
     // Runtime app keys (#55): the admin routes answer the admin key only, and are a 404 without `adminKey`.
     if (path === "/v1/admin/keys" || path.startsWith("/v1/admin/keys/"))
       return serveAdmin({ options: liveOptions(host.options), keys: host.keys }, { path, request, response, scope, info })
@@ -305,7 +314,7 @@ export function createOpenAiRoute(routeHost: RouteHost) {
         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)
+          setSessionLink(response, info, historyTemplate(host.options, auth.app), recordID, directory)
         },
         // An alias with fallbacks: report which target answered, and echo it as the response model.
         onServed: reportServed(response, info, (served) => void (exchange.model = served.model)),

package/src/responses/request.ts

@@ -10,6 +10,7 @@
  * `ModelRef` afterwards, which is why the request omits `ref`.
  */
 import type { PlugboardOptions } from "../config.js"
+import { imageProblem, pdfProblem } from "../image.js"
 import { bodyUser, userField } from "../user.js"
 import {
   isPlugError,
@@ -88,12 +89,16 @@ const userParts = (content: unknown, param: string): PlugPart[] | PlugError => {
       const url = typeof item.image_url === "string" ? item.image_url : isRecord(item.image_url) ? item.image_url.url : undefined
       if (typeof url !== "string")
         return unsupported(item.file_id != null ? "input_image.file_id is not supported (stateless); send image_url" : "input_image needs an image_url", `${at}.image_url`)
+      const problem = imageProblem(url)
+      if (problem) return bad(problem, `${at}.image_url`, "invalid_image")
       parts.push({ type: "media", url, ...(dataUrlType(url) ? { mediaType: dataUrlType(url) } : {}) })
     } else if (item.type === "input_file") {
       if (typeof item.file_data === "string") {
         const data = item.file_data
         const filename = typeof item.filename === "string" ? item.filename.toLowerCase() : ""
         const url = data.startsWith("data:") ? data : `data:${filename.endsWith(".pdf") ? "application/pdf" : "application/octet-stream"};base64,${data}`
+        const problem = pdfProblem(url)
+        if (problem) return bad(problem, `${at}.file_data`, "invalid_file")
         parts.push({ type: "media", url, mediaType: dataUrlType(url) })
       } else if (typeof item.file_url === "string") {
         parts.push({ type: "media", url: item.file_url })
@@ -246,6 +251,13 @@ const parseTools = (raw: unknown): PlugTool[] | PlugError => {
   return tools
 }
 
+/**
+ * A caller's tool as echoed on the response object. A function tool always carries `strict` (#289, the OpenAI
+ * FunctionTool schema requires it): the caller's boolean, or false when it was absent or null. Other entries are
+ * echoed as sent.
+ */
+const echoTool = (tool: unknown): unknown => (isRecord(tool) && tool.type === "function" ? { ...tool, strict: tool.strict === true } : tool)
+
 const parseToolChoice = (raw: unknown): PlugToolChoice | undefined | PlugError => {
   if (raw == null) return undefined
   if (raw === "auto" || raw === "none" || raw === "required") return raw
@@ -319,6 +331,7 @@ export function parseResponsesRequest(body: unknown, options: PlugboardOptions,
   if (refused) return refused
   if (body.instructions != null && typeof body.instructions !== "string") return bad("instructions must be a string", "instructions")
   if (body.reasoning != null && !isRecord(body.reasoning)) return bad("reasoning must be an object", "reasoning")
+  if (body.stream != null && typeof body.stream !== "boolean") return bad("stream must be a boolean", "stream")
 
   const parsed = parseInput(body.input, resolve)
   if (isPlugError(parsed)) return parsed
@@ -381,7 +394,7 @@ export function parseResponsesRequest(body: unknown, options: PlugboardOptions,
         temperature: generation.temperature ?? null,
         text: { format: isRecord(text?.format) ? text.format : { type: "text" } },
         tool_choice: body.tool_choice ?? "auto",
-        tools: Array.isArray(body.tools) ? body.tools : [],
+        tools: Array.isArray(body.tools) ? body.tools.map(echoTool) : [],
         top_p: generation.topP ?? null,
         truncation: "disabled",
         user: typeof body.user === "string" ? body.user : null,

package/src/responses/response.ts

@@ -201,7 +201,7 @@ export async function runResponse(
   const passthrough = exchange.callerTools === true && calls > 0
   const structuredAnswer = exchange.structuredTool !== undefined && !passthrough
   const fallback = structuredAnswer && !answered && exchange.structuredSchema !== undefined ? textFallback(collected, exchange.structuredSchema) : undefined
-  const missing = passthrough || answered || fallback !== undefined || exchange.structuredTool === undefined ? undefined : structuredMissing(exchange.structuredTool)
+  const missing = passthrough || answered || fallback !== undefined || exchange.structuredTool === undefined ? undefined : structuredMissing()
   failure ??= finish ? missing : noFinish()
   if (failure) {
     if (!started && !committed()) return { failure, started }

package/src/responses/route.ts

@@ -10,6 +10,7 @@
 
 import type { ServerResponse } from "node:http"
 import { isPlugError, type PlugError, type PlugRequest } from "../contract.js"
+import { historyTemplate } from "../config.js"
 import { reportServed, type ServedInfo } from "../fallback.js"
 import { boundEvents, sendError, sendJson, sseWriter, type RequestScope } from "../http.js"
 import { resolveModel } from "../models.js"
@@ -55,7 +56,7 @@ export async function serveResponses(host: RouteHost, { app, body, response, sco
       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)
+        setSessionLink(response, info, historyTemplate(host.options, app), recordID, directory)
       },
       onServed: reportServed(response, info, (served) => void (exchange.model = served.model)),
       onPolicy: reportPolicy(response),

package/src/session/caller.ts

@@ -68,7 +68,9 @@ const countMedia = (request: PlugRequest): number =>
 function checkPreparation(request: PlugRequest, images: number, maxTools: number): PlugError | undefined {
   const wanted = countMedia(request)
   if (images !== wanted) {
-    return { status: 500, kind: "server", code: "backend_preparation_failed", message: `Prepared ${images} attachment(s) for a request with ${wanted}` }
+    // The counts are for the log only; the caller gets the generic message (#288).
+    log("request.preparation_failed", { images, wanted })
+    return { status: 500, kind: "server", code: "backend_preparation_failed", message: "Could not prepare the model request" }
   }
   const tools = seedToolsFor(request).length
   if (tools > maxTools) {

package/src/session/context.ts

@@ -10,6 +10,7 @@
 import { Effect } from "effect"
 import { appPolicy, type AppPolicy, type PlugboardOptions } from "../config.js"
 import type { PlugError, PlugMessage, PlugRequest } from "../contract.js"
+import { log } from "../log.js"
 import type { ContextHookEvent, HostContext, HostPart, HostToolDescriptor } from "./host.js"
 import { SEED_PREFIX, SEED_RESULT, seedToolsFor } from "./seeds.js"
 import { FAILURE_EVENT, type SessionStore } from "./state.js"
@@ -108,7 +109,8 @@ function systemFor(caller: ReadonlyArray<string>, policy: AppPolicy | undefined)
   }
 }
 
-const preparationFailed = (message: string): PlugError => ({ status: 500, kind: "server", code: "backend_preparation_failed", message })
+/** The one 500 message for a request plugboard could not prepare. What was missing is logged, never sent: it names host internals (#288). */
+const preparationFailed = (): PlugError => ({ status: 500, kind: "server", code: "backend_preparation_failed", message: "Could not prepare the model request" })
 
 /**
  * `session.hook("context")` body: swap the request session's system, messages, tools and
@@ -151,11 +153,8 @@ function applyContext(event: unknown, sessions: SessionStore, apps: PlugboardOpt
   // The caller validates both before dispatch; this only fires if the host disagrees. The request is
   // already rewritten (no real tool can run); fail it instead of answering from a truncated prompt.
   if (missingMedia > 0 || missingTools > 0) {
-    const detail = [missingMedia > 0 ? `${missingMedia} attachment(s) not delivered by the host` : "", missingTools > 0 ? `${missingTools} tool(s) without a seed tool` : ""]
-    state.collector.push({
-      type: FAILURE_EVENT,
-      error: preparationFailed(`Could not prepare the model request: ${detail.filter(Boolean).join(", ")}`),
-    })
+    log("request.preparation_failed", { missing_media: missingMedia, missing_tools: missingTools })
+    state.collector.push({ type: FAILURE_EVENT, error: preparationFailed() })
   }
 }