opencode-plugboard 0.0.0-stage → 0.3.0

package/src/openai/request.ts

@@ -0,0 +1,334 @@
+/**
+ * OpenAI Chat Completions request -> neutral `PlugRequest` plus the `OpenAiExchange` the
+ * response encoders need.
+ *
+ * Pure function: no I/O. 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 { OpenAiExchange } from "./response.js"
+
+type JsonObject = Record<string, unknown>
+
+export interface ParsedChat {
+  /** The model call, minus the model ref the route resolves from `request.model`. */
+  readonly request: Omit<PlugRequest, "ref">
+  /** Response presentation state for the encoders; never reaches the model call. */
+  readonly exchange: OpenAiExchange
+  readonly reasoningEffort?: string
+}
+
+/** Name of the forced tool that carries structured output. */
+const RESPOND_TOOL = "respond"
+
+/** The most stop sequences OpenAI accepts. */
+const MAX_STOP = 4
+
+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 } : {}),
+})
+
+/** Text of a string or an array of `{type:"text"}` parts (system, developer, tool and assistant content). */
+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")
+}
+
+const dataUrlType = (url: string) => /^data:([^;,]+)[;,]/.exec(url)?.[1]
+
+const parseJson = (value: string): unknown => {
+  try {
+    return JSON.parse(value)
+  } catch {
+    return value
+  }
+}
+
+/** User content: string, or parts of text / image_url / 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 === "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
+      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}`
+      parts.push({ type: "media", url, mediaType: dataUrlType(url) })
+    } else return bad(`Unsupported content part type "${String(item.type)}"`, `${at}.type`, "unsupported_parameter")
+  }
+  return parts
+}
+
+const parseMessages = (raw: unknown[]): { system: string[]; messages: PlugMessage[] } | PlugError => {
+  const system: string[] = []
+  const messages: PlugMessage[] = []
+  // `role:"tool"` messages carry only `tool_call_id`; tool results need the tool's name.
+  const toolNames = new Map<string, string>()
+
+  for (const [index, message] of raw.entries()) {
+    const param = `messages[${index}]`
+    if (!isRecord(message)) return bad("Each message must be an object", param)
+    switch (message.role) {
+      case "system":
+      case "developer": {
+        const value = textOf(message.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": {
+        const parts = userParts(message.content, `${param}.content`)
+        if (!Array.isArray(parts)) return parts
+        messages.push({ role: "user", content: parts })
+        break
+      }
+      case "assistant": {
+        const parts: PlugPart[] = []
+        if (message.content != null) {
+          // Assistant content may mix text and refusal parts; keep the text.
+          const value = Array.isArray(message.content)
+            ? textOf(message.content.filter((p) => isRecord(p) && p.type === "text"))
+            : textOf(message.content)
+          if (value === undefined) return bad("Assistant content must be a string or text parts", `${param}.content`)
+          if (value.length > 0) parts.push({ type: "text", text: value })
+        }
+        if (message.tool_calls != null) {
+          if (!Array.isArray(message.tool_calls)) return bad("tool_calls must be an array", `${param}.tool_calls`)
+          for (const [i, call] of message.tool_calls.entries()) {
+            const fn = isRecord(call) && isRecord(call.function) ? call.function : undefined
+            if (!isRecord(call) || !fn || typeof fn.name !== "string")
+              return bad("Each tool call needs an id and a function name", `${param}.tool_calls[${i}]`)
+            if (typeof call.id !== "string" || call.id.length === 0)
+              return bad("Each tool call needs a non-empty id", `${param}.tool_calls[${i}].id`)
+            const id = call.id
+            toolNames.set(id, fn.name)
+            parts.push({
+              type: "tool-call",
+              id,
+              name: fn.name,
+              input: typeof fn.arguments === "string" ? parseJson(fn.arguments) : (fn.arguments ?? {}),
+            })
+          }
+        }
+        if (parts.length > 0) messages.push({ role: "assistant", content: parts })
+        break
+      }
+      case "tool": {
+        const result = textOf(message.content)
+        if (typeof message.tool_call_id !== "string" || result === undefined)
+          return bad("Tool messages need a tool_call_id and string or text-part content", param)
+        const id = message.tool_call_id
+        const name = toolNames.get(id)
+        if (name === undefined)
+          return bad(`Tool message answers tool_call_id "${id}", which no earlier assistant tool call has`, `${param}.tool_call_id`)
+        messages.push({ role: "tool", content: [{ type: "tool-result", id, name, result }] })
+        break
+      }
+      default:
+        return bad(`Unsupported message role "${String(message.role)}"`, `${param}.role`)
+    }
+  }
+  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 fn = isRecord(entry) && entry.type === "function" && isRecord(entry.function) ? entry.function : undefined
+    if (!fn || typeof fn.name !== "string" || fn.name.length === 0)
+      return bad('Each tool must be {"type":"function","function":{"name":...}}', `tools[${index}]`)
+    if (names.has(fn.name)) return bad(`Duplicate tool name "${fn.name}"`, `tools[${index}].function.name`)
+    if (fn.description != null && typeof fn.description !== "string")
+      return bad("Tool description must be a string", `tools[${index}].function.description`)
+    // An omitted `parameters` is a tool without arguments; a present one must be a JSON Schema object.
+    if (fn.parameters != null && !isRecord(fn.parameters))
+      return bad("Tool parameters must be a JSON Schema object", `tools[${index}].function.parameters`)
+    names.add(fn.name)
+    tools.push({
+      name: fn.name,
+      description: typeof fn.description === "string" ? fn.description : "",
+      parameters: isRecord(fn.parameters) ? fn.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" && isRecord(raw.function) && typeof raw.function.name === "string")
+    return { type: "tool", name: raw.function.name }
+  return bad("Unsupported tool_choice", "tool_choice")
+}
+
+/** System instruction for `json_object`: no schema, so the caller's prompt describes the keys (OpenAI semantics). */
+const JSON_OBJECT_INSTRUCTION = "Respond with a single valid JSON object only."
+
+/**
+ * `json_schema` -> the `respond` tool (`structured`; forced unless the caller also sends tools).
+ * `json_object` -> a system instruction and plain text content (`instruction`): there is no schema
+ * to force a tool with.
+ */
+const parseResponseFormat = (raw: unknown): { structured?: PlugTool; instruction?: string } | PlugError => {
+  if (raw == null) return {}
+  if (!isRecord(raw)) return bad("response_format must be an object", "response_format")
+  if (raw.type === "text") return {}
+  if (raw.type === "json_object") return { instruction: JSON_OBJECT_INSTRUCTION }
+  if (raw.type === "json_schema") {
+    const spec = raw.json_schema
+    if (!isRecord(spec)) return bad("response_format.json_schema must be an object", "response_format.json_schema")
+    if (spec.name != null && typeof spec.name !== "string") return bad("response_format.json_schema.name must be a string", "response_format.json_schema.name")
+    if (spec.description != null && typeof spec.description !== "string")
+      return bad("response_format.json_schema.description must be a string", "response_format.json_schema.description")
+    if (!isRecord(spec.schema)) return bad("response_format.json_schema.schema must be a JSON Schema object", "response_format.json_schema.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 spec.description === "string" ? ` ${spec.description}` : ""),
+        parameters: spec.schema,
+      },
+    }
+  }
+  return bad(`Unsupported response_format type "${String(raw.type)}"`, "response_format.type")
+}
+
+const parseGeneration = (body: JsonObject): PlugGeneration | PlugError => {
+  const out: { -readonly [K in keyof PlugGeneration]: PlugGeneration[K] } = {}
+  const number = (key: string, min: number, max: number, integer: boolean): number | undefined | PlugError => {
+    const value = body[key]
+    if (value == null) return undefined
+    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)
+    return value
+  }
+  for (const [key, field, min, max, integer] of [
+    ["temperature", "temperature", 0, 2, false],
+    ["top_p", "topP", 0, 1, false],
+    ["presence_penalty", "presencePenalty", -2, 2, false],
+    ["frequency_penalty", "frequencyPenalty", -2, 2, false],
+    // max_completion_tokens is the current name; max_tokens the deprecated one. Prefer the former.
+    ["max_tokens", "maxTokens", 1, Number.MAX_SAFE_INTEGER, true],
+    ["max_completion_tokens", "maxTokens", 1, Number.MAX_SAFE_INTEGER, true],
+  ] as const) {
+    const value = number(key, min, max, integer)
+    if (typeof value === "object") return value
+    if (value !== undefined) out[field] = value
+  }
+  if (body.stop != null) {
+    const stop = typeof body.stop === "string" ? [body.stop] : body.stop
+    if (!Array.isArray(stop) || !stop.every((s) => typeof s === "string")) return bad("stop must be a string or an array of strings", "stop")
+    if (stop.length > MAX_STOP) return bad(`stop takes at most ${MAX_STOP} sequences`, "stop")
+    out.stop = stop as string[]
+  }
+  return out
+}
+
+export function parseChatRequest(body: unknown, options: PlugboardOptions): ParsedChat | 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 (!Array.isArray(body.messages) || body.messages.length === 0) return bad("messages must be a non-empty array", "messages")
+
+  // Parameters the session backend cannot honour are rejected, not ignored.
+  if (body.n != null) {
+    if (typeof body.n !== "number" || !Number.isInteger(body.n) || body.n < 1) return bad("n must be a positive integer", "n")
+    if (body.n > 1) return bad("Only n=1 is supported", "n", "unsupported_parameter")
+  }
+  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")
+
+  const parsed = parseMessages(body.messages)
+  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 = parseResponseFormat(body.response_format)
+  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.function.name")
+  if (respond && callerTools.some((tool) => tool.name === RESPOND_TOOL))
+    return bad(
+      `A tool named "${RESPOND_TOOL}" collides with response_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 bad(
+      "A tool_choice that names a tool cannot be combined with response_format json_schema",
+      "tool_choice",
+      "unsupported_parameter",
+    )
+  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 request: Omit<PlugRequest, "ref"> = {
+    model: body.model,
+    system: format.instruction ? [...parsed.system, format.instruction] : parsed.system,
+    messages: parsed.messages,
+    tools,
+    ...(forced && tools.length > 0 ? { toolChoice: forced } : {}),
+    generation,
+  }
+  const streamOptions = isRecord(body.stream_options) ? body.stream_options : {}
+  return {
+    request,
+    exchange: {
+      model: body.model,
+      stream: body.stream === true,
+      includeUsage: streamOptions.include_usage === true,
+      ...(respond ? { structuredTool: RESPOND_TOOL, ...(withCallerTools ? { callerTools: true } : {}) } : {}),
+    },
+    ...(typeof body.reasoning_effort === "string" ? { reasoningEffort: body.reasoning_effort } : {}),
+  }
+}

package/src/openai/response.ts

@@ -0,0 +1,286 @@
+/**
+ * Neutral results -> OpenAI wire objects: Chat Completions as one JSON body or SSE chunks, the
+ * `/v1/models` list, and error bodies.
+ *
+ * Reasoning deltas are dropped: Chat Completions has no standard field for them.
+ */
+import type { PlugError, PlugErrorKind, PlugEvent, PlugFinish, PlugUsage } from "../contract.js"
+import type { ListedModel } from "../models.js"
+
+type ToolCall = Extract<PlugEvent, { type: "tool-call" }>
+
+/**
+ * What the encoders need to know about the exchange besides the model events: Chat Completions
+ * presentation state. The request decoder produces it; the model call never sees it.
+ */
+export interface OpenAiExchange {
+  /** The model string the client sent; echoed in every response object. */
+  readonly model: string
+  readonly stream: boolean
+  /** `stream_options.include_usage`: the stream carries a usage field per chunk and a final usage chunk. */
+  readonly includeUsage: boolean
+  /** Name of the forced tool that carries `response_format` output; its input is unwrapped into the message content. */
+  readonly structuredTool?: string
+  /**
+   * The caller's own tools are offered next to the structured tool. A call to any of them is the
+   * response (normal `tool_calls`, prose and the structured answer dropped); the structured
+   * answer is content only when the step called no caller tool.
+   */
+  readonly callerTools?: boolean
+}
+
+/** How a streamed exchange ended. Nothing was written when `failure` is set and `started` is false: the caller answers with a real HTTP error. */
+export interface StreamResult {
+  readonly failure?: PlugError
+  /** Whether any frame was written (the response is committed as a 200 SSE stream). */
+  readonly started: boolean
+}
+
+const ERROR_TYPES: Record<PlugErrorKind, string> = {
+  invalid_request: "invalid_request_error",
+  authentication: "authentication_error",
+  permission: "permission_error",
+  not_found: "not_found_error",
+  rate_limit: "rate_limit_error",
+  server: "server_error",
+  timeout: "timeout_error",
+}
+
+const FINISH_REASONS: Record<Exclude<PlugFinish, "error">, string> = {
+  stop: "stop",
+  length: "length",
+  "tool-calls": "tool_calls",
+  "content-filter": "content_filter",
+}
+
+export const encodeError = (error: PlugError): object => ({
+  error: { message: error.message, type: ERROR_TYPES[error.kind], param: error.param ?? null, code: error.code ?? null },
+})
+
+/** `GET /v1/models` body. */
+export const encodeModelList = (models: ReadonlyArray<ListedModel>): object => ({
+  object: "list",
+  data: models.map(({ id, ref, model }) => ({
+    id,
+    object: "model",
+    created: 0,
+    owned_by: ref.providerID,
+    plugboard: { capabilities: model.capabilities ?? {}, contextLimit: model.contextLimit },
+  })),
+})
+
+const encodeUsage = (usage: PlugUsage) => {
+  const prompt = usage.inputTokens ?? 0
+  const completion = usage.outputTokens ?? 0
+  return {
+    prompt_tokens: prompt,
+    completion_tokens: completion,
+    total_tokens: prompt + completion,
+    prompt_tokens_details: { cached_tokens: usage.cacheReadTokens ?? 0 },
+    completion_tokens_details: { reasoning_tokens: usage.reasoningTokens ?? 0 },
+  }
+}
+
+const args = (input: unknown) => (typeof input === "string" ? input : JSON.stringify(input ?? {}))
+
+/**
+ * Final finish_reason. Tool calls force `tool_calls` even when the upstream says `stop`;
+ * structured output ends as a plain `stop`.
+ */
+const finishReason = (reason: Exclude<PlugFinish, "error">, calls: number, structured: boolean) => {
+  if (reason === "length" || reason === "content-filter") return FINISH_REASONS[reason]
+  if (structured) return "stop"
+  return calls > 0 ? "tool_calls" : FINISH_REASONS[reason]
+}
+
+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" })
+
+/**
+ * Structured-output projection, shared by the JSON and SSE encoders so both give the same body.
+ * In structured mode (`exchange.structuredTool` set) the content is exactly the arguments of
+ * the first call to that tool: prose, reasoning and any other tool call are suppressed, and
+ * later calls to it are ignored. Without an answer the exchange fails, except when the model
+ * stopped for `length` or `content-filter`, which keep their finish reasons with empty content.
+ */
+const structured = {
+  isAnswer: (exchange: OpenAiExchange, call: ToolCall) => exchange.structuredTool !== undefined && call.name === exchange.structuredTool,
+  content: (call: ToolCall) => args(call.input),
+  /** The failure for a finished structured exchange, if any. */
+  failure: (exchange: OpenAiExchange, 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`,
+        },
+}
+
+const newId = () => `chatcmpl-${crypto.randomUUID().replaceAll("-", "").slice(0, 29)}`
+const now = () => Math.floor(Date.now() / 1000)
+
+export async function collectCompletion(
+  events: AsyncIterable<PlugEvent>,
+  exchange: OpenAiExchange,
+): Promise<{ status: number; body: object }> {
+  let text = ""
+  const calls: ToolCall[] = []
+  let finish: Exclude<PlugFinish, "error"> | undefined
+  let usage: PlugUsage | undefined
+  let failure: PlugError | undefined
+
+  for await (const event of events) {
+    if (event.type === "text-delta") text += event.text
+    else if (event.type === "tool-call") calls.push(event)
+    else if (event.type === "finish") {
+      usage = event.usage ?? usage
+      if (event.reason === "error") failure ??= failedRun()
+      else finish = event.reason
+    } else if (event.type === "error") {
+      failure = event.error
+      break
+    }
+  }
+  if (!failure && !finish) failure = noFinish()
+  if (failure || !finish) {
+    const error = failure ?? noFinish()
+    return { status: error.status, body: encodeError(error) }
+  }
+
+  const answer = calls.find((call) => structured.isAnswer(exchange, call))
+  const others = calls.filter((call) => !structured.isAnswer(exchange, call))
+  // With the caller's tools offered, a call to one of them wins over the structured answer.
+  const passthrough = exchange.callerTools === true && others.length > 0
+  const isStructured = exchange.structuredTool !== undefined && !passthrough
+  const missing = passthrough ? undefined : structured.failure(exchange, finish, answer !== undefined)
+  if (missing) return { status: missing.status, body: encodeError(missing) }
+  const toolCalls = isStructured ? [] : others
+  const message: Record<string, unknown> = {
+    role: "assistant",
+    content: isStructured
+      ? answer
+        ? structured.content(answer)
+        : null
+      : exchange.structuredTool === undefined && text.length > 0
+        ? text
+        : null,
+    refusal: null,
+  }
+  if (toolCalls.length > 0)
+    message.tool_calls = toolCalls.map((call) => ({
+      id: call.id,
+      type: "function",
+      function: { name: call.name, arguments: args(call.input) },
+    }))
+  return {
+    status: 200,
+    body: {
+      id: newId(),
+      object: "chat.completion",
+      created: now(),
+      model: exchange.model,
+      choices: [{ index: 0, message, logprobs: null, finish_reason: finishReason(finish, toolCalls.length, isStructured) }],
+      ...(usage ? { usage: encodeUsage(usage) } : {}),
+    },
+  }
+}
+
+/**
+ * Writes SSE frames via `write` (each frame is one complete `data: ...\n\n` string) and reports
+ * how the exchange ended. A failure before the first frame is not written (the first wire-visible
+ * output decides the HTTP status: see `StreamResult`); a failure after it is written as an
+ * `error` frame and then `data: [DONE]`.
+ */
+export async function streamCompletion(
+  events: AsyncIterable<PlugEvent>,
+  exchange: OpenAiExchange,
+  write: (chunk: string) => void,
+): Promise<StreamResult> {
+  const id = newId()
+  const created = now()
+  const frame = (value: object) => write(`data: ${JSON.stringify(value)}\n\n`)
+  const chunk = (delta: Record<string, unknown>, finish: string | null = null) =>
+    frame({
+      id,
+      object: "chat.completion.chunk",
+      created,
+      model: exchange.model,
+      choices: [{ index: 0, delta, finish_reason: finish, logprobs: null }],
+      ...(exchange.includeUsage ? { usage: null } : {}),
+    })
+
+  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
+    chunk({ role: "assistant", content: "" })
+  }
+
+  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" && structured.isAnswer(exchange, event)) {
+        if (!answered) {
+          answered = true
+          if (exchange.callerTools) held = event
+          else {
+            start()
+            chunk({ content: structured.content(event) })
+          }
+        }
+        continue
+      }
+      if (!(exchange.callerTools && event.type === "tool-call")) continue
+    }
+    start()
+    if (event.type === "text-delta") {
+      if (event.text.length > 0) chunk({ content: event.text })
+    } else {
+      // Tool calls arrive whole, so each goes out as one chunk with the next index.
+      chunk({ tool_calls: [{ index: calls++, id: event.id, type: "function", function: { name: event.name, arguments: args(event.input) } }] })
+    }
+  }
+
+  const passthrough = exchange.callerTools === true && calls > 0
+  const isStructured = exchange.structuredTool !== undefined && !passthrough
+  failure ??= finish ? (passthrough ? undefined : structured.failure(exchange, finish, answered)) : noFinish()
+  if (failure) {
+    if (!started) return { failure, started }
+    frame(encodeError(failure))
+    write("data: [DONE]\n\n")
+    return { failure, started }
+  }
+  start()
+  if (held && isStructured) chunk({ content: structured.content(held) })
+  chunk({}, finishReason(finish!, calls, isStructured))
+  if (exchange.includeUsage && usage)
+    frame({ id, object: "chat.completion.chunk", created, model: exchange.model, choices: [], usage: encodeUsage(usage) })
+  write("data: [DONE]\n\n")
+  return { started }
+}