opencode-plugboard 0.2.1 → 0.4.0

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

package/src/responses/response.ts

@@ -0,0 +1,225 @@
+/**
+ * Neutral results -> OpenAI Responses wire objects: one response object, or the named SSE
+ * events of a stream.
+ *
+ * One state machine (`runResponse`) serves both: it emits stream events as it goes and returns
+ * the final response object, so the JSON body and the stream never disagree. A non-streaming
+ * call passes a no-op `emit`. Reasoning deltas are dropped (no reasoning items are produced).
+ */
+import type { PlugError, PlugEvent, PlugFinish, PlugUsage } from "../contract.js"
+
+type ToolCall = Extract<PlugEvent, { type: "tool-call" }>
+
+/** What the encoder needs besides the model events: Responses presentation state. The request decoder produces it. */
+export interface ResponsesExchange {
+  /** The model string the client sent; echoed in every response object. */
+  readonly model: string
+  readonly stream: boolean
+  /** Request fields echoed into the response object (instructions, tools, temperature, ...). */
+  readonly envelope: Readonly<Record<string, unknown>>
+  /** Name of the forced tool that carries `text.format` json_schema output; its input becomes the message text. */
+  readonly structuredTool?: string
+  /**
+   * The caller's own tools are offered next to the structured tool. A call to any of them is the
+   * response (function_call items, prose and the structured answer dropped); the structured
+   * answer is the message text only when the step called no caller tool.
+   */
+  readonly callerTools?: boolean
+}
+
+/** A stream event as emitted: `type` is also the SSE event name. */
+export type ResponsesStreamEvent = { readonly type: string; readonly sequence_number: number } & 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. */
+export interface ResponseRun {
+  readonly failure?: PlugError
+  /** Whether `response.created` was emitted (a streamed response is committed as a 200 SSE stream). */
+  readonly started: boolean
+  /** The final response object (completed, incomplete or failed once started). */
+  readonly response?: object
+}
+
+type Item = Record<string, unknown>
+
+const args = (input: unknown) => (typeof input === "string" ? input : JSON.stringify(input ?? {}))
+
+const newId = (prefix: string) => `${prefix}_${crypto.randomUUID().replaceAll("-", "")}`
+
+const encodeUsage = (usage: PlugUsage) => {
+  const input = usage.inputTokens ?? 0
+  const output = usage.outputTokens ?? 0
+  return {
+    input_tokens: input,
+    input_tokens_details: { cached_tokens: usage.cacheReadTokens ?? 0 },
+    output_tokens: output,
+    output_tokens_details: { reasoning_tokens: usage.reasoningTokens ?? 0 },
+    total_tokens: input + output,
+  }
+}
+
+const noFinish = (): PlugError => ({ status: 500, kind: "server", message: "Model stream ended without a finish event" })
+const failedRun = (): PlugError => ({ status: 500, kind: "server", message: "Model run failed" })
+
+/** SSE frame of one stream event: `event: <type>` then `data: <json>`. */
+export const sseFrame = (event: ResponsesStreamEvent): string => `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`
+
+/**
+ * Structured-output projection, same rules as the Chat Completions front-end: in structured mode
+ * the message text is exactly the arguments of the first call to the `respond` tool; prose and
+ * other calls are suppressed. Without an answer the exchange fails, except when the model
+ * stopped for `length` or `content-filter`, which keep their status with empty output.
+ */
+const structuredFailure = (exchange: ResponsesExchange, 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 runResponse(
+  events: AsyncIterable<PlugEvent>,
+  exchange: ResponsesExchange,
+  emit: (event: ResponsesStreamEvent) => void,
+): Promise<ResponseRun> {
+  const id = newId("resp")
+  const createdAt = Math.floor(Date.now() / 1000)
+  let sequence = 0
+  const send = (type: string, data: Record<string, unknown>) => emit({ type, sequence_number: sequence++, ...data })
+  const envelope = (status: string, output: Item[], extra: Record<string, unknown> = {}) => ({
+    id,
+    object: "response",
+    created_at: createdAt,
+    status,
+    error: null,
+    incomplete_details: null,
+    model: exchange.model,
+    output,
+    ...exchange.envelope,
+    ...extra,
+  })
+
+  const items: Item[] = []
+  /** Output items that are open or done: the next item's `output_index`. */
+  let nextIndex = 0
+  let open: { id: string; index: number; text: string } | undefined
+  let started = false
+  let calls = 0
+  let answered = false
+  /** 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
+  let usage: PlugUsage | undefined
+  let failure: PlugError | undefined
+
+  const start = () => {
+    if (started) return
+    started = true
+    send("response.created", { response: envelope("in_progress", []) })
+    send("response.in_progress", { response: envelope("in_progress", []) })
+  }
+  const messageItem = (itemId: string, status: string, text: string | undefined): Item => ({
+    id: itemId,
+    type: "message",
+    status,
+    role: "assistant",
+    content: text === undefined ? [] : [{ type: "output_text", text, annotations: [], logprobs: [] }],
+  })
+  const text = (delta: string) => {
+    if (delta.length === 0) return
+    start()
+    if (!open) {
+      open = { id: newId("msg"), index: nextIndex++, text: "" }
+      send("response.output_item.added", { output_index: open.index, item: messageItem(open.id, "in_progress", undefined) })
+      send("response.content_part.added", {
+        item_id: open.id,
+        output_index: open.index,
+        content_index: 0,
+        part: { type: "output_text", text: "", annotations: [], logprobs: [] },
+      })
+    }
+    open.text += delta
+    send("response.output_text.delta", { item_id: open.id, output_index: open.index, content_index: 0, delta, logprobs: [] })
+  }
+  const closeMessage = () => {
+    if (!open) return
+    const part = { type: "output_text", text: open.text, annotations: [], logprobs: [] }
+    send("response.output_text.done", { item_id: open.id, output_index: open.index, content_index: 0, text: open.text, logprobs: [] })
+    send("response.content_part.done", { item_id: open.id, output_index: open.index, content_index: 0, part })
+    const item = messageItem(open.id, "completed", open.text)
+    send("response.output_item.done", { output_index: open.index, item })
+    items.push(item)
+    open = undefined
+  }
+  /** Tool calls arrive whole, so each goes out as one arguments delta. */
+  const toolCall = (call: ToolCall) => {
+    start()
+    closeMessage()
+    const index = nextIndex++
+    const itemId = newId("fc")
+    const argumentsText = args(call.input)
+    const item = (status: string, text: string): Item => ({ id: itemId, type: "function_call", status, call_id: call.id, name: call.name, arguments: text })
+    send("response.output_item.added", { output_index: index, item: item("in_progress", "") })
+    send("response.function_call_arguments.delta", { item_id: itemId, output_index: index, delta: argumentsText })
+    send("response.function_call_arguments.done", { item_id: itemId, output_index: index, name: call.name, arguments: argumentsText })
+    const done = item("completed", argumentsText)
+    send("response.output_item.done", { output_index: index, item: done })
+    items.push(done)
+    calls++
+  }
+
+  for await (const event of events) {
+    if (event.type === "error") {
+      failure = event.error
+      break
+    }
+    if (event.type === "finish") {
+      usage = event.usage ?? usage
+      if (event.reason === "error") failure ??= failedRun()
+      else finish = event.reason
+      continue
+    }
+    if (event.type === "reasoning-delta") continue
+    if (exchange.structuredTool !== undefined) {
+      // Structured mode: only the first answer is content; prose and other tool calls are
+      // suppressed, except the caller's own tools when they are offered.
+      if (event.type === "tool-call" && event.name === exchange.structuredTool) {
+        if (!answered) {
+          answered = true
+          if (exchange.callerTools) held = event
+          else text(args(event.input))
+        }
+        continue
+      }
+      if (!(exchange.callerTools && event.type === "tool-call")) continue
+    }
+    if (event.type === "text-delta") text(event.text)
+    else toolCall(event)
+  }
+
+  const passthrough = exchange.callerTools === true && calls > 0
+  const structuredAnswer = exchange.structuredTool !== undefined && !passthrough
+  failure ??= finish ? (passthrough ? undefined : structuredFailure(exchange, finish, answered)) : noFinish()
+  if (failure) {
+    if (!started) return { failure, started }
+    closeMessage()
+    const response = envelope("failed", items, {
+      error: { code: failure.code ?? failure.kind, message: failure.message },
+      ...(usage ? { usage: encodeUsage(usage) } : {}),
+    })
+    send("response.failed", { response })
+    return { failure, started, response }
+  }
+  start()
+  if (held && structuredAnswer) text(args(held.input))
+  closeMessage()
+  const incomplete = finish === "length" ? "max_output_tokens" : finish === "content-filter" ? "content_filter" : undefined
+  const response = envelope(incomplete ? "incomplete" : "completed", items, {
+    ...(incomplete ? { incomplete_details: { reason: incomplete } } : {}),
+    ...(usage ? { usage: encodeUsage(usage) } : {}),
+  })
+  send(incomplete ? "response.incomplete" : "response.completed", { response })
+  return { started, response }
+}

package/src/responses/route.ts

@@ -0,0 +1,72 @@
+/**
+ * `POST /v1/responses`: the Responses front-end's half of the route. `src/openai/route.ts` has
+ * already checked origin, authenticated, and read the JSON body (the same handling and
+ * deadline as Chat Completions) and hands over here.
+ *
+ * Same flow as Chat Completions: parse, resolve the model, call the ModelCaller, encode. Nothing
+ * is committed until the encoder emits its first event, so a failure before any output is a
+ * real HTTP error even when the client asked for a stream.
+ */
+
+import type { ServerResponse } from "node:http"
+import { isPlugError, type PlugError, type PlugRequest } from "../contract.js"
+import { boundEvents, sendJson, sseWriter, type RequestScope } from "../http.js"
+import { resolveModel } from "../models.js"
+import { encodeError } from "../openai/response.js"
+import type { RouteHost } from "../openai/route.js"
+import { parseResponsesRequest } from "./request.js"
+import { runResponse, sseFrame } from "./response.js"
+
+const SESSION_HEADER = "x-plugboard-session"
+
+export interface ResponsesCall {
+  readonly app: string
+  readonly body: unknown
+  readonly response: ServerResponse
+  readonly scope: RequestScope
+  /** The route's log fields: the resolved model, and the outcome of a stream that failed after it committed. */
+  readonly info: { model?: string; failed?: string }
+}
+
+export async function serveResponses(host: RouteHost, { app, body, response, scope, info }: ResponsesCall): Promise<void> {
+  const fail = (error: PlugError) => sendJson(response, error.status, encodeError(error))
+
+  const parsed = parseResponsesRequest(body, host.options)
+  if (isPlugError(parsed)) return fail(parsed)
+  const catalog = await scope.race(host.loadCatalog())
+  const ref = resolveModel(host.options, parsed.request.model, catalog, parsed.reasoningEffort)
+  if (isPlugError(ref)) return fail(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,
+      signal: scope.signal,
+      onRecord: (recordID) => {
+        if (response.headersSent || response.destroyed || !/^[\x21-\x7e]+$/.test(recordID)) return
+        response.setHeader(SESSION_HEADER, recordID)
+      },
+    }),
+    scope,
+  )
+
+  if (exchange.stream) {
+    const sse = sseWriter(response, scope.signal)
+    const { failure } = await runResponse(sse.paced(events), exchange, (event) => sse.write(sseFrame(event)))
+    if (!sse.started && !response.headersSent) {
+      if (!scope.signal.aborted || scope.timedOut) fail(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 run = await runResponse(events, exchange, () => {})
+  if (run.failure || !run.response) return fail(run.failure ?? { status: 502, kind: "server", message: "No response from the model" })
+  sendJson(response, 200, run.response)
+}