opencode-plugboard 0.6.0 → 0.8.0

package/README.md

@@ -4,7 +4,7 @@
 [![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)
 
-An OpenCode V2 plugin that serves an OpenAI-compatible API from your OpenCode server, so your other apps reuse the provider logins you already made in OpenCode.
+An OpenCode V2 plugin that turns your OpenCode server into an OpenAI- and Anthropic-compatible API, so every other app reuses the provider logins you already made in OpenCode. Point Claude Code at a GPT model, or n8n at your Claude subscription.
 
 ```
 client ──▶ plugboard listener ──▶ OpenCode session ──▶ provider
@@ -12,7 +12,7 @@ client ──▶ plugboard listener ──▶ OpenCode session ──▶ provide
   └──── reply; tool calls go back to the caller ◀──────────┘
 ```
 
-Tools like n8n, Open WebUI or a Discord bot only speak the OpenAI API, so each wants its own key or its own gateway. Plugboard serves `/v1/chat/completions`, `/v1/responses` and `/v1/models` from inside OpenCode. OpenCode never runs your tools.
+Tools like n8n, Open WebUI or a Discord bot only speak the OpenAI API, so each wants its own key or its own gateway. Plugboard serves OpenAI Chat Completions (`/v1/chat/completions`), the Responses API (`/v1/responses`), the Anthropic Messages API (`/v1/messages`), legacy completions (`/v1/completions`) and `/v1/models` from inside OpenCode. OpenCode never runs your tools.
 
 ## Quick start
 
@@ -30,7 +30,7 @@ export PLUGBOARD_KEY_MY_APP=choose-a-long-random-string
 {
   "plugins": [
     {
-      "package": "opencode-plugboard@0.6.0",
+      "package": "opencode-plugboard@0.8.0",
       "options": {
         "keys": { "my-app": "{env:PLUGBOARD_KEY_MY_APP}" },
         "models": ["anthropic/claude-sonnet-4-6", "github-copilot/*", "opencode-go/glm-5.3-flash"],
@@ -77,7 +77,7 @@ Plugboard is early (0.x) and narrow on purpose.
 
 - **V2 only.** OpenCode V2 has no OpenAI endpoint, and the V1 plugins that had one stopped working when the plugin API changed. V1 is not planned.
 - **Two formats:** Chat Completions and Responses. `/v1/responses` is a stateless subset, see [docs/responses.md](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/responses.md). Anthropic Messages and Gemini front-ends are on the [roadmap](#roadmap).
-- **Not planned:** embeddings, audio, image generation. Only `n=1`, no `logprobs`.
+- **Not planned:** embeddings, audio, image generation, `logprobs`.
 - **No concurrency limit per app** yet ([#54](https://github.com/jjjermiah/opencode-plugboard/issues/54), [#86](https://github.com/jjjermiah/opencode-plugboard/issues/86)).
 - **Not a gateway with its own provider keys.** It only reuses what OpenCode is logged in to.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-plugboard",
-  "version": "0.6.0",
+  "version": "0.8.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-compatible Chat Completions, Responses and model endpoints.",

package/src/anthropic/request.ts

@@ -0,0 +1,343 @@
+/**
+ * Anthropic Messages request -> neutral `PlugRequest` plus the `MessagesExchange` the response
+ * encoder needs.
+ *
+ * Pure function: no I/O. Stateless like the other front-ends: the caller sends the whole
+ * conversation in `messages`. Server tools (web search, code execution, computer use, ...) run on
+ * Anthropic's side and plugboard has no equivalent, so they are rejected with a 400
+ * `invalid_request_error` 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 { MessagesExchange } from "./response.js"
+
+type JsonObject = Record<string, unknown>
+
+export interface ParsedMessages {
+  /** 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: MessagesExchange
+  /** Variant name to try on the model (from `output_config.effort` or `thinking.budget_tokens`). */
+  readonly reasoningEffort?: string
+  /** `top_k` was sent; plugboard has no such sampling option, so it is ignored and reported. */
+  readonly topKIgnored: boolean
+}
+
+const isRecord = (value: unknown): value is JsonObject => typeof value === "object" && value !== null && !Array.isArray(value)
+
+const bad = (message: string): PlugError => ({ status: 400, kind: "invalid_request", message })
+
+/** Anthropic's own minimum for `thinking.budget_tokens`. */
+const MIN_THINKING_BUDGET = 1024
+
+/** Budget ranges -> the variant names OpenCode models commonly offer (`low`, `medium`, `high`). Unknown names are ignored by the resolver. */
+const effortOfBudget = (budget: number) => (budget <= 4096 ? "low" : budget <= 16384 ? "medium" : "high")
+
+const MEDIA_TYPE = /^[\w.+-]+\/[\w.+-]+$/
+
+/** A base64 or url `source` of an image or document block -> media part. */
+const mediaPart = (block: JsonObject, at: string, what: "image" | "document"): PlugPart | PlugError => {
+  const source = block.source
+  if (!isRecord(source)) return bad(`${at}.source: Field required`)
+  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 }
+  }
+  if (source.type === "url") {
+    if (typeof source.url !== "string" || source.url.length === 0) return bad(`${at}.source.url: must be a non-empty string`)
+    return { type: "media", url: source.url }
+  }
+  if (what === "document" && source.type === "text") {
+    if (typeof source.data !== "string") return bad(`${at}.source.data: must be a string`)
+    return { type: "text", text: source.data }
+  }
+  return bad(`${at}.source.type: "${String(source.type)}" is not supported for ${what} blocks (use base64 or url)`)
+}
+
+/** Blocks that carry nothing plugboard can replay or act on. */
+const IGNORED = new Set(["thinking", "redacted_thinking"])
+
+/** Text of a tool_result `content`: a string, or text blocks; image blocks are returned separately. */
+const toolResultContent = (content: unknown, at: string): { text: string; media: PlugPart[] } | PlugError => {
+  if (content == null) return { text: "", media: [] }
+  if (typeof content === "string") return { text: content, media: [] }
+  if (!Array.isArray(content)) return bad(`${at}.content: must be a string or an array of content blocks`)
+  const texts: string[] = []
+  const media: PlugPart[] = []
+  for (const [index, block] of content.entries()) {
+    const here = `${at}.content.${index}`
+    if (!isRecord(block)) return bad(`${here}: must be an object`)
+    if (block.type === "text" && typeof block.text === "string") texts.push(block.text)
+    else if (block.type === "image" || block.type === "document") {
+      const part = mediaPart(block, here, block.type)
+      if (isPlugError(part)) return part
+      if (part.type === "text") texts.push(part.text)
+      else media.push(part)
+    } else return bad(`${here}.type: "${String(block.type)}" is not supported in tool_result content (use text or image)`)
+  }
+  return { text: texts.join("\n"), media }
+}
+
+/** Plain content blocks (text, image, document) of a user message, in order. */
+const userBlock = (block: JsonObject, at: string): PlugPart | undefined | PlugError => {
+  switch (block.type) {
+    case "text":
+      if (typeof block.text !== "string") return bad(`${at}.text: must be a string`)
+      return block.text.length > 0 ? { type: "text", text: block.text } : undefined
+    case "image":
+    case "document":
+      return mediaPart(block, at, block.type)
+    default:
+      return bad(`${at}.type: "${String(block.type)}" is not supported in user messages (use text, image, document or tool_result)`)
+  }
+}
+
+const parseMessages = (raw: unknown): PlugMessage[] | PlugError => {
+  if (raw == null) return bad("messages: Field required")
+  if (!Array.isArray(raw) || raw.length === 0) return bad("messages: must be a non-empty array")
+  const messages: PlugMessage[] = []
+  const toolNames = new Map<string, string>()
+
+  for (const [index, message] of raw.entries()) {
+    const at = `messages.${index}`
+    if (!isRecord(message)) return bad(`${at}: must be an object`)
+    if (message.role !== "user" && message.role !== "assistant") return bad(`${at}.role: must be "user" or "assistant" (put system prompts in the top-level system field)`)
+    const content = message.content
+    if (content == null) return bad(`${at}.content: Field required`)
+    const blocks: unknown[] = typeof content === "string" ? [{ type: "text", text: content }] : Array.isArray(content) ? content : []
+    if (typeof content !== "string" && !Array.isArray(content)) return bad(`${at}.content: must be a string or an array of content blocks`)
+
+    if (message.role === "assistant") {
+      const parts: PlugPart[] = []
+      for (const [i, block] of blocks.entries()) {
+        const here = `${at}.content.${i}`
+        if (!isRecord(block)) return bad(`${here}: must be an object`)
+        if (typeof block.type === "string" && IGNORED.has(block.type)) continue
+        if (block.type === "text") {
+          if (typeof block.text !== "string") return bad(`${here}.text: must be a string`)
+          if (block.text.length > 0) parts.push({ type: "text", text: block.text })
+        } else if (block.type === "tool_use") {
+          if (typeof block.id !== "string" || block.id.length === 0) return bad(`${here}.id: Field required`)
+          if (typeof block.name !== "string" || block.name.length === 0) return bad(`${here}.name: Field required`)
+          if (block.input != null && !isRecord(block.input)) return bad(`${here}.input: must be an object`)
+          toolNames.set(block.id, block.name)
+          parts.push({ type: "tool-call", id: block.id, name: block.name, input: block.input ?? {} })
+        } else return bad(`${here}.type: "${String(block.type)}" is not supported in assistant messages (use text or tool_use)`)
+      }
+      if (parts.length > 0) messages.push({ role: "assistant", content: parts })
+      continue
+    }
+
+    // A user turn: text, images and documents, plus tool_result blocks that answer the previous
+    // assistant turn. Each result becomes its own `tool` message; images inside results (which a
+    // tool message cannot carry) follow the results as user media.
+    let user: PlugPart[] = []
+    let hoisted: PlugPart[] = []
+    const flushUser = () => {
+      if (user.length > 0) messages.push({ role: "user", content: user })
+      user = []
+    }
+    const takeHoisted = () => {
+      if (hoisted.length === 0) return
+      user.push({ type: "text", text: "Images returned by the tool calls above:" }, ...hoisted)
+      hoisted = []
+    }
+    for (const [i, block] of blocks.entries()) {
+      const here = `${at}.content.${i}`
+      if (!isRecord(block)) return bad(`${here}: must be an object`)
+      if (block.type === "tool_result") {
+        if (typeof block.tool_use_id !== "string" || block.tool_use_id.length === 0) return bad(`${here}.tool_use_id: Field required`)
+        const name = toolNames.get(block.tool_use_id)
+        if (name === undefined) return bad(`${here}.tool_use_id: "${block.tool_use_id}" matches no tool_use block in an earlier assistant message`)
+        const result = toolResultContent(block.content, here)
+        if (isPlugError(result)) return result
+        flushUser()
+        messages.push({
+          role: "tool",
+          content: [{ type: "tool-result", id: block.tool_use_id, name, result: result.text, ...(block.is_error === true ? { isError: true } : {}) }],
+        })
+        hoisted.push(...result.media)
+        continue
+      }
+      takeHoisted()
+      const part = userBlock(block, here)
+      if (isPlugError(part)) return part
+      if (part) user.push(part)
+    }
+    takeHoisted()
+    flushUser()
+  }
+  if (messages.length === 0) return bad("messages: no non-empty content")
+  return messages
+}
+
+/** `system`: a string or text blocks (`cache_control` is accepted and ignored). */
+const parseSystem = (raw: unknown): string[] | PlugError => {
+  if (raw == null) return []
+  if (typeof raw === "string") return raw.length > 0 ? [raw] : []
+  if (!Array.isArray(raw)) return bad("system: must be a string or an array of text blocks")
+  const system: string[] = []
+  for (const [index, block] of raw.entries()) {
+    if (!isRecord(block) || block.type !== "text" || typeof block.text !== "string") return bad(`system.${index}: must be a text block`)
+    if (block.text.length > 0) system.push(block.text)
+  }
+  return system
+}
+
+const parseTools = (raw: unknown): PlugTool[] | PlugError => {
+  if (raw == null) return []
+  if (!Array.isArray(raw)) return bad("tools: must be an array")
+  const tools: PlugTool[] = []
+  const names = new Set<string>()
+  for (const [index, entry] of raw.entries()) {
+    const at = `tools.${index}`
+    if (!isRecord(entry)) return bad(`${at}: must be an object`)
+    if (entry.type != null && entry.type !== "custom")
+      return bad(
+        `${at}.type: "${String(entry.type)}" is not supported. Only custom tools with an input_schema are: server tools (web_search, web_fetch, code_execution, ...) run on Anthropic's side, and computer use, bash and text editor tools are not available through plugboard`,
+      )
+    if (typeof entry.name !== "string" || entry.name.length === 0) return bad(`${at}.name: Field required`)
+    if (names.has(entry.name)) return bad(`${at}.name: duplicate tool name "${entry.name}"`)
+    if (entry.description != null && typeof entry.description !== "string") return bad(`${at}.description: must be a string`)
+    if (!isRecord(entry.input_schema)) return bad(`${at}.input_schema: Field required (a JSON Schema object)`)
+    names.add(entry.name)
+    tools.push({ name: entry.name, description: typeof entry.description === "string" ? entry.description : "", parameters: entry.input_schema })
+  }
+  return tools
+}
+
+const parseToolChoice = (raw: unknown): PlugToolChoice | undefined | PlugError => {
+  if (raw == null) return undefined
+  if (!isRecord(raw)) return bad("tool_choice: must be an object")
+  switch (raw.type) {
+    case "auto":
+      return "auto"
+    case "any":
+      return "required"
+    case "none":
+      return "none"
+    case "tool":
+      if (typeof raw.name !== "string" || raw.name.length === 0) return bad("tool_choice.name: Field required")
+      return { type: "tool", name: raw.name }
+    default:
+      return bad(`tool_choice.type: must be one of auto, any, tool, none`)
+  }
+}
+
+const parseGeneration = (body: JsonObject): PlugGeneration | PlugError => {
+  const out: { -readonly [K in keyof PlugGeneration]: PlugGeneration[K] } = {}
+  if (typeof body.max_tokens !== "number" || !Number.isInteger(body.max_tokens)) {
+    return bad(body.max_tokens == null ? "max_tokens: Field required" : "max_tokens: must be an integer")
+  }
+  if (body.max_tokens < 1) return bad("max_tokens: must be at least 1")
+  out.maxTokens = body.max_tokens
+  for (const [key, field] of [
+    ["temperature", "temperature"],
+    ["top_p", "topP"],
+  ] as const) {
+    const value = body[key]
+    if (value == null) continue
+    if (typeof value !== "number" || !Number.isFinite(value)) return bad(`${key}: must be a number`)
+    if (value < 0 || value > 1) return bad(`${key}: must be between 0 and 1`)
+    out[field] = value
+  }
+  if (body.top_k != null && (typeof body.top_k !== "number" || !Number.isInteger(body.top_k) || body.top_k < 0)) return bad("top_k: must be a non-negative integer")
+  if (body.stop_sequences != null) {
+    if (!Array.isArray(body.stop_sequences) || body.stop_sequences.some((s) => typeof s !== "string" || s.length === 0))
+      return bad("stop_sequences: must be an array of non-empty strings")
+    if (body.stop_sequences.length > 0) out.stop = body.stop_sequences as string[]
+  }
+  return out
+}
+
+/** `thinking` and `output_config.effort` -> whether thinking blocks are wanted and a variant name to try. */
+const parseThinking = (body: JsonObject, maxTokens: number): { enabled: boolean; effort?: string } | PlugError => {
+  let enabled = false
+  let effort: string | undefined
+  const thinking = body.thinking
+  if (thinking != null) {
+    if (!isRecord(thinking)) return bad("thinking: must be an object")
+    if (thinking.type === "enabled") {
+      const budget = thinking.budget_tokens
+      if (typeof budget !== "number" || !Number.isInteger(budget)) return bad("thinking.budget_tokens: Field required (an integer)")
+      if (budget < MIN_THINKING_BUDGET) return bad(`thinking.budget_tokens: must be at least ${MIN_THINKING_BUDGET}`)
+      if (budget >= maxTokens) return bad("thinking.budget_tokens: must be less than max_tokens")
+      enabled = true
+      effort = effortOfBudget(budget)
+    } else if (thinking.type === "adaptive") enabled = true
+    else if (thinking.type !== "disabled") return bad('thinking.type: must be "enabled", "adaptive" or "disabled"')
+  }
+  const config = body.output_config
+  if (config != null) {
+    if (!isRecord(config)) return bad("output_config: must be an object")
+    if (config.format != null) return bad("output_config.format: structured outputs are not supported")
+    if (config.effort != null) {
+      if (typeof config.effort !== "string" || config.effort.length === 0) return bad("output_config.effort: must be a string")
+      effort = config.effort
+    }
+  }
+  return { enabled, ...(effort ? { effort } : {}) }
+}
+
+export function parseMessagesRequest(body: unknown, options: PlugboardOptions): ParsedMessages | 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: Field required")
+  if (body.stream != null && typeof body.stream !== "boolean") return bad("stream: must be a boolean")
+  if (Array.isArray(body.mcp_servers) && body.mcp_servers.length > 0) return bad("mcp_servers: not supported (MCP connectors run on Anthropic's side)")
+
+  const generation = parseGeneration(body)
+  if (isPlugError(generation)) return generation
+  // Claude Code sends a `system` role message for models it doesn't know (any non-Claude id), which the real API
+  // would reject. Lift those into the system prompt so any OpenCode model works behind Claude Code.
+  const rawMessages: unknown = body.messages
+  const lifted = Array.isArray(rawMessages) ? rawMessages.filter((m) => isRecord(m) && m.role === "system") : []
+  const messages = parseMessages(Array.isArray(rawMessages) && lifted.length > 0 ? rawMessages.filter((m) => !lifted.includes(m)) : rawMessages)
+  if (isPlugError(messages)) return messages
+  const base = parseSystem(body.system)
+  if (isPlugError(base)) return base
+  const extra: string[] = []
+  for (const m of lifted) {
+    const s = parseSystem((m as Record<string, unknown>).content)
+    if (isPlugError(s)) return s
+    extra.push(...s)
+  }
+  const system = [...base, ...extra]
+  const tools = parseTools(body.tools)
+  if (isPlugError(tools)) return tools
+  const toolChoice = parseToolChoice(body.tool_choice)
+  if (isPlugError(toolChoice)) return toolChoice
+  const thinking = parseThinking(body, generation.maxTokens ?? 1)
+  if (isPlugError(thinking)) return thinking
+
+  if (tools.length > options.maxTools) return bad(`tools: ${tools.length} tools; plugboard allows ${options.maxTools} (option \`maxTools\`)`)
+  if (toolChoice !== undefined && toolChoice !== "none" && toolChoice !== "auto" && tools.length === 0) return bad("tool_choice: needs at least one tool in tools")
+  if (typeof toolChoice === "object" && !tools.some((tool) => tool.name === toolChoice.name))
+    return bad(`tool_choice.name: "${toolChoice.name}" is not in tools`)
+
+  const request: Omit<PlugRequest, "ref"> = {
+    model: body.model,
+    system,
+    messages,
+    tools,
+    ...(toolChoice && tools.length > 0 ? { toolChoice } : {}),
+    generation,
+  }
+  return {
+    request,
+    exchange: { model: body.model, stream: body.stream === true, thinking: thinking.enabled },
+    ...(thinking.effort ? { reasoningEffort: thinking.effort } : {}),
+    topKIgnored: body.top_k != null,
+  }
+}

package/src/anthropic/response.ts

@@ -0,0 +1,221 @@
+/**
+ * Neutral results -> Anthropic Messages wire objects: one message object, or the named SSE
+ * events of a stream, plus the Anthropic error body.
+ *
+ * One state machine (`runMessage`) serves both: it emits stream events as it goes and returns the
+ * final message, so the JSON body and the stream never disagree. A non-streaming call passes a
+ * no-op `emit`. Thinking blocks are produced only when the request asked for thinking.
+ */
+import type { PlugError, PlugEvent, PlugFinish, PlugUsage } from "../contract.js"
+
+type ToolCall = Extract<PlugEvent, { type: "tool-call" }>
+
+/** What the encoder needs besides the model events: Messages presentation state. The request decoder produces it. */
+export interface MessagesExchange {
+  /** The model string the client sent; echoed in the message object. */
+  readonly model: string
+  readonly stream: boolean
+  /** `thinking` was enabled or adaptive: reasoning text is returned as thinking blocks. */
+  readonly thinking: boolean
+}
+
+/** A stream event as emitted: `type` is also the SSE event name. */
+export type MessagesStreamEvent = { readonly type: string } & 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 MessageRun {
+  readonly failure?: PlugError
+  /** Whether `message_start` was emitted (a streamed response is committed as a 200 SSE stream). */
+  readonly started: boolean
+  /** The final message object. */
+  readonly message?: object
+}
+
+type Block = Record<string, unknown>
+
+const newId = (prefix: string) => `${prefix}_${crypto.randomUUID().replaceAll("-", "")}`
+
+/** Host call ids are not always Anthropic-shaped; `toolu_` plus the id with unsafe characters replaced. */
+const toolId = (id: string) => (/^toolu_[A-Za-z0-9_-]+$/.test(id) ? id : `toolu_${id.replace(/[^A-Za-z0-9_-]/g, "_")}`)
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value)
+
+/** Tool input must be a JSON object; a string is parsed, anything else becomes `{}`. */
+const toolInput = (input: unknown): Record<string, unknown> => {
+  if (isRecord(input)) return input
+  if (typeof input === "string") {
+    try {
+      const parsed: unknown = JSON.parse(input)
+      if (isRecord(parsed)) return parsed
+    } catch {}
+  }
+  return {}
+}
+
+/**
+ * Anthropic's `input_tokens` excludes cached tokens, which are reported on their own, while
+ * `PlugUsage.inputTokens` includes them.
+ */
+const encodeUsage = (usage: PlugUsage | undefined) => {
+  const read = usage?.cacheReadTokens ?? 0
+  const write = usage?.cacheWriteTokens ?? 0
+  return {
+    input_tokens: Math.max(0, (usage?.inputTokens ?? 0) - read - write),
+    output_tokens: usage?.outputTokens ?? 0,
+    cache_creation_input_tokens: write,
+    cache_read_input_tokens: read,
+  }
+}
+
+const STOP_REASON: Record<Exclude<PlugFinish, "error">, string> = {
+  stop: "end_turn",
+  length: "max_tokens",
+  "tool-calls": "tool_use",
+  "content-filter": "refusal",
+}
+
+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" })
+
+/** Anthropic's error `type` for a neutral error. */
+const errorType = (error: PlugError): string => {
+  if (error.status === 413) return "request_too_large"
+  if (error.status === 529) return "overloaded_error"
+  switch (error.kind) {
+    case "invalid_request":
+      return "invalid_request_error"
+    case "authentication":
+      return "authentication_error"
+    case "permission":
+      return "permission_error"
+    case "not_found":
+      return "not_found_error"
+    case "rate_limit":
+      return "rate_limit_error"
+    case "timeout":
+      return "timeout_error"
+    default:
+      return "api_error"
+  }
+}
+
+/** `{"type":"error","error":{"type","message"}}`: the body of every error on this route, and the data of a stream `error` event. */
+export const encodeError = (error: PlugError) => ({ type: "error", error: { type: errorType(error), message: error.message } })
+
+/** SSE frame of one stream event: `event: <type>` then `data: <json>`. */
+export const sseFrame = (event: MessagesStreamEvent): string => `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`
+
+export async function runMessage(
+  events: AsyncIterable<PlugEvent>,
+  exchange: MessagesExchange,
+  emit: (event: MessagesStreamEvent) => void,
+): Promise<MessageRun> {
+  const id = newId("msg")
+  const content: Block[] = []
+  /** Blocks opened so far: the next block's `index`. */
+  let nextIndex = 0
+  let open: { kind: "text" | "thinking"; index: number; text: string } | undefined
+  let started = false
+  let pinged = false
+  let calls = 0
+  let finish: Exclude<PlugFinish, "error"> | undefined
+  let usage: PlugUsage | undefined
+  let failure: PlugError | undefined
+
+  const message = (extra: Record<string, unknown>) => ({
+    id,
+    type: "message",
+    role: "assistant",
+    model: exchange.model,
+    content,
+    stop_reason: null,
+    stop_sequence: null,
+    usage: encodeUsage(undefined),
+    ...extra,
+  })
+  const start = () => {
+    if (started) return
+    started = true
+    emit({ type: "message_start", message: message({ content: [] }) })
+  }
+  /** The first content block is followed by one `ping`, as the Anthropic API does. */
+  const ping = () => {
+    if (pinged) return
+    pinged = true
+    emit({ type: "ping" })
+  }
+  const close = () => {
+    if (!open) return
+    emit({ type: "content_block_stop", index: open.index })
+    content.push(open.kind === "text" ? { type: "text", text: open.text } : { type: "thinking", thinking: open.text, signature: "" })
+    open = undefined
+  }
+  const delta = (kind: "text" | "thinking", text: string) => {
+    if (text.length === 0) return
+    start()
+    if (open && open.kind !== kind) close()
+    if (!open) {
+      open = { kind, index: nextIndex++, text: "" }
+      emit({
+        type: "content_block_start",
+        index: open.index,
+        content_block: kind === "text" ? { type: "text", text: "" } : { type: "thinking", thinking: "", signature: "" },
+      })
+      ping()
+    }
+    open.text += text
+    emit({
+      type: "content_block_delta",
+      index: open.index,
+      delta: kind === "text" ? { type: "text_delta", text } : { type: "thinking_delta", thinking: text },
+    })
+  }
+  /** Tool calls arrive whole, so each goes out as one `input_json_delta` holding the full input. */
+  const toolCall = (call: ToolCall) => {
+    start()
+    close()
+    const index = nextIndex++
+    const toolUseId = toolId(call.id)
+    const input = toolInput(call.input)
+    emit({ type: "content_block_start", index, content_block: { type: "tool_use", id: toolUseId, name: call.name, input: {} } })
+    ping()
+    emit({ type: "content_block_delta", index, delta: { type: "input_json_delta", partial_json: JSON.stringify(input) } })
+    emit({ type: "content_block_stop", index })
+    content.push({ type: "tool_use", id: toolUseId, name: call.name, input })
+    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") {
+      if (exchange.thinking) delta("thinking", event.text)
+    } else if (event.type === "text-delta") delta("text", event.text)
+    else toolCall(event)
+  }
+
+  failure ??= finish ? undefined : noFinish()
+  if (failure) {
+    if (!started) return { failure, started }
+    // The stream is already committed: close what is open and end with an `error` event (no `message_stop`).
+    close()
+    emit(encodeError(failure))
+    return { failure, started }
+  }
+  start()
+  close()
+  ping()
+  const reason = finish === "stop" && calls > 0 ? "tool-calls" : (finish ?? "stop")
+  const final = message({ stop_reason: STOP_REASON[reason as Exclude<PlugFinish, "error">], usage: encodeUsage(usage) })
+  emit({ type: "message_delta", delta: { stop_reason: final.stop_reason, stop_sequence: null }, usage: final.usage })
+  emit({ type: "message_stop" })
+  return { started, message: final }
+}