opencode-plugboard 0.6.0 → 0.8.0

package/src/anthropic/route.ts

@@ -0,0 +1,148 @@
+/**
+ * `POST /v1/messages` (and a clear 404 for `POST /v1/messages/count_tokens`): the Anthropic
+ * Messages front-end's half of the route. `src/openai/route.ts` hands every request for these
+ * paths over before it does anything else, because this route differs from the OpenAI ones in
+ * three ways: errors use Anthropic's body shape from the first check on, `x-api-key` authenticates
+ * as well as `Authorization: Bearer`, and there is no `[DONE]`.
+ *
+ * Same flow as the other front-ends: origin check, authenticate, parse, resolve the model, call
+ * the ModelCaller, encode. Nothing is committed until the encoder emits its first event, so a
+ * failure before any output is a real HTTP error even when the client asked for a stream.
+ * `anthropic-version` and `anthropic-beta` are accepted and ignored.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http"
+import { authenticate } from "../config.js"
+import { isPlugError, type PlugError, type PlugRequest } from "../contract.js"
+import {
+  BodyError,
+  RequestAborted,
+  boundEvents,
+  checkJsonContentType,
+  checkOrigin,
+  readJsonBody,
+  sendJson,
+  sseWriter,
+  type RequestScope,
+} from "../http.js"
+import { resolveModel } from "../models.js"
+import { dropRejected } from "../openai/sampling.js"
+import type { RouteHost } from "../openai/route.js"
+import { parseMessagesRequest } from "./request.js"
+import { encodeError, runMessage, sseFrame } from "./response.js"
+
+const SESSION_HEADER = "x-plugboard-session"
+const DROPPED_HEADER = "x-plugboard-dropped-params"
+const MESSAGES = "/v1/messages"
+const COUNT_TOKENS = "/v1/messages/count_tokens"
+
+/** Paths this front-end owns, whatever the method. */
+export const isMessagesPath = (path: string) => path === MESSAGES || path === COUNT_TOKENS
+
+export interface MessagesCall {
+  readonly path: string
+  readonly request: IncomingMessage
+  readonly response: ServerResponse
+  readonly scope: RequestScope
+  /** The route's log fields: the route name, the app, the resolved model, dropped parameters, and the outcome of a stream that failed after it committed. */
+  readonly info: { route: string; app?: string; model?: string; failed?: string; dropped?: string }
+}
+
+const header = (request: IncomingMessage, name: string): string | undefined => {
+  const value = request.headers[name]
+  return (Array.isArray(value) ? value[0] : value)?.trim() || undefined
+}
+
+/** `Authorization: Bearer` first (Claude Code with ANTHROPIC_AUTH_TOKEN), then `x-api-key` (the Anthropic SDKs). One key store. */
+const authenticateRequest = (host: RouteHost, request: IncomingMessage) => {
+  const bearer = authenticate(host.options, request.headers.authorization)
+  const apiKey = header(request, "x-api-key")
+  return isPlugError(bearer) && apiKey ? authenticate(host.options, `Bearer ${apiKey}`) : bearer
+}
+
+export async function serveMessages(host: RouteHost, call: MessagesCall): Promise<void> {
+  const { path, request, response, scope, info } = call
+  const fail = (error: PlugError, close = false) => sendJson(response, error.status, encodeError(error), { close })
+  if (request.method === "POST") info.route = `POST ${path}`
+  response.setHeader("request-id", `req_${crypto.randomUUID().replaceAll("-", "")}`)
+
+  try {
+    await serve()
+  } catch (caught) {
+    // Answer in this route's error shape, then rethrow: the shared handler logs the outcome and
+    // finds the response already sent.
+    if (!response.headersSent) {
+      if (caught instanceof BodyError) fail({ status: caught.status, kind: "invalid_request", message: caught.message }, caught.status === 413)
+      else if (caught instanceof RequestAborted) {
+        if (caught.kind === "timeout") fail(scope.timeoutError, true)
+      } else fail({ status: 500, kind: "server", message: "Internal server error" })
+    }
+    throw caught
+  }
+
+  async function serve(): Promise<void> {
+    if (request.method !== "POST")
+      return fail({ status: 405, kind: "invalid_request", code: "method_not_allowed", message: `Method ${request.method} is not allowed for ${path}; use POST` })
+    const rejected = checkOrigin(request, host.options)
+    if (rejected) return fail(rejected)
+    const auth = authenticateRequest(host, request)
+    if (isPlugError(auth)) return fail(auth)
+    info.app = auth.app
+    if (path === COUNT_TOKENS)
+      return fail({ status: 404, kind: "not_found", code: "not_found", message: "count_tokens is not supported by plugboard" })
+    const unsupported = checkJsonContentType(request)
+    if (unsupported) return fail(unsupported)
+
+    const body = await readJsonBody(request, scope.signal)
+    const parsed = parseMessagesRequest(body, host.options)
+    if (isPlugError(parsed)) return fail(parsed)
+    const catalog = await scope.race(host.loadCatalog())
+    const ref = resolveModel(host.options, parsed.request.model, catalog, parsed.reasoningEffort)
+    if (isPlugError(ref)) return fail(ref)
+    info.model = `${ref.providerID}/${ref.id}${ref.variant ? `#${ref.variant}` : ""}`
+    // Sampling parameters the model is known to reject are dropped; `top_k` has no neutral
+    // equivalent and is always dropped. Both are reported before any response bytes.
+    const sampled = host.options.dropUnsupportedParams ? dropRejected(ref, parsed.request.generation) : undefined
+    const dropped = [...(sampled?.dropped ?? []), ...(parsed.topKIgnored ? ["top_k"] : [])]
+    if (dropped.length > 0) {
+      info.dropped = dropped.join(",")
+      response.setHeader(DROPPED_HEADER, info.dropped)
+    }
+    const model: PlugRequest = { ...parsed.request, ...(sampled ? { generation: sampled.generation } : {}), ref }
+    const { exchange } = parsed
+
+    // Abandoned requests (client gone, deadline passed) must never reach the model caller.
+    if (scope.signal.aborted) throw scope.signal.reason
+    const events = boundEvents(
+      host.caller.stream(model, {
+        app: auth.app,
+        signal: scope.signal,
+        onRecord: (recordID) => {
+          if (response.headersSent || response.destroyed || !/^[\x21-\x7e]+$/.test(recordID)) return
+          response.setHeader(SESSION_HEADER, recordID)
+        },
+      }),
+      scope,
+    )
+
+    if (exchange.stream) {
+      const sse = sseWriter(response, scope.signal)
+      const { failure, started } = await runMessage(sse.paced(events), exchange, (event) => sse.write(sseFrame(event)))
+      if (!sse.started && !response.headersSent) {
+        if (!scope.signal.aborted || scope.timedOut) fail(failure ?? { status: 502, kind: "server", message: "No response from the model" })
+      } else {
+        if (failure) {
+          info.failed = failure.code ?? failure.kind
+          // Committed by a keepalive before the encoder wrote anything: the encoder left the error for us.
+          if (!started && !response.writableEnded) sse.write(sseFrame(encodeError(failure)))
+        }
+        if (!response.writableEnded) response.end()
+      }
+      return
+    }
+
+    const run = await runMessage(events, exchange, () => {})
+    if (run.failure || !run.message) return fail(run.failure ?? { status: 502, kind: "server", message: "No response from the model" })
+    sendJson(response, 200, run.message)
+  }
+}

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 }) },