opencode-plugboard 0.0.0-stage → 0.3.0

package/src/openai/route.ts

@@ -0,0 +1,216 @@
+/**
+ * OpenAI front-end route table: `GET /healthz`, `GET /v1/models`, `GET /v1/models/{id}`,
+ * `POST /v1/chat/completions`, and the dispatch of `POST /v1/responses` to `src/responses/route.ts`.
+ *
+ * The flow is: establish cancellation and the deadline, check origin, authenticate, parse, resolve
+ * the model, call the ModelCaller, encode. Parsing, policy and encoding are imported directly;
+ * only effects (the model caller, the catalog and the serving generation's options) arrive
+ * through `RouteHost`.
+ *
+ * Response header `x-plugboard-session: <id>` carries the id of the history record the call
+ * writes (the `ModelCaller` reports it through `CallContext.onRecord`). It is set before the
+ * response headers go out (JSON body or first SSE chunk); an id reported after that is ignored.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http"
+import { authenticate, type PlugboardOptions } from "../config.js"
+import { isPlugError, type CatalogModel, type ModelCaller, type PlugError, type PlugRequest } from "../contract.js"
+import {
+  BodyError,
+  RequestAborted,
+  beginRequest,
+  boundEvents,
+  checkJsonContentType,
+  checkOrigin,
+  finishRequest,
+  readJsonBody,
+  sendJson,
+  sseWriter,
+  type RequestScope,
+} from "../http.js"
+import { errorMessage, log, logError } from "../log.js"
+import { listAvailableModels, resolveModel } from "../models.js"
+import { serveResponses } from "../responses/route.js"
+import { parseChatRequest } from "./request.js"
+import { collectCompletion, encodeError, encodeModelList, streamCompletion } from "./response.js"
+
+/** What the serving generation supplies per request. */
+export interface RouteHost {
+  readonly options: PlugboardOptions
+  readonly caller: ModelCaller
+  /** The serving Location's enabled models. */
+  loadCatalog(): Promise<ReadonlyArray<CatalogModel>>
+}
+
+const SESSION_HEADER = "x-plugboard-session"
+const MODEL_PREFIX = "/v1/models/"
+const KNOWN_ROUTES = ["GET /v1/models", "POST /v1/chat/completions", "POST /v1/responses"]
+
+const decodeSegment = (raw: string): string => {
+  try {
+    return decodeURIComponent(raw)
+  } catch {
+    return raw
+  }
+}
+
+/** What a request log line may carry: ids and outcomes only. */
+interface RequestInfo {
+  route: string
+  app?: string
+  model?: string
+  /** Set when a response committed as 200 and then failed (a stream error frame): the log outcome and the error code. */
+  failed?: string
+}
+
+export function createOpenAiRoute(host: RouteHost) {
+  const fail = (response: ServerResponse, error: PlugError, close = false) =>
+    sendJson(response, error.status, encodeError(error), { close })
+
+  /** The route proper. Throws `BodyError`, `RequestAborted` or an unexpected error; `handle` maps them. */
+  async function serve(request: IncomingMessage, response: ServerResponse, scope: RequestScope, info: RequestInfo): Promise<void> {
+    let url: URL
+    try {
+      url = new URL(request.url ?? "/", "http://127.0.0.1")
+    } catch {
+      return fail(response, { status: 400, kind: "invalid_request", code: "invalid_request_target", message: "Malformed request target" })
+    }
+    const path = url.pathname
+    const modelId = request.method === "GET" && path.startsWith(MODEL_PREFIX) && path.length > MODEL_PREFIX.length ? decodeSegment(path.slice(MODEL_PREFIX.length)) : undefined
+    const route = `${request.method} ${modelId !== undefined ? "/v1/models/{id}" : path}`
+    // Arbitrary client paths stay out of the log.
+    info.route = modelId !== undefined || KNOWN_ROUTES.includes(route) || route === "GET /healthz" ? route : "unknown"
+
+    const rejected = checkOrigin(request, host.options)
+    if (rejected) return fail(response, rejected)
+
+    if (route === "GET /healthz") return sendJson(response, 200, { ok: true })
+
+    if (modelId === undefined && !KNOWN_ROUTES.includes(route)) {
+      return fail(response, {
+        status: 404,
+        kind: "not_found",
+        code: "not_found",
+        message: `No route for ${request.method} ${path}`,
+      })
+    }
+
+    const auth = authenticate(host.options, request.headers.authorization)
+    if (isPlugError(auth)) return fail(response, auth)
+    info.app = auth.app
+
+    if (route === "GET /v1/models" || modelId !== undefined) {
+      const listed = listAvailableModels(host.options, await scope.race(host.loadCatalog()))
+      if (modelId === undefined) return sendJson(response, 200, encodeModelList(listed))
+      const item = listed.find((m) => m.id === modelId)
+      if (!item) {
+        return fail(response, {
+          status: 404,
+          kind: "not_found",
+          code: "model_not_found",
+          param: "model",
+          message: `Model ${modelId} is not available`,
+        })
+      }
+      info.model = item.id
+      return sendJson(response, 200, (encodeModelList([item]) as { data: object[] }).data[0])
+    }
+
+    const unsupported = checkJsonContentType(request)
+    if (unsupported) return fail(response, unsupported)
+
+    const body = await readJsonBody(request, scope.signal)
+    if (route === "POST /v1/responses") return serveResponses(host, { app: auth.app, body, response, scope, info })
+    const parsed = parseChatRequest(body, host.options)
+    if (isPlugError(parsed)) return fail(response, parsed)
+    const catalog = await scope.race(host.loadCatalog())
+    const ref = resolveModel(host.options, parsed.request.model, catalog, parsed.reasoningEffort)
+    if (isPlugError(ref)) return fail(response, ref)
+    info.model = `${ref.providerID}/${ref.id}${ref.variant ? `#${ref.variant}` : ""}`
+    const call: PlugRequest = { ...parsed.request, ref }
+    const { exchange } = parsed
+
+    // Abandoned requests (client gone, deadline passed) must never reach the model caller.
+    if (scope.signal.aborted) throw scope.signal.reason
+    const events = boundEvents(
+      host.caller.stream(call, {
+        app: auth.app,
+        signal: scope.signal,
+        onRecord: (recordID) => {
+          if (response.headersSent || response.destroyed || !/^[\x21-\x7e]+$/.test(recordID)) return
+          response.setHeader(SESSION_HEADER, recordID)
+        },
+      }),
+      scope,
+    )
+
+    if (exchange.stream) {
+      // Nothing is committed until the encoder writes its first frame, so a failure before any
+      // wire-visible output (including suppressed reasoning or structured prose) is a real HTTP error.
+      const sse = sseWriter(response, scope.signal)
+      const { failure } = await streamCompletion(sse.paced(events), exchange, sse.write)
+      if (!sse.started && !response.headersSent) {
+        if (!scope.signal.aborted || scope.timedOut) fail(response, failure ?? { status: 502, kind: "server", message: "No response from the model" })
+      } else {
+        if (failure) info.failed = failure.code ?? failure.kind
+        if (!response.writableEnded) response.end()
+      }
+      return
+    }
+
+    const result = await collectCompletion(events, exchange)
+    sendJson(response, result.status, result.body)
+  }
+
+  /** Never rejects: every failure ends in a response (or a closed socket) and one log line. */
+  return async function handle(request: IncomingMessage, response: ServerResponse): Promise<void> {
+    const started = Date.now()
+    const id = crypto.randomUUID().slice(0, 8)
+    const info: RequestInfo = { route: "unparsed" }
+    const scope = beginRequest(request, response, host.options.requestTimeoutMs)
+    let outcome = "ok"
+    let error: string | undefined
+    try {
+      try {
+        await serve(request, response, scope, info)
+      } catch (caught) {
+        if (caught instanceof RequestAborted) {
+          outcome = caught.kind
+          if (caught.kind === "timeout") {
+            if (response.headersSent) response.end()
+            else fail(response, scope.timeoutError, true)
+          }
+        } else if (caught instanceof BodyError) {
+          outcome = `body_${caught.status}`
+          // 413: the client may still be sending; answer, then close (see `finishRequest`).
+          fail(response, { status: caught.status, kind: "invalid_request", message: caught.message }, caught.status === 413)
+        } else {
+          // Unexpected: the message goes to the log only; the client gets a generic one.
+          outcome = "error"
+          error = errorMessage(caught)
+          if (response.headersSent) {
+            if (!response.writableEnded) response.end()
+          } else fail(response, { status: 500, kind: "server", message: "Internal server error" })
+        }
+      }
+      if (outcome === "ok" && scope.signal.aborted) outcome = scope.timedOut ? "timeout" : "disconnected"
+      else if (outcome === "ok" && info.failed !== undefined) {
+        outcome = "error"
+        error = info.failed
+      } else if (outcome === "ok" && response.statusCode >= 400) outcome = `status_${response.statusCode}`
+    } catch (caught) {
+      outcome = "error"
+      error = errorMessage(caught)
+    } finally {
+      scope.dispose()
+      try {
+        finishRequest(request, response)
+      } catch {}
+      if (info.route !== "GET /healthz" || outcome !== "ok") {
+        const fields = { id, route: info.route, app: info.app, model: info.model, status: response.statusCode, ms: Date.now() - started, outcome, error }
+        if (outcome === "error" || response.statusCode >= 500) logError("request.failed", fields)
+        else log("request", fields)
+      }
+    }
+  }
+}

package/src/responses/request.ts

@@ -0,0 +1,377 @@
+/**
+ * OpenAI Responses request -> neutral `PlugRequest` plus the `ResponsesExchange` the response
+ * encoder needs.
+ *
+ * Pure function: no I/O. Stateless subset: the caller sends the whole conversation in `input`
+ * each time, which is how history already works. Anything that needs server-side state
+ * (`previous_response_id`, `conversation`, `item_reference`, `background`) or a hosted tool is
+ * rejected with 400 `unsupported_parameter` naming the field. The route resolves `model` to a
+ * `ModelRef` afterwards, which is why the request omits `ref`.
+ */
+import type { PlugboardOptions } from "../config.js"
+import {
+  isPlugError,
+  type PlugError,
+  type PlugGeneration,
+  type PlugMessage,
+  type PlugPart,
+  type PlugRequest,
+  type PlugTool,
+  type PlugToolChoice,
+} from "../contract.js"
+import type { ResponsesExchange } from "./response.js"
+
+type JsonObject = Record<string, unknown>
+
+export interface ParsedResponses {
+  /** The model call, minus the model ref the route resolves from `request.model`. */
+  readonly request: Omit<PlugRequest, "ref">
+  /** Response presentation state for the encoder; never reaches the model call. */
+  readonly exchange: ResponsesExchange
+  readonly reasoningEffort?: string
+}
+
+/** Name of the forced tool that carries structured output (same as the Chat Completions front-end). */
+const RESPOND_TOOL = "respond"
+
+/** System instruction for `json_object`: no schema, so the caller's prompt describes the keys. */
+const JSON_OBJECT_INSTRUCTION = "Respond with a single valid JSON object only."
+
+const isRecord = (value: unknown): value is JsonObject => typeof value === "object" && value !== null && !Array.isArray(value)
+
+const bad = (message: string, param?: string, code?: string): PlugError => ({
+  status: 400,
+  kind: "invalid_request",
+  message,
+  ...(code ? { code } : {}),
+  ...(param ? { param } : {}),
+})
+
+const unsupported = (message: string, param: string) => bad(message, param, "unsupported_parameter")
+
+const dataUrlType = (url: string) => /^data:([^;,]+)[;,]/.exec(url)?.[1]
+
+const parseJson = (value: string): unknown => {
+  try {
+    return JSON.parse(value)
+  } catch {
+    return value
+  }
+}
+
+/** Text of a string or a list of `input_text` / `output_text` parts (system, developer, tool output). */
+const textOf = (content: unknown): string | undefined => {
+  if (typeof content === "string") return content
+  if (!Array.isArray(content)) return undefined
+  const texts: string[] = []
+  for (const item of content) {
+    if (!isRecord(item) || typeof item.text !== "string") return undefined
+    texts.push(item.text)
+  }
+  return texts.join("\n")
+}
+
+/** Content of a user message: string, or parts of `input_text` / `input_image` / `input_file`. */
+const userParts = (content: unknown, param: string): PlugPart[] | PlugError => {
+  if (typeof content === "string") return [{ type: "text", text: content }]
+  if (!Array.isArray(content)) return bad("Message content must be a string or an array of content parts", param)
+  const parts: PlugPart[] = []
+  for (const [index, item] of content.entries()) {
+    const at = `${param}[${index}]`
+    if (!isRecord(item)) return bad("Content part must be an object", at)
+    if ((item.type === "input_text" || item.type === "output_text") && typeof item.text === "string") {
+      parts.push({ type: "text", text: item.text })
+    } else if (item.type === "input_image" || item.type === "image_url") {
+      // `image_url` is the Chat Completions part type; @langchain/openai sends it in Responses input for standard image blocks.
+      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`)
+      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}`
+        parts.push({ type: "media", url, mediaType: dataUrlType(url) })
+      } else if (typeof item.file_url === "string") {
+        parts.push({ type: "media", url: item.file_url })
+      } else return unsupported("input_file needs file_data or file_url; file_id is not supported (stateless)", `${at}.file_data`)
+    } else return unsupported(`Unsupported content part type "${String(item.type)}"`, `${at}.type`)
+  }
+  return parts
+}
+
+/** Assistant content: string, or `output_text` parts (refusals are dropped, like the Chat Completions front-end). */
+const assistantText = (content: unknown, param: string): string | PlugError => {
+  if (typeof content === "string") return content
+  if (!Array.isArray(content)) return bad("Assistant content must be a string or an array of output_text parts", param)
+  const texts: string[] = []
+  for (const [index, item] of content.entries()) {
+    if (!isRecord(item)) return bad("Content part must be an object", `${param}[${index}]`)
+    if (item.type === "refusal") continue
+    if ((item.type !== "output_text" && item.type !== "input_text") || typeof item.text !== "string")
+      return unsupported(`Unsupported assistant content part type "${String(item.type)}"`, `${param}[${index}].type`)
+    texts.push(item.text)
+  }
+  return texts.join("")
+}
+
+/**
+ * `input` items -> neutral messages. Adjacent assistant items (text, function calls) become one
+ * assistant message, the shape the Chat Completions front-end produces, so a parallel-call turn
+ * is one message followed by its results.
+ */
+const parseInput = (input: unknown): { system: string[]; messages: PlugMessage[] } | PlugError => {
+  if (typeof input === "string") return { system: [], messages: [{ role: "user", content: [{ type: "text", text: input }] }] }
+  if (!Array.isArray(input) || input.length === 0) return bad("input must be a string or a non-empty array of items", "input")
+
+  const system: string[] = []
+  const messages: PlugMessage[] = []
+  const toolNames = new Map<string, string>()
+  let pending: PlugPart[] | undefined
+  const flush = () => {
+    if (pending && pending.length > 0) messages.push({ role: "assistant", content: pending })
+    pending = undefined
+  }
+
+  for (const [index, item] of input.entries()) {
+    const param = `input[${index}]`
+    if (!isRecord(item)) return bad("Each input item must be an object", param)
+    const type = item.type ?? (item.role !== undefined ? "message" : undefined)
+    switch (type) {
+      case "message": {
+        switch (item.role) {
+          case "system":
+          case "developer": {
+            const value = textOf(item.content)
+            if (value === undefined) return bad("System message content must be a string or text parts", `${param}.content`)
+            if (value.length > 0) system.push(value)
+            break
+          }
+          case "user": {
+            flush()
+            const parts = userParts(item.content, `${param}.content`)
+            if (!Array.isArray(parts)) return parts
+            messages.push({ role: "user", content: parts })
+            break
+          }
+          case "assistant": {
+            const text = assistantText(item.content, `${param}.content`)
+            if (typeof text !== "string") return text
+            if (text.length > 0) (pending ??= []).push({ type: "text", text })
+            break
+          }
+          default:
+            return bad(`Unsupported message role "${String(item.role)}"`, `${param}.role`)
+        }
+        break
+      }
+      case "function_call": {
+        if (typeof item.call_id !== "string" || item.call_id.length === 0) return bad("function_call needs a non-empty call_id", `${param}.call_id`)
+        if (typeof item.name !== "string" || item.name.length === 0) return bad("function_call needs a name", `${param}.name`)
+        toolNames.set(item.call_id, item.name)
+        ;(pending ??= []).push({
+          type: "tool-call",
+          id: item.call_id,
+          name: item.name,
+          input: typeof item.arguments === "string" ? parseJson(item.arguments) : (item.arguments ?? {}),
+        })
+        break
+      }
+      case "function_call_output": {
+        flush()
+        if (typeof item.call_id !== "string") return bad("function_call_output needs a call_id", `${param}.call_id`)
+        const result = textOf(item.output)
+        if (result === undefined) return bad("function_call_output output must be a string or an array of text parts", `${param}.output`)
+        const name = toolNames.get(item.call_id)
+        if (name === undefined)
+          return bad(`function_call_output answers call_id "${item.call_id}", which no earlier function_call item has`, `${param}.call_id`)
+        messages.push({ role: "tool", content: [{ type: "tool-result", id: item.call_id, name, result }] })
+        break
+      }
+      // Reasoning items carry no content plugboard can replay; they are dropped.
+      case "reasoning":
+        break
+      case "item_reference":
+        return unsupported(
+          "item_reference needs server-side state, which plugboard does not keep; send the full items instead (Vercel AI SDK: providerOptions.openai.store = false)",
+          `${param}.type`,
+        )
+      default:
+        return unsupported(`Unsupported input item type "${String(type)}"`, `${param}.type`)
+    }
+  }
+  flush()
+  if (messages.length === 0) return bad("input has no user, assistant or tool items", "input")
+  return { system, messages }
+}
+
+const parseTools = (raw: unknown): PlugTool[] | PlugError => {
+  if (raw == null) return []
+  if (!Array.isArray(raw)) return bad("tools must be an array", "tools")
+  const tools: PlugTool[] = []
+  const names = new Set<string>()
+  for (const [index, entry] of raw.entries()) {
+    const at = `tools[${index}]`
+    if (!isRecord(entry)) return bad("Each tool must be an object", at)
+    if (entry.type !== "function")
+      return unsupported(`Unsupported tool type "${String(entry.type)}": only function tools are supported (built-in tools such as web_search and file_search run on OpenAI's servers)`, `${at}.type`)
+    if (typeof entry.name !== "string" || entry.name.length === 0) return bad('Each function tool needs a "name"', `${at}.name`)
+    if (names.has(entry.name)) return bad(`Duplicate tool name "${entry.name}"`, `${at}.name`)
+    if (entry.description != null && typeof entry.description !== "string") return bad("Tool description must be a string", `${at}.description`)
+    // `parameters` may be null (strict mode with no arguments): a tool without arguments.
+    if (entry.parameters != null && !isRecord(entry.parameters)) return bad("Tool parameters must be a JSON Schema object", `${at}.parameters`)
+    names.add(entry.name)
+    tools.push({
+      name: entry.name,
+      description: typeof entry.description === "string" ? entry.description : "",
+      parameters: isRecord(entry.parameters) ? entry.parameters : { type: "object", properties: {} },
+    })
+  }
+  return tools
+}
+
+const parseToolChoice = (raw: unknown): PlugToolChoice | undefined | PlugError => {
+  if (raw == null) return undefined
+  if (raw === "auto" || raw === "none" || raw === "required") return raw
+  if (isRecord(raw) && raw.type === "function" && typeof raw.name === "string") return { type: "tool", name: raw.name }
+  return unsupported("Unsupported tool_choice: use auto, none, required or {type:\"function\", name}", "tool_choice")
+}
+
+/**
+ * `text.format`: `json_schema` -> the `respond` tool (`structured`, forced unless the caller also
+ * sends tools); `json_object` -> a system instruction (`instruction`).
+ */
+const parseTextFormat = (raw: unknown): { structured?: PlugTool; instruction?: string } | PlugError => {
+  if (raw == null) return {}
+  if (!isRecord(raw)) return bad("text must be an object", "text")
+  const format = raw.format
+  if (format == null || (isRecord(format) && format.type === "text")) return {}
+  if (!isRecord(format)) return bad("text.format must be an object", "text.format")
+  if (format.type === "json_object") return { instruction: JSON_OBJECT_INSTRUCTION }
+  if (format.type === "json_schema") {
+    if (format.name != null && typeof format.name !== "string") return bad("text.format.name must be a string", "text.format.name")
+    if (format.description != null && typeof format.description !== "string") return bad("text.format.description must be a string", "text.format.description")
+    if (!isRecord(format.schema)) return bad("text.format.schema must be a JSON Schema object", "text.format.schema")
+    return {
+      structured: {
+        name: RESPOND_TOOL,
+        // With caller tools also on offer, this description is what tells the model which call is the final answer.
+        description:
+          "Give your final answer by calling this tool with JSON matching its schema." +
+          (typeof format.description === "string" ? ` ${format.description}` : ""),
+        parameters: format.schema,
+      },
+    }
+  }
+  return bad(`Unsupported text.format type "${String(format.type)}"`, "text.format.type")
+}
+
+const parseGeneration = (body: JsonObject): PlugGeneration | PlugError => {
+  const out: { -readonly [K in keyof PlugGeneration]: PlugGeneration[K] } = {}
+  for (const [key, field, min, max, integer] of [
+    ["temperature", "temperature", 0, 2, false],
+    ["top_p", "topP", 0, 1, false],
+    ["max_output_tokens", "maxTokens", 1, Number.MAX_SAFE_INTEGER, true],
+  ] as const) {
+    const value = body[key]
+    if (value == null) continue
+    if (typeof value !== "number" || !Number.isFinite(value)) return bad(`${key} must be a number`, key)
+    if (integer && !Number.isInteger(value)) return bad(`${key} must be an integer`, key)
+    if (value < min || value > max)
+      return bad(max === Number.MAX_SAFE_INTEGER ? `${key} must be at least ${min}` : `${key} must be between ${min} and ${max}`, key)
+    out[field] = value
+  }
+  return out
+}
+
+/** Fields that need server-side state or features plugboard does not have. */
+const checkUnsupported = (body: JsonObject): PlugError | undefined => {
+  if (body.previous_response_id != null)
+    return unsupported("previous_response_id is not supported: plugboard is stateless, send the full conversation in input", "previous_response_id")
+  if (body.conversation != null) return unsupported("conversation is not supported: plugboard is stateless", "conversation")
+  if (body.background === true) return unsupported("background mode is not supported", "background")
+  if (body.prompt != null) return unsupported("Stored prompts (prompt) are not supported", "prompt")
+  if (body.top_logprobs != null && body.top_logprobs !== 0) return unsupported("top_logprobs is not supported", "top_logprobs")
+  if (body.truncation != null && body.truncation !== "disabled") return unsupported('Only truncation "disabled" is supported', "truncation")
+}
+
+export function parseResponsesRequest(body: unknown, options: PlugboardOptions): ParsedResponses | PlugError {
+  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.input == null) return bad("input is required", "input")
+  const refused = checkUnsupported(body)
+  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")
+
+  const parsed = parseInput(body.input)
+  if (isPlugError(parsed)) return parsed
+  const callerTools = parseTools(body.tools)
+  if (!Array.isArray(callerTools)) return callerTools
+  const toolChoice = parseToolChoice(body.tool_choice)
+  if (isPlugError(toolChoice)) return toolChoice
+  const format = parseTextFormat(body.text)
+  if (isPlugError(format)) return format
+  const respond = format.structured
+  const generation = parseGeneration(body)
+  if (isPlugError(generation)) return generation
+
+  if (typeof toolChoice === "object" && !callerTools.some((tool) => tool.name === toolChoice.name))
+    return bad(`tool_choice names "${toolChoice.name}", which is not in tools`, "tool_choice.name")
+  if (respond && callerTools.some((tool) => tool.name === RESPOND_TOOL))
+    return bad(
+      `A tool named "${RESPOND_TOOL}" collides with text.format json_schema, which plugboard answers through that name`,
+      "tools",
+      "reserved_tool_name",
+    )
+  // json_schema + caller tools: the model may call a caller tool or `respond`, so `tool_choice` is
+  // `required` (not forced to `respond`). `tool_choice: none` leaves only `respond`; naming a tool
+  // contradicts a structured answer.
+  if (respond && typeof toolChoice === "object")
+    return unsupported("A tool_choice that names a tool cannot be combined with text.format json_schema", "tool_choice")
+  const withCallerTools = respond !== undefined && callerTools.length > 0 && toolChoice !== "none"
+  const tools = respond ? (withCallerTools ? [...callerTools, respond] : [respond]) : callerTools
+  if (tools.length > options.maxTools)
+    return bad(`Request has ${tools.length} tools; plugboard allows ${options.maxTools} (option \`maxTools\`)`, "tools", "too_many_tools")
+
+  const forced: PlugToolChoice | undefined = respond ? (withCallerTools ? "required" : { type: "tool", name: RESPOND_TOOL }) : toolChoice
+  const instructions = typeof body.instructions === "string" && body.instructions.length > 0 ? [body.instructions] : []
+  const system = [...instructions, ...parsed.system, ...(format.instruction ? [format.instruction] : [])]
+  const request: Omit<PlugRequest, "ref"> = {
+    model: body.model,
+    system,
+    messages: parsed.messages,
+    tools,
+    ...(forced && tools.length > 0 ? { toolChoice: forced } : {}),
+    generation,
+  }
+  const reasoningEffort = isRecord(body.reasoning) && typeof body.reasoning.effort === "string" ? body.reasoning.effort : undefined
+  const text = isRecord(body.text) ? body.text : undefined
+  return {
+    request,
+    exchange: {
+      model: body.model,
+      stream: body.stream === true,
+      // Echoed in the response object, as OpenAI does. `store` is always false: nothing is kept for retrieval.
+      envelope: {
+        instructions: typeof body.instructions === "string" ? body.instructions : null,
+        max_output_tokens: generation.maxTokens ?? null,
+        metadata: isRecord(body.metadata) ? body.metadata : {},
+        parallel_tool_calls: body.parallel_tool_calls !== false,
+        previous_response_id: null,
+        reasoning: { effort: reasoningEffort ?? null, summary: null },
+        store: false,
+        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 : [],
+        top_p: generation.topP ?? null,
+        truncation: "disabled",
+        user: typeof body.user === "string" ? body.user : null,
+      },
+      ...(respond ? { structuredTool: RESPOND_TOOL, ...(withCallerTools ? { callerTools: true } : {}) } : {}),
+    },
+    ...(reasoningEffort ? { reasoningEffort } : {}),
+  }
+}