opencode-plugboard 0.7.0 → 0.8.0

package/README.md

@@ -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 OpenAI Chat Completions (`/v1/chat/completions`), the Responses API (`/v1/responses`), the Anthropic Messages API (`/v1/messages`) 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.7.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.7.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/completions/request.ts

@@ -0,0 +1,103 @@
+/**
+ * Legacy OpenAI `POST /v1/completions` request -> neutral `PlugRequest`s plus the
+ * `CompletionsExchange` the encoders need.
+ *
+ * Pure function: no I/O. The OpenCode models are chat models, so a prompt becomes one user
+ * message and there is no system prompt, except for `suffix` (see `SUFFIX_INSTRUCTION`). A string
+ * prompt is one model call; a list of strings is one call per prompt, times `n` (capped by
+ * `maxN`). The route resolves `model` to a `ModelRef` afterwards, which is why the requests omit
+ * `ref`.
+ */
+import type { PlugboardOptions } from "../config.js"
+import { isPlugError, type PlugError, type PlugRequest } from "../contract.js"
+import { parseChoiceCount, parseGeneration } from "../openai/request.js"
+import type { CompletionsExchange } from "./response.js"
+
+export interface ParsedCompletions {
+  /** One model call per prompt, minus the model ref the route resolves from `model`. The route runs each `n` times. */
+  readonly requests: ReadonlyArray<Omit<PlugRequest, "ref">>
+  readonly n: number
+  /** Response presentation state for the encoders; never reaches the model call. */
+  readonly exchange: CompletionsExchange
+  readonly reasoningEffort?: string
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> => 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")
+
+/**
+ * `suffix` is the text that should follow the completion (insert mode). Chat models have no
+ * insert mode, so it is passed as an instruction: a best-effort mapping whose quality depends on
+ * the model, and the only case that adds a system prompt.
+ */
+const SUFFIX_INSTRUCTION = (suffix: string) =>
+  "Continue the user's text. Reply with only the text that belongs between the user's text and the following suffix, " +
+  "so that the user's text, your reply and the suffix read as one passage. Do not repeat either of them and add no commentary.\n\nSuffix:\n" +
+  suffix
+
+/** `prompt`: a string, or a list of strings. Token ids (a list of numbers or of number lists) need a tokenizer and are rejected. */
+const parsePrompts = (raw: unknown): string[] | PlugError => {
+  if (typeof raw === "string") return [raw]
+  if (!Array.isArray(raw) || raw.length === 0) return bad("prompt must be a string or a non-empty array of strings", "prompt")
+  if (raw.some((item) => typeof item === "number" || Array.isArray(item)))
+    return unsupported("Token-array prompts are not supported; send the prompt as text", "prompt")
+  if (!raw.every((item) => typeof item === "string")) return bad("prompt must be a string or an array of strings", "prompt")
+  return raw as string[]
+}
+
+export function parseCompletionsRequest(body: unknown, options: PlugboardOptions): ParsedCompletions | 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.prompt == null) return bad("prompt is required", "prompt")
+
+  if (body.logprobs != null) return unsupported("logprobs is not supported", "logprobs")
+  if (body.best_of != null) {
+    if (typeof body.best_of !== "number" || !Number.isInteger(body.best_of) || body.best_of < 1) return bad("best_of must be a positive integer", "best_of")
+    if (body.best_of > 1) return unsupported("best_of is not supported", "best_of")
+  }
+  if (body.echo != null && typeof body.echo !== "boolean") return bad("echo must be a boolean", "echo")
+  if (body.suffix != null && typeof body.suffix !== "string") return bad("suffix must be a string", "suffix")
+
+  const prompts = parsePrompts(body.prompt)
+  if (isPlugError(prompts)) return prompts
+  const n = parseChoiceCount(body, options)
+  if (isPlugError(n)) return n
+  if (prompts.length * n > options.maxN)
+    return bad(
+      `${prompts.length} prompt${prompts.length === 1 ? "" : "s"} with n=${n} make ${prompts.length * n} model calls, above the limit of ${options.maxN} (option \`maxN\`)`,
+      prompts.length > 1 ? "prompt" : "n",
+      "too_many_choices",
+    )
+  const generation = parseGeneration(body)
+  if (isPlugError(generation)) return generation
+
+  const suffix = typeof body.suffix === "string" && body.suffix.length > 0 ? body.suffix : undefined
+  const streamOptions = isRecord(body.stream_options) ? body.stream_options : {}
+  return {
+    requests: prompts.map((prompt) => ({
+      model: body.model as string,
+      system: suffix ? [SUFFIX_INSTRUCTION(suffix)] : [],
+      messages: [{ role: "user", content: [{ type: "text", text: prompt }] }],
+      tools: [],
+      generation,
+    })),
+    n,
+    exchange: {
+      model: body.model,
+      stream: body.stream === true,
+      includeUsage: streamOptions.include_usage === true,
+      perPrompt: n,
+      ...(body.echo === true ? { echo: prompts } : {}),
+    },
+    ...(typeof body.reasoning_effort === "string" ? { reasoningEffort: body.reasoning_effort } : {}),
+  }
+}

package/src/completions/response.ts

@@ -0,0 +1,147 @@
+/**
+ * Neutral results -> the legacy `text_completion` wire objects: one JSON body per choice, or SSE
+ * chunks per choice, for `src/openai/fanout.ts` to merge.
+ *
+ * Reasoning deltas and tool calls are dropped: the legacy format has neither, and the request
+ * offers no tools. `logprobs` is always null.
+ */
+import type { PlugError, PlugEvent, PlugFinish, PlugUsage } from "../contract.js"
+import type { ChoiceCodec } from "../openai/fanout.js"
+import { encodeError, type StreamChoice, type StreamResult } from "../openai/response.js"
+
+/** What the encoders need besides the model events; the request decoder produces it, the model call never sees it. */
+export interface CompletionsExchange {
+  /** The model string the client sent; echoed in every response object. */
+  readonly model: string
+  readonly stream: boolean
+  /** `stream_options.include_usage`: a final chunk with `choices: []` and the summed usage. */
+  readonly includeUsage: boolean
+  /** Choices per prompt. Choice `i` answers prompt `floor(i / perPrompt)`. */
+  readonly perPrompt: number
+  /** `echo`: each prompt, written ahead of the text of its choices. */
+  readonly echo?: ReadonlyArray<string>
+}
+
+const FINISH_REASONS: Record<Exclude<PlugFinish, "error">, string> = {
+  stop: "stop",
+  length: "length",
+  // The request offers no tools; should a model call one anyway, the turn simply stopped.
+  "tool-calls": "stop",
+  "content-filter": "content_filter",
+}
+
+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" })
+
+const now = () => Math.floor(Date.now() / 1000)
+
+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 }
+}
+
+const prefixOf = (exchange: CompletionsExchange, index: number) => exchange.echo?.[Math.floor(index / exchange.perPrompt)] ?? ""
+
+/** One choice as a complete body: `choices[0]` carries the text, `usage` the totals. */
+async function collectText(events: AsyncIterable<PlugEvent>, exchange: CompletionsExchange, index: number): Promise<{ status: number; body: object }> {
+  let text = ""
+  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 === "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) }
+  }
+  return {
+    status: 200,
+    body: {
+      id: `cmpl-${crypto.randomUUID().replaceAll("-", "").slice(0, 29)}`,
+      object: "text_completion",
+      created: now(),
+      model: exchange.model,
+      choices: [{ text: prefixOf(exchange, index) + text, index: 0, logprobs: null, finish_reason: FINISH_REASONS[finish] }],
+      ...(usage ? { usage: encodeUsage(usage) } : {}),
+    },
+  }
+}
+
+/**
+ * One choice of the shared stream. Writes this choice's text chunks and its finish chunk, never
+ * the error frame, usage chunk or `[DONE]` (see `StreamChoice`). Nothing is written before the
+ * first text, so a failure before it is still a real HTTP error.
+ */
+async function streamText(
+  events: AsyncIterable<PlugEvent>,
+  exchange: CompletionsExchange,
+  write: (chunk: string) => void,
+  choice: StreamChoice,
+): Promise<StreamResult> {
+  const chunk = (text: string, finish: string | null = null) =>
+    write(
+      `data: ${JSON.stringify({
+        id: choice.id,
+        object: "text_completion",
+        created: choice.created,
+        model: exchange.model,
+        choices: [{ text, index: choice.index, logprobs: null, finish_reason: finish }],
+      })}\n\n`,
+    )
+  let started = false
+  const start = () => {
+    if (started) return
+    started = true
+    const prefix = prefixOf(exchange, choice.index)
+    if (prefix.length > 0) chunk(prefix)
+  }
+  let finish: Exclude<PlugFinish, "error"> | undefined
+  let usage: PlugUsage | undefined
+  let failure: PlugError | undefined
+  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
+    } else if (event.type === "text-delta" && event.text.length > 0) {
+      start()
+      chunk(event.text)
+    }
+  }
+  failure ??= finish ? undefined : noFinish()
+  if (failure) return { failure, started }
+  start()
+  chunk("", FINISH_REASONS[finish!])
+  return { started, ...(usage ? { usage } : {}) }
+}
+
+export const completionsCodec = (exchange: CompletionsExchange): ChoiceCodec => ({
+  stream: exchange.stream,
+  includeUsage: exchange.includeUsage,
+  idPrefix: "cmpl-",
+  collect: (events, index) => collectText(events, exchange, index),
+  streamChoice: (events, write, choice) => streamText(events, exchange, write, choice),
+  usageChunk: (choice, usage) => ({
+    id: choice.id,
+    object: "text_completion",
+    created: choice.created,
+    model: exchange.model,
+    choices: [],
+    usage: encodeUsage(usage),
+  }),
+})

package/src/completions/route.ts

@@ -0,0 +1,54 @@
+/**
+ * `POST /v1/completions`: the legacy completions 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, drop sampling parameters the model
+ * rejects, call the ModelCaller, encode. Every request goes through `serveChoices`, a single
+ * prompt with `n` 1 being the case of one choice. Nothing is committed until the first text, so a
+ * failure before it 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 { sendJson, type RequestScope } from "../http.js"
+import { resolveModel } from "../models.js"
+import { serveChoices } from "../openai/fanout.js"
+import { encodeError } from "../openai/response.js"
+import type { RouteHost } from "../openai/route.js"
+import { dropRejected } from "../openai/sampling.js"
+import { parseCompletionsRequest } from "./request.js"
+import { completionsCodec } from "./response.js"
+
+const DROPPED_HEADER = "x-plugboard-dropped-params"
+
+export interface CompletionsCall {
+  readonly app: string
+  readonly body: unknown
+  readonly response: ServerResponse
+  readonly scope: RequestScope
+  /** The route's log fields: the resolved model, the sampling parameters dropped, and the outcome of a stream that failed after it committed. */
+  readonly info: { model?: string; failed?: string; dropped?: string }
+}
+
+export async function serveCompletions(host: RouteHost, { app, body, response, scope, info }: CompletionsCall): Promise<void> {
+  const fail = (error: PlugError) => sendJson(response, error.status, encodeError(error))
+
+  const parsed = parseCompletionsRequest(body, host.options)
+  if (isPlugError(parsed)) return fail(parsed)
+  const catalog = await scope.race(host.loadCatalog())
+  const ref = resolveModel(host.options, parsed.requests[0]!.model, catalog, parsed.reasoningEffort)
+  if (isPlugError(ref)) return fail(ref)
+  info.model = `${ref.providerID}/${ref.id}${ref.variant ? `#${ref.variant}` : ""}`
+  // Same sampling drop as Chat Completions: every prompt carries the same parameters.
+  const sampled = host.options.dropUnsupportedParams ? dropRejected(ref, parsed.requests[0]!.generation) : undefined
+  if (sampled && sampled.dropped.length > 0) {
+    info.dropped = sampled.dropped.join(",")
+    response.setHeader(DROPPED_HEADER, info.dropped)
+  }
+  // Choice `i` answers prompt `floor(i / n)`.
+  const calls: PlugRequest[] = parsed.requests.flatMap((request) =>
+    Array.from({ length: parsed.n }, (): PlugRequest => ({ ...request, ...(sampled ? { generation: sampled.generation } : {}), ref })),
+  )
+  return serveChoices(host, { app, calls, response, scope, info, codec: completionsCodec(parsed.exchange) })
+}

package/src/config.ts

@@ -14,6 +14,8 @@ export interface PlugboardOptions {
   /** Alias -> `provider/model[#variant]`. Targets must also pass the allowlist. */
   readonly aliases: Readonly<Record<string, string>>
   readonly maxTools: number
+  /** Most model calls one request may fan out to: `n` for chat completions, prompts x `n` for legacy completions. Each is a full call and a kept session. */
+  readonly maxN: number
   readonly requestTimeoutMs: number
   /**
    * Fetch http(s) image URLs server-side. Off by default: it is an SSRF vector into the host's network.
@@ -38,10 +40,11 @@ const DEFAULTS = {
   host: "127.0.0.1",
   port: 4010,
   maxTools: 32,
+  maxN: 1,
   requestTimeoutMs: 600_000,
 } as const
 
-const KNOWN = new Set(["listen", "keys", "models", "aliases", "maxTools", "requestTimeoutMs", "remoteImages", "history", "dropUnsupportedParams", "logFormat", "metrics"])
+const KNOWN = new Set(["listen", "keys", "models", "aliases", "maxTools", "maxN", "requestTimeoutMs", "remoteImages", "history", "dropUnsupportedParams", "logFormat", "metrics"])
 const HISTORY_KNOWN = new Set(["maxSessions", "maxAgeDays"])
 /** About 100 years: keeps `maxAgeDays * 86_400_000` a safe integer. */
 const MAX_AGE_DAYS = 36_500
@@ -166,6 +169,7 @@ export function parseOptions(raw: unknown): PlugboardOptions {
     models: models as string[],
     aliases,
     maxTools: positiveInt(input.maxTools, "maxTools", DEFAULTS.maxTools, 1024),
+    maxN: positiveInt(input.maxN, "maxN", DEFAULTS.maxN, 64),
     requestTimeoutMs: positiveInt(input.requestTimeoutMs, "requestTimeoutMs", DEFAULTS.requestTimeoutMs, MAX_TIMER_MS),
     remoteImages,
     history: { ...(maxSessions === undefined ? {} : { maxSessions }), ...(maxAgeDays === undefined ? {} : { maxAgeDays }) },

package/src/openai/fanout.ts

@@ -0,0 +1,278 @@
+/**
+ * Several choices for one request (`n` > 1 on Chat Completions, `n` or several prompts on legacy
+ * completions): one independent `ModelCaller` call per choice, run concurrently, each in its own
+ * session, merged into one response.
+ *
+ * Every choice is a full model call and a kept history session, which is why `maxN` caps them.
+ * The choices share nothing: no history, no seed, no ordering.
+ *
+ * Failure policy: if any choice fails, the request fails and the other choices are cancelled
+ * (their sessions are interrupted). A partial answer set would look like a complete one, and
+ * callers that sample n times for evaluation would silently average over fewer samples.
+ *   - non-stream: the first failure becomes the HTTP error.
+ *   - stream, nothing sent yet: the same HTTP error.
+ *   - stream, already committed: an `error` frame and `[DONE]`, as for a single stream.
+ * Client disconnect and the request deadline cancel every choice (the group signal includes the
+ * request's).
+ *
+ * The wire encoders stay per-choice and come in through `ChoiceCodec`: Chat Completions here,
+ * legacy completions in `src/completions/response.ts`. This module owns what is shared: the
+ * group cancellation, the merge of JSON bodies and the interleaving of SSE chunks.
+ */
+
+import type { ServerResponse } from "node:http"
+import type { PlugError, PlugEvent, PlugRequest, PlugUsage } from "../contract.js"
+import { RequestAborted, boundEvents, sendJson, sseWriter, type RequestScope } from "../http.js"
+import { chatUsageChunk, collectCompletion, encodeError, streamCompletion, type OpenAiExchange, type StreamChoice, type StreamResult } from "./response.js"
+import type { RouteHost } from "./route.js"
+
+const SESSION_HEADER = "x-plugboard-session"
+
+/** The per-choice wire encoder a front-end supplies. */
+export interface ChoiceCodec {
+  readonly stream: boolean
+  readonly includeUsage: boolean
+  /** Prefix of the shared stream id (`chatcmpl-`, `cmpl-`). */
+  readonly idPrefix: string
+  /** One choice as a complete JSON body with `choices[0]` and `usage`. */
+  collect(events: AsyncIterable<PlugEvent>, index: number): Promise<{ status: number; body: object }>
+  /** One choice of the shared stream: this choice's chunks only (see `StreamChoice`). */
+  streamChoice(events: AsyncIterable<PlugEvent>, write: (chunk: string) => void, choice: StreamChoice): Promise<StreamResult>
+  /** The final chunk with the summed usage (`include_usage`). */
+  usageChunk(choice: Omit<StreamChoice, "index">, usage: PlugUsage): object
+}
+
+/** The Chat Completions encoder as a `ChoiceCodec`. */
+export const chatCodec = (exchange: OpenAiExchange): ChoiceCodec => ({
+  stream: exchange.stream,
+  includeUsage: exchange.includeUsage,
+  idPrefix: "chatcmpl-",
+  collect: (events) => collectCompletion(events, exchange),
+  streamChoice: (events, write, choice) => streamCompletion(events, exchange, write, choice),
+  usageChunk: (choice, usage) => chatUsageChunk(exchange.model, choice.id, choice.created, usage),
+})
+
+export interface ChoicesCall {
+  readonly app: string
+  /** One resolved model call per choice, in choice order. Every entry is a full call with its own session. */
+  readonly calls: ReadonlyArray<PlugRequest>
+  readonly response: ServerResponse
+  readonly scope: RequestScope
+  /** The route's log fields: the outcome of a stream that failed after it committed. */
+  readonly info: { failed?: string }
+  readonly codec: ChoiceCodec
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value)
+
+/** A queue that is an async iterable: the encoder of one choice reads what the interleaver feeds it. */
+function channel<T>() {
+  const items: T[] = []
+  let closed = false
+  let wake: (() => void) | undefined
+  return {
+    push(item: T) {
+      items.push(item)
+      wake?.()
+    },
+    close() {
+      closed = true
+      wake?.()
+    },
+    async *[Symbol.asyncIterator](): AsyncGenerator<T> {
+      while (true) {
+        if (items.length > 0) {
+          yield items.shift()!
+          continue
+        }
+        if (closed) return
+        await new Promise<void>((resolve) => {
+          wake = resolve
+        })
+        wake = undefined
+      }
+    },
+  }
+}
+
+/** A scope whose signal also aborts when one choice fails; deadline and error stay the request's. */
+function groupScope(scope: RequestScope, signal: AbortSignal): RequestScope {
+  return {
+    signal,
+    get timedOut() {
+      return scope.timedOut
+    },
+    timeoutError: scope.timeoutError,
+    race<T>(promise: Promise<T>): Promise<T> {
+      promise.catch(() => {})
+      if (signal.aborted) return Promise.reject(signal.reason)
+      return new Promise<T>((resolve, reject) => {
+        const onAbort = () => reject(signal.reason)
+        signal.addEventListener("abort", onAbort, { once: true })
+        promise.then(
+          (value) => {
+            signal.removeEventListener("abort", onAbort)
+            resolve(value)
+          },
+          (error) => {
+            signal.removeEventListener("abort", onAbort)
+            reject(error)
+          },
+        )
+      })
+    },
+    dispose() {},
+  }
+}
+
+/** Numbers add up, objects add up per key. */
+const sumDeep = (a: unknown, b: unknown): unknown => {
+  if (typeof a === "number" && typeof b === "number") return a + b
+  if (isRecord(a) && isRecord(b)) return Object.fromEntries(Object.keys(a).map((key) => [key, sumDeep(a[key], b[key])]))
+  return a ?? b
+}
+
+/** The bodies of successful choices as one: `choices` in order with their `index`, `usage` summed, the rest from the first. */
+function mergeBodies(bodies: ReadonlyArray<object>): object {
+  const [head] = bodies as ReadonlyArray<Record<string, unknown>>
+  const choices = (bodies as ReadonlyArray<{ choices: object[] }>).map((body, index) => ({ ...body.choices[0], index }))
+  const usage = (bodies as ReadonlyArray<{ usage?: unknown }>).map((body) => body.usage).reduce((total, next) => (total === undefined ? next : sumDeep(total, next)), undefined as unknown)
+  return { ...head, choices, ...(usage === undefined ? {} : { usage }) }
+}
+
+const addUsage = (a: PlugUsage, b: PlugUsage): PlugUsage => {
+  const out: { -readonly [K in keyof PlugUsage]: PlugUsage[K] } = {}
+  for (const key of ["inputTokens", "outputTokens", "reasoningTokens", "cacheReadTokens", "cacheWriteTokens"] as const) {
+    if (a[key] !== undefined || b[key] !== undefined) out[key] = (a[key] ?? 0) + (b[key] ?? 0)
+  }
+  return out
+}
+
+export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls, response, scope, info, codec }: ChoicesCall): Promise<void> {
+  const fail = (error: PlugError) => sendJson(response, error.status, encodeError(error))
+  // Abandoned requests (client gone, deadline passed) must never reach the model caller.
+  if (scope.signal.aborted) throw scope.signal.reason
+
+  const group = new AbortController()
+  const cancel = () => group.abort(new RequestAborted("disconnected"))
+  const gscope = groupScope(scope, AbortSignal.any([scope.signal, group.signal]))
+  /** History record ids as the callers report them, in choice order, for the response header (comma separated). */
+  const records: Array<string | undefined> = []
+  const open = (index: number) =>
+    boundEvents(
+      host.caller.stream(calls[index]!, {
+        app,
+        signal: gscope.signal,
+        onRecord: (recordID) => {
+          if (response.headersSent || response.destroyed || !/^[\x21-\x7e]+$/.test(recordID)) return
+          records[index] = recordID
+          response.setHeader(SESSION_HEADER, records.filter((id) => id !== undefined).join(","))
+        },
+      }),
+      gscope,
+    )
+
+  if (!codec.stream) {
+    const results = await new Promise<Array<{ status: number; body: object }>>((resolve, reject) => {
+      const done: Array<{ status: number; body: object }> = []
+      let left = calls.length
+      calls.forEach((_, index) => {
+        codec.collect(open(index), index).then(
+          (result) => {
+            if (result.status !== 200) {
+              cancel()
+              return resolve([result])
+            }
+            done[index] = result
+            if (--left === 0) resolve(done)
+          },
+          (error) => {
+            cancel()
+            reject(error)
+          },
+        )
+      })
+    })
+    const first = results[0]!
+    return sendJson(response, first.status, results.length === 1 ? first.body : mergeBodies(results.map((result) => result.body)))
+  }
+
+  const sse = sseWriter(response, scope.signal)
+  const shared = { id: `${codec.idPrefix}${crypto.randomUUID().replaceAll("-", "").slice(0, 29)}`, created: Math.floor(Date.now() / 1000) }
+  const channels = calls.map(() => channel<PlugEvent>())
+  let failure: PlugError | undefined
+  let usage: PlugUsage | undefined
+  const runs = channels.map((events, index) =>
+    codec.streamChoice(events, sse.write, { ...shared, index }).then((result) => {
+      if (result.failure && !failure) {
+        failure = result.failure
+        cancel()
+      }
+      if (result.usage) usage = usage ? addUsage(usage, result.usage) : result.usage
+    }),
+  )
+
+  // The choice an event belongs to. Set just before it is yielded; the consumer reads it before it
+  // pulls again, so it cannot change in between.
+  let current = 0
+  /**
+   * The choices' events as one stream, so one `sse.paced` serves all: backpressure, and the
+   * keepalive commit at the first non-terminal event of any choice. At most one event per choice
+   * is pulled ahead. A choice's stream ending closes its channel.
+   */
+  async function* merged(): AsyncGenerator<PlugEvent> {
+    const iterators = calls.map((_, index) => open(index)[Symbol.asyncIterator]())
+    type Step = { index: number; result?: IteratorResult<PlugEvent>; error?: unknown; threw?: true }
+    const pending = new Map<number, Promise<Step>>()
+    const arm = (index: number) =>
+      pending.set(
+        index,
+        iterators[index]!.next().then(
+          (result): Step => ({ index, result }),
+          (error): Step => ({ index, error, threw: true }),
+        ),
+      )
+    try {
+      for (let index = 0; index < iterators.length; index++) arm(index)
+      while (pending.size > 0 && !failure) {
+        const step = await Promise.race(pending.values())
+        pending.delete(step.index)
+        if (step.threw) throw step.error
+        if (step.result!.done) {
+          channels[step.index]!.close()
+          continue
+        }
+        current = step.index
+        yield step.result!.value
+        arm(step.index)
+      }
+    } finally {
+      for (const iterator of iterators) void iterator.return?.(undefined)?.catch?.(() => {})
+      for (const events of channels) events.close()
+    }
+  }
+
+  try {
+    for await (const event of sse.paced(merged())) channels[current]!.push(event)
+  } catch (error) {
+    cancel()
+    await Promise.all(runs)
+    throw error
+  }
+  await Promise.all(runs)
+
+  if (!failure && !sse.started && !response.headersSent) failure = { status: 502, kind: "server", message: "No response from the model" }
+  if (failure) {
+    if (!sse.started && !response.headersSent) {
+      if (!scope.signal.aborted || scope.timedOut) fail(failure)
+    } else {
+      info.failed = failure.code ?? failure.kind
+      sse.write(`data: ${JSON.stringify(encodeError(failure))}\n\ndata: [DONE]\n\n`)
+      if (!response.writableEnded) response.end()
+    }
+    return
+  }
+  if (codec.includeUsage && usage) sse.write(`data: ${JSON.stringify(codec.usageChunk(shared, usage))}\n\n`)
+  sse.write("data: [DONE]\n\n")
+  if (!response.writableEnded) response.end()
+}

package/src/openai/request.ts

@@ -25,6 +25,8 @@ export interface ParsedChat {
   readonly request: Omit<PlugRequest, "ref">
   /** Response presentation state for the encoders; never reaches the model call. */
   readonly exchange: OpenAiExchange
+  /** `n`: independent model calls whose answers become `choices` (1..`maxN`). The route fans out when it is above 1. */
+  readonly n: number
   readonly reasoningEffort?: string
 }
 
@@ -226,7 +228,16 @@ const parseResponseFormat = (raw: unknown): { structured?: PlugTool; instruction
   return bad(`Unsupported response_format type "${String(raw.type)}"`, "response_format.type")
 }
 
-const parseGeneration = (body: JsonObject): PlugGeneration | PlugError => {
+/** `n` is how many completions to return. Each one is a full model call (see `src/openai/fanout.ts`), so it is capped by the `maxN` option. */
+export const parseChoiceCount = (body: JsonObject, options: PlugboardOptions): number | PlugError => {
+  if (body.n == null) return 1
+  if (typeof body.n !== "number" || !Number.isInteger(body.n) || body.n < 1) return bad("n must be a positive integer", "n")
+  if (body.n > options.maxN)
+    return bad(`n=${body.n} is above the limit of ${options.maxN} (option \`maxN\`; each choice is a full model call)`, "n", "too_many_choices")
+  return body.n
+}
+
+export 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]
@@ -265,10 +276,8 @@ export function parseChatRequest(body: unknown, options: PlugboardOptions): Pars
   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")
-  }
+  const n = parseChoiceCount(body, options)
+  if (typeof n === "object") return n
   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")
 
@@ -323,6 +332,7 @@ export function parseChatRequest(body: unknown, options: PlugboardOptions): Pars
   const streamOptions = isRecord(body.stream_options) ? body.stream_options : {}
   return {
     request,
+    n,
     exchange: {
       model: body.model,
       stream: body.stream === true,

package/src/openai/response.ts

@@ -40,6 +40,20 @@ export interface StreamResult {
   readonly failure?: PlugError
   /** Whether any frame was written (the response is committed as a 200 SSE stream). */
   readonly started: boolean
+  /** The usage the model reported, when the exchange succeeded. */
+  readonly usage?: PlugUsage
+}
+
+/**
+ * One choice of a fanned-out stream (`n` > 1, see `src/openai/fanout.ts`): the chunks share the
+ * stream's `id` and `created` and carry this choice's `index`. The encoder then writes this
+ * choice's chunks only. The error frame, the usage chunk and `[DONE]` belong to the whole
+ * stream and are written by the fan-out.
+ */
+export interface StreamChoice {
+  readonly id: string
+  readonly created: number
+  readonly index: number
 }
 
 const ERROR_TYPES: Record<PlugErrorKind, string> = {
@@ -246,6 +260,16 @@ export async function collectCompletion(
   }
 }
 
+/** The final chunk of a stream with `include_usage`: no choices, the totals. */
+export const chatUsageChunk = (model: string, id: string, created: number, usage: PlugUsage): object => ({
+  id,
+  object: "chat.completion.chunk",
+  created,
+  model,
+  choices: [],
+  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
@@ -256,9 +280,11 @@ export async function streamCompletion(
   events: AsyncIterable<PlugEvent>,
   exchange: OpenAiExchange,
   write: (chunk: string) => void,
+  choice?: StreamChoice,
 ): Promise<StreamResult> {
-  const id = newId()
-  const created = now()
+  const id = choice?.id ?? newId()
+  const created = choice?.created ?? now()
+  const index = choice?.index ?? 0
   const frame = (value: object) => write(`data: ${JSON.stringify(value)}\n\n`)
   const chunk = (delta: Record<string, unknown>, finish: string | null = null) =>
     frame({
@@ -266,7 +292,7 @@ export async function streamCompletion(
       object: "chat.completion.chunk",
       created,
       model: exchange.model,
-      choices: [{ index: 0, delta, finish_reason: finish, logprobs: null }],
+      choices: [{ index, delta, finish_reason: finish, logprobs: null }],
       ...(exchange.includeUsage ? { usage: null } : {}),
     })
 
@@ -348,16 +374,18 @@ export async function streamCompletion(
   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")
+    if (!choice) {
+      frame(encodeError(failure))
+      write("data: [DONE]\n\n")
+    }
     return { failure, started }
   }
   flush()
   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) })
+  if (choice) return { started, ...(usage ? { usage } : {}) }
+  if (exchange.includeUsage && usage) frame(chatUsageChunk(exchange.model, id, created, usage))
   write("data: [DONE]\n\n")
   return { started }
 }

package/src/openai/route.ts

@@ -1,6 +1,7 @@
 /**
  * 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`.
+ * `POST /v1/chat/completions` (`n` > 1 through `./fanout.ts`), and the dispatch of `POST /v1/responses`
+ * and `POST /v1/completions` to `src/responses/route.ts` and `src/completions/route.ts`.
  * Observability and first-run routes (`src/discovery.ts`, `src/metrics.ts`): `GET /` and `GET /v1`
  * (keyless discovery), the authenticated `GET /v1/status`, and `GET /metrics` (option `metrics`).
  *
@@ -39,8 +40,10 @@ import { errorMessage, log, logError, withRequestId } from "../log.js"
 import { NO_APP, outcomeLabel, type Metrics } from "../metrics.js"
 import { listAvailableModels, resolveModel } from "../models.js"
 import { isMessagesPath, serveMessages } from "../anthropic/route.js"
+import { serveCompletions } from "../completions/route.js"
 import { serveResponses } from "../responses/route.js"
 import { processMetrics, processStatus, type RuntimeStatus } from "../runtime.js"
+import { chatCodec, serveChoices } from "./fanout.js"
 import { parseChatRequest } from "./request.js"
 import { collectCompletion, encodeError, encodeModelList, streamCompletion } from "./response.js"
 import { dropRejected } from "./sampling.js"
@@ -61,7 +64,7 @@ const SESSION_HEADER = "x-plugboard-session"
 const REQUEST_ID_HEADER = "x-plugboard-request-id"
 const DROPPED_HEADER = "x-plugboard-dropped-params"
 const MODEL_PREFIX = "/v1/models/"
-const KNOWN_ROUTES = ["GET /v1/models", "POST /v1/chat/completions", "POST /v1/responses", "GET /v1/status"]
+const KNOWN_ROUTES = ["GET /v1/models", "POST /v1/chat/completions", "POST /v1/completions", "POST /v1/responses", "GET /v1/status"]
 /** Pages anyone may fetch; they decide for themselves how much to show (see `src/discovery.ts`). */
 const DISCOVERY_ROUTES = ["GET /", "GET /v1"]
 /** Allows a page's inline style and nothing else: no scripts, images, fonts or frames. */
@@ -205,6 +208,7 @@ export function createOpenAiRoute(routeHost: RouteHost) {
 
     const body = await readJsonBody(request, scope.signal)
     if (route === "POST /v1/responses") return serveResponses(host, { app: auth.app, body, response, scope, info })
+    if (route === "POST /v1/completions") return serveCompletions(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())
@@ -220,6 +224,9 @@ export function createOpenAiRoute(routeHost: RouteHost) {
     }
     const call: PlugRequest = { ...parsed.request, ...(sampled ? { generation: sampled.generation } : {}), ref }
     const { exchange } = parsed
+    // n > 1: one independent call per choice, merged (src/openai/fanout.ts).
+    if (parsed.n > 1)
+      return serveChoices(host, { app: auth.app, calls: Array.from({ length: parsed.n }, () => call), response, scope, info, codec: chatCodec(exchange) })
 
     // Abandoned requests (client gone, deadline passed) must never reach the model caller.
     if (scope.signal.aborted) throw scope.signal.reason