opencode-plugboard 0.9.0 → 0.11.0

package/src/gemini/response.ts

@@ -0,0 +1,234 @@
+/**
+ * Neutral results -> Gemini wire objects: `GenerateContentResponse` (one JSON body, or the chunks
+ * of a stream), the model list, and Google-shaped error bodies.
+ *
+ * One state machine (`runGenerate`) serves both: it emits a chunk per piece of output as it goes
+ * and returns the aggregated response, so the JSON body and the stream cannot disagree. A
+ * non-streaming call passes a no-op `emit`. Reasoning deltas are dropped (no thought parts).
+ */
+import type { PlugError, PlugErrorKind, PlugEvent, PlugFinish, PlugUsage } from "../contract.js"
+import type { ListedModel } from "../models.js"
+import { unfence } from "../openai/response.js"
+import { WRAP_KEY } from "./request.js"
+
+type ToolCall = Extract<PlugEvent, { type: "tool-call" }>
+
+/** What the encoder needs besides the model events: Gemini presentation state. The request decoder produces it. */
+export interface GeminiExchange {
+  /** The model string from the URL; echoed as `modelVersion`. */
+  readonly model: string
+  readonly stream: boolean
+  /** Name of the forced tool that carries `responseSchema` output; its input becomes the text of the answer. */
+  readonly structuredTool?: string
+  /** The schema was not an object, so the answer sits under one property of the tool input and is unwrapped. */
+  readonly wrapped?: boolean
+  /**
+   * The caller's own tools are offered next to the structured tool. A call to any of them is the
+   * response (function calls, prose and the structured answer dropped); the structured answer is
+   * the text only when the step called no caller tool.
+   */
+  readonly callerTools?: boolean
+  /** `responseMimeType: application/json` without a schema: a single code fence around JSON text is stripped. */
+  readonly jsonObject?: boolean
+}
+
+/** 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 GenerateRun {
+  readonly failure?: PlugError
+  /** Whether any chunk was emitted (a streamed response is committed as a 200 SSE stream). */
+  readonly started: boolean
+  /** The aggregated response (non-streaming body). Absent on failure. */
+  readonly response?: object
+}
+
+type Part = Record<string, unknown>
+
+// ---------------------------------------------------------------- errors, models
+
+const STATUSES: Record<PlugErrorKind, string> = {
+  invalid_request: "INVALID_ARGUMENT",
+  authentication: "UNAUTHENTICATED",
+  permission: "PERMISSION_DENIED",
+  not_found: "NOT_FOUND",
+  rate_limit: "RESOURCE_EXHAUSTED",
+  server: "INTERNAL",
+  timeout: "DEADLINE_EXCEEDED",
+}
+
+/** Google's `{error:{code,message,status,details?}}`; `code` is the HTTP status. */
+export const encodeGeminiError = (error: PlugError): object => ({
+  error: {
+    code: error.status,
+    message: error.message,
+    status: error.status === 503 ? "UNAVAILABLE" : STATUSES[error.kind],
+    ...(error.param
+      ? { details: [{ "@type": "type.googleapis.com/google.rpc.BadRequest", fieldViolations: [{ field: error.param, description: error.message }] }] }
+      : {}),
+  },
+})
+
+const encodeModel = ({ id, ref, model }: ListedModel): object => ({
+  name: `models/${id}`,
+  version: "plugboard",
+  displayName: model.name ?? id,
+  description: `${ref.providerID} model served by opencode-plugboard`,
+  ...(model.contextLimit !== undefined ? { inputTokenLimit: model.contextLimit } : {}),
+  supportedGenerationMethods: ["generateContent", "streamGenerateContent"],
+})
+
+/** `GET /v1beta/models` body (everything on one page). */
+export const encodeGeminiModelList = (models: ReadonlyArray<ListedModel>): object => ({ models: models.map(encodeModel) })
+
+/** `GET /v1beta/models/{model}` body. */
+export const encodeGeminiModel = encodeModel
+
+// ---------------------------------------------------------------- responses
+
+const FINISH_REASONS: Record<Exclude<PlugFinish, "error">, string> = {
+  stop: "STOP",
+  // Gemini reports STOP when the model ends on a function call.
+  "tool-calls": "STOP",
+  length: "MAX_TOKENS",
+  "content-filter": "SAFETY",
+}
+
+/** Gemini's candidate count excludes thoughts, which have their own field; the total is the sum. */
+const encodeUsage = (usage: PlugUsage) => {
+  const input = usage.inputTokens ?? 0
+  const output = usage.outputTokens ?? 0
+  const thoughts = usage.reasoningTokens ?? 0
+  return {
+    promptTokenCount: input,
+    candidatesTokenCount: Math.max(output - thoughts, 0),
+    totalTokenCount: input + output,
+    ...(usage.cacheReadTokens ? { cachedContentTokenCount: usage.cacheReadTokens } : {}),
+    ...(thoughts > 0 ? { thoughtsTokenCount: thoughts } : {}),
+  }
+}
+
+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 argsOf = (input: unknown): Record<string, unknown> =>
+  typeof input === "object" && input !== null && !Array.isArray(input) ? (input as Record<string, unknown>) : { value: input }
+
+/** The text of a structured answer: the tool input as JSON, or its wrapped property. */
+const structuredText = (exchange: GeminiExchange, call: ToolCall): string => {
+  const input = exchange.wrapped && typeof call.input === "object" && call.input !== null ? (call.input as Record<string, unknown>)[WRAP_KEY] : call.input
+  return typeof input === "string" && !exchange.wrapped ? input : JSON.stringify(input ?? {})
+}
+
+/**
+ * Structured-output projection, as in the other front-ends: the text is exactly the first
+ * `respond` call; prose and other calls are suppressed. Without an answer the exchange fails,
+ * except when the model stopped for `length` or `content-filter`.
+ */
+const structuredFailure = (exchange: GeminiExchange, finish: Exclude<PlugFinish, "error">, answered: boolean): PlugError | undefined =>
+  exchange.structuredTool === undefined || answered || finish === "length" || finish === "content-filter"
+    ? undefined
+    : {
+        status: 502,
+        kind: "server",
+        code: "structured_output_missing",
+        message: `The model finished without calling the \`${exchange.structuredTool}\` tool, so there is no structured output`,
+      }
+
+export async function runGenerate(events: AsyncIterable<PlugEvent>, exchange: GeminiExchange, emit: (chunk: object) => void): Promise<GenerateRun> {
+  const responseId = crypto.randomUUID().replaceAll("-", "").slice(0, 22)
+  const envelope = (parts: Part[], extra: Record<string, unknown> = {}, candidate: Record<string, unknown> = {}) => ({
+    candidates: [{ content: { role: "model", parts }, ...candidate, index: 0 }],
+    ...extra,
+    modelVersion: exchange.model,
+    responseId,
+  })
+
+  /** The aggregated parts: adjacent text merges into one part. */
+  const parts: Part[] = []
+  let started = false
+  let calls = 0
+  let answered = false
+  /** With caller tools offered the structured answer waits for the finish: a caller tool call in the same step replaces it. */
+  let held: ToolCall | undefined
+  let finish: Exclude<PlugFinish, "error"> | undefined
+  let usage: PlugUsage | undefined
+  let failure: PlugError | undefined
+
+  const push = (part: Part) => {
+    started = true
+    const last = parts.at(-1)
+    if (typeof part.text === "string" && last && typeof last.text === "string") last.text += part.text
+    else parts.push(part)
+    emit(envelope([part]))
+  }
+  const text = (delta: string) => {
+    if (delta.length > 0) push({ text: delta })
+  }
+  const toolCall = (call: ToolCall) => {
+    push({ functionCall: { name: call.name, args: argsOf(call.input) } })
+    calls++
+  }
+  // json_object: text that opens with a backtick may be a fenced answer, so it waits until a tool
+  // call or the finish shows the whole text; anything else streams as it comes.
+  let pending = ""
+  let passing = false
+  const flush = () => {
+    if (pending.length === 0) return
+    const out = unfence(pending)
+    pending = ""
+    text(out)
+  }
+
+  for await (const event of events) {
+    if (event.type === "error") {
+      failure = event.error
+      break
+    }
+    if (event.type === "finish") {
+      usage = event.usage ?? usage
+      if (event.reason === "error") failure ??= failedRun()
+      else finish = event.reason
+      continue
+    }
+    if (event.type === "reasoning-delta") continue
+    if (exchange.structuredTool !== undefined) {
+      // Structured mode: only the first answer is content; prose and other tool calls are
+      // suppressed, except the caller's own tools when they are offered.
+      if (event.type === "tool-call" && event.name === exchange.structuredTool) {
+        if (!answered) {
+          answered = true
+          if (exchange.callerTools) held = event
+          else text(structuredText(exchange, event))
+        }
+        continue
+      }
+      if (!(exchange.callerTools && event.type === "tool-call")) continue
+    }
+    if (exchange.jsonObject && event.type === "text-delta" && !passing) {
+      pending += event.text
+      const lead = pending.trimStart()
+      if (lead.length > 0 && !lead.startsWith("`")) {
+        passing = true
+        flush()
+      }
+      continue
+    }
+    if (event.type !== "text-delta") flush()
+    if (event.type === "text-delta") text(event.text)
+    else toolCall(event)
+  }
+
+  const passthrough = exchange.callerTools === true && calls > 0
+  failure ??= finish ? (passthrough ? undefined : structuredFailure(exchange, finish, answered)) : noFinish()
+  if (failure) return { failure, started }
+  flush()
+  if (held && !passthrough) text(structuredText(exchange, held))
+  const candidate = { finishReason: FINISH_REASONS[finish!] }
+  const extra = usage ? { usageMetadata: encodeUsage(usage) } : {}
+  // The last chunk carries the finish reason and usage, with an empty text part as Google's does.
+  emit(envelope([{ text: "" }], extra, candidate))
+  started = true
+  return { started, response: envelope(parts.length > 0 ? parts : [{ text: "" }], extra, candidate) }
+}
+
+/** SSE frame of one stream chunk (`alt=sse`): `data: <json>`, no event name and no `[DONE]`. */
+export const sseChunk = (chunk: object): string => `data: ${JSON.stringify(chunk)}\n\n`

package/src/gemini/route.ts

@@ -0,0 +1,163 @@
+/**
+ * The Gemini front-end's half of the route: `GET /v1beta/models`, `GET /v1beta/models/{model}`,
+ * `POST /v1beta/models/{model}:generateContent` and `:streamGenerateContent?alt=sse` (and the
+ * `POST /v1/models/{model}:...` spelling). `src/openai/route.ts` matches the path
+ * (`matchGeminiRoute`), checks the origin, authenticates (`geminiAuthorization` supplies the
+ * credential) and hands over here; errors on these routes use Google's body (`encodeGeminiError`).
+ *
+ * The `{model}` segment is an alias or `provider/model[#variant]`, percent-decoded. Ids contain `/`
+ * and `#`: a literal `/` works, a `#` must be sent as `%23` (SDKs build the URL as a string, so
+ * `#` is cut as a fragment there; use an alias).
+ *
+ * Same flow as the other front-ends: parse, resolve the model, call the ModelCaller, encode. Nothing
+ * is committed until the encoder emits its first chunk, so a failure before any output is a real
+ * HTTP error even for a stream.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http"
+import { isPlugError, type PlugError, type PlugRequest } from "../contract.js"
+import { boundEvents, checkJsonContentType, readJsonBody, sendJson, sseWriter, type RequestScope } from "../http.js"
+import { listAvailableModels, resolveModel } from "../models.js"
+import type { RouteHost } from "../openai/route.js"
+import { dropRejected } from "../openai/sampling.js"
+import { parseGeminiRequest } from "./request.js"
+import { encodeGeminiError, encodeGeminiModel, encodeGeminiModelList, runGenerate, sseChunk } from "./response.js"
+
+const SESSION_HEADER = "x-plugboard-session"
+const DROPPED_HEADER = "x-plugboard-dropped-params"
+
+export type GeminiMatch =
+  | { readonly op: "list"; readonly route: string }
+  | { readonly op: "get"; readonly route: string; readonly model: string }
+  | { readonly op: "generate"; readonly route: string; readonly model: string; readonly stream: boolean }
+  /** A method on a model that plugboard does not serve (`countTokens`, `embedContent`, ...). */
+  | { readonly op: "unsupported"; readonly route: string; readonly verb: string }
+
+const decode = (raw: string): string | undefined => {
+  try {
+    return decodeURIComponent(raw)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Recognises the Gemini paths. `GET /v1/models...` stays with the OpenAI routes: only `POST`
+ * with a `:method` suffix is claimed under `/v1/`. Logs get the `route` label, never the path.
+ */
+export function matchGeminiRoute(method: string | undefined, path: string): GeminiMatch | undefined {
+  if (path === "/v1beta/models") return method === "GET" ? { op: "list", route: "GET /v1beta/models" } : undefined
+  for (const prefix of ["/v1beta/models/", "/v1/models/"]) {
+    if (!path.startsWith(prefix) || path.length === prefix.length) continue
+    const rest = path.slice(prefix.length)
+    if (method === "GET") {
+      if (prefix === "/v1/models/") return undefined
+      const model = decode(rest)
+      return model === undefined ? undefined : { op: "get", route: "GET /v1beta/models/{model}", model }
+    }
+    if (method !== "POST") return undefined
+    // The method is after the last colon; ids may contain colons themselves (`llama3:8b`).
+    const colon = rest.lastIndexOf(":")
+    const verb = colon > 0 ? rest.slice(colon + 1) : ""
+    const model = decode(rest.slice(0, colon))
+    if (!/^[A-Za-z]+$/.test(verb) || model === undefined) return undefined
+    const label = `POST ${prefix.slice(0, -1)}/{model}:${verb}`
+    if (verb === "generateContent" || verb === "streamGenerateContent")
+      return { op: "generate", route: label, model: model.startsWith("models/") ? model.slice(7) : model, stream: verb === "streamGenerateContent" }
+    return { op: "unsupported", route: label, verb }
+  }
+  return undefined
+}
+
+/**
+ * The credential in the form `authenticate` reads: `Authorization` as sent, else the Gemini key
+ * as `x-goog-api-key` or the `key` query parameter. Query strings end up in proxy and access
+ * logs; plugboard never logs the URL, but prefer the header.
+ */
+export function geminiAuthorization(request: IncomingMessage, url: URL): string | undefined {
+  if (request.headers.authorization !== undefined) return request.headers.authorization
+  const key = request.headers["x-goog-api-key"] ?? url.searchParams.get("key")
+  return typeof key === "string" && key.length > 0 ? `Bearer ${key}` : undefined
+}
+
+export interface GeminiCall {
+  readonly match: GeminiMatch
+  readonly request: IncomingMessage
+  readonly url: URL
+  readonly app: string
+  readonly response: ServerResponse
+  readonly scope: RequestScope
+  /** The route's log fields: the resolved model, and the outcome of a stream that failed after it committed. */
+  readonly info: { model?: string; failed?: string; dropped?: string }
+}
+
+export async function serveGemini(host: RouteHost, { match, request, url, app, response, scope, info }: GeminiCall): Promise<void> {
+  const fail = (error: PlugError) => sendJson(response, error.status, encodeGeminiError(error))
+
+  if (match.op === "unsupported")
+    return fail({ status: 404, kind: "not_found", code: "method_not_supported", message: `Method ${match.verb} is not supported; plugboard serves generateContent and streamGenerateContent` })
+
+  if (match.op === "list" || match.op === "get") {
+    const listed = listAvailableModels(host.options, await scope.race(host.loadCatalog()))
+    if (match.op === "list") return sendJson(response, 200, encodeGeminiModelList(listed))
+    const item = listed.find((m) => m.id === match.model)
+    if (!item) return fail({ status: 404, kind: "not_found", code: "model_not_found", param: "model", message: `Model ${match.model} is not available` })
+    info.model = item.id
+    return sendJson(response, 200, encodeGeminiModel(item))
+  }
+
+  if (match.stream && url.searchParams.get("alt") !== "sse")
+    return fail({ status: 400, kind: "invalid_request", code: "unsupported_parameter", param: "alt", message: "streamGenerateContent needs the query parameter alt=sse" })
+  const unsupported = checkJsonContentType(request)
+  if (unsupported) return fail(unsupported)
+  const body = await readJsonBody(request, scope.signal)
+
+  const parsed = parseGeminiRequest(match.model, match.stream, body, host.options)
+  if (isPlugError(parsed)) return fail(parsed)
+  const catalog = await scope.race(host.loadCatalog())
+  const ref = resolveModel(host.options, match.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 and reported, before any response bytes.
+  const sampled = host.options.dropUnsupportedParams ? dropRejected(ref, parsed.request.generation) : undefined
+  if (sampled && sampled.dropped.length > 0) {
+    info.dropped = sampled.dropped.join(",")
+    response.setHeader(DROPPED_HEADER, info.dropped)
+  }
+  const call: 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(call, {
+      app,
+      signal: scope.signal,
+      onRecord: (recordID) => {
+        if (response.headersSent || response.destroyed || !/^[\x21-\x7e]+$/.test(recordID)) return
+        response.setHeader(SESSION_HEADER, recordID)
+      },
+    }),
+    scope,
+  )
+
+  if (exchange.stream) {
+    const sse = sseWriter(response, scope.signal)
+    const { failure } = await runGenerate(sse.paced(events), exchange, (chunk) => sse.write(sseChunk(chunk)))
+    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
+        // Google ends a failed stream with one error object.
+        sse.write(sseChunk(encodeGeminiError(failure)))
+      }
+      if (!response.writableEnded) response.end()
+    }
+    return
+  }
+
+  const run = await runGenerate(events, exchange, () => {})
+  if (run.failure || !run.response) return fail(run.failure ?? { status: 502, kind: "server", message: "No response from the model" })
+  sendJson(response, 200, run.response)
+}

package/src/http.ts

@@ -5,6 +5,7 @@
  */
 
 import type { IncomingMessage, ServerResponse } from "node:http"
+import { raceAbort } from "./abort.js"
 import { isLoopbackHost, type PlugboardOptions } from "./config.js"
 import type { PlugError, PlugEvent } from "./contract.js"
 
@@ -49,9 +50,9 @@ export interface RequestScope {
 
 /**
  * Establishes cancellation and the deadline. Call before the first `await` of a request: a socket
- * that is already gone aborts immediately, so abandoned work never starts.
+ * that is already gone aborts immediately, so abandoned work never starts. `graceMs` is for tests.
  */
-export function beginRequest(request: IncomingMessage, response: ServerResponse, timeoutMs: number): RequestScope {
+export function beginRequest(request: IncomingMessage, response: ServerResponse, timeoutMs: number, graceMs = DEADLINE_GRACE_MS): RequestScope {
   const controller = new AbortController()
   const abort = (kind: RequestAborted["kind"]) => {
     if (!controller.signal.aborted) controller.abort(new RequestAborted(kind))
@@ -68,7 +69,7 @@ export function beginRequest(request: IncomingMessage, response: ServerResponse,
     graceTimer = setTimeout(() => {
       response.destroy()
       request.socket?.destroy()
-    }, DEADLINE_GRACE_MS)
+    }, graceMs)
     graceTimer.unref?.()
   }
   timer = setTimeout(onDeadline, Math.min(Math.max(timeoutMs, 1), MAX_TIMER_MS))
@@ -98,24 +99,7 @@ export function beginRequest(request: IncomingMessage, response: ServerResponse,
       code: "timeout",
       message: `Request timed out after ${timeoutMs} ms (option requestTimeoutMs)`,
     },
-    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)
-          },
-        )
-      })
-    },
+    race: (promise) => raceAbort(promise, signal),
     dispose,
   }
 }

package/src/openai/route.ts

@@ -36,6 +36,8 @@ import {
   sseWriter,
   type RequestScope,
 } from "../http.js"
+import { encodeGeminiError } from "../gemini/response.js"
+import { geminiAuthorization, matchGeminiRoute, serveGemini } from "../gemini/route.js"
 import { errorMessage, log, logError, withRequestId } from "../log.js"
 import { NO_APP, outcomeLabel, type Metrics } from "../metrics.js"
 import { listAvailableModels, resolveModel } from "../models.js"
@@ -111,9 +113,10 @@ export function createOpenAiRoute(routeHost: RouteHost) {
   const host: RouteHost = metrics ? { ...routeHost, caller: metered(routeHost.caller, metrics) } : routeHost
   /** Routes with a handler of their own. `GET /metrics` exists only when enabled; otherwise it is an unknown path. */
   const known = (route: string) => KNOWN_ROUTES.includes(route) || DISCOVERY_ROUTES.includes(route) || (metrics !== undefined && route === "GET /metrics")
-
+  /** Responses to Gemini routes: errors there use Google's body. */
+  const googleErrors = new WeakSet<ServerResponse>()
   const fail = (response: ServerResponse, error: PlugError, close = false) =>
-    sendJson(response, error.status, encodeError(error), { close })
+    sendJson(response, error.status, googleErrors.has(response) ? encodeGeminiError(error) : encodeError(error), { close })
 
   /** The catalog for a page that can do without it: a failure is logged and reported as absent; an abort still ends the request. */
   async function optionalCatalog(scope: RequestScope): Promise<ReadonlyArray<CatalogModel> | undefined> {
@@ -136,9 +139,11 @@ export function createOpenAiRoute(routeHost: RouteHost) {
     }
     const path = url.pathname
     const modelId = request.method === "GET" && path.startsWith(MODEL_PREFIX) && path.length > MODEL_PREFIX.length ? decodeSegment(path.slice(MODEL_PREFIX.length)) : undefined
-    const route = `${request.method} ${modelId !== undefined ? "/v1/models/{id}" : path}`
+    const gemini = matchGeminiRoute(request.method, path)
+    if (gemini) googleErrors.add(response)
+    const route = gemini?.route ?? `${request.method} ${modelId !== undefined ? "/v1/models/{id}" : path}`
     // Arbitrary client paths stay out of the log.
-    info.route = modelId !== undefined || known(route) || route === "GET /healthz" ? route : "unknown"
+    info.route = gemini || modelId !== undefined || known(route) || route === "GET /healthz" ? route : "unknown"
     // Anthropic Messages: its own error shape and x-api-key auth, so it takes the request from here.
     if (isMessagesPath(path)) return serveMessages(host, { path, request, response, scope, info })
 
@@ -164,11 +169,12 @@ export function createOpenAiRoute(routeHost: RouteHost) {
     }
 
     // Authenticate before anything reveals which routes exist: an unauthenticated caller sees 401 for every path but /healthz and the first-run pages.
-    const auth = authenticate(host.options, request.headers.authorization)
+    // Gemini clients also send the key as `x-goog-api-key` or `?key=` (see `geminiAuthorization`).
+    const auth = authenticate(host.options, gemini ? geminiAuthorization(request, url) : request.headers.authorization)
     if (isPlugError(auth)) return fail(response, auth)
     info.app = auth.app
 
-    if (modelId === undefined && !known(route)) {
+    if (!gemini && modelId === undefined && !known(route)) {
       return fail(response, {
         status: 404,
         kind: "not_found",
@@ -177,6 +183,8 @@ export function createOpenAiRoute(routeHost: RouteHost) {
       })
     }
 
+    if (gemini) return serveGemini(host, { match: gemini, request, url, app: auth.app, response, scope, info })
+
     if (route === "GET /v1/status") {
       const catalog = await optionalCatalog(scope)
       return sendJson(response, 200, buildStatus({ options: host.options, app: auth.app, runtime: runtimeStatus(), catalog }))

package/src/responses/response.ts

@@ -79,10 +79,16 @@ const structuredFailure = (exchange: ResponsesExchange, finish: Exclude<PlugFini
         message: `The model finished without calling the \`${exchange.structuredTool}\` tool, so there is no structured output`,
       }
 
+/**
+ * `committed`: whether the transport already committed a 200 stream before any event was emitted
+ * (the SSE writer does at the first reasoning event, #49). A failure then still opens the response
+ * and ends it with `response.failed`, instead of leaving the client an empty 200 stream.
+ */
 export async function runResponse(
   events: AsyncIterable<PlugEvent>,
   exchange: ResponsesExchange,
   emit: (event: ResponsesStreamEvent) => void,
+  committed: () => boolean = () => false,
 ): Promise<ResponseRun> {
   const id = newId("resp")
   const createdAt = Math.floor(Date.now() / 1000)
@@ -203,14 +209,15 @@ export async function runResponse(
   const structuredAnswer = exchange.structuredTool !== undefined && !passthrough
   failure ??= finish ? (passthrough ? undefined : structuredFailure(exchange, finish, answered)) : noFinish()
   if (failure) {
-    if (!started) return { failure, started }
+    if (!started && !committed()) return { failure, started }
+    start()
     closeMessage()
     const response = envelope("failed", items, {
       error: { code: failure.code ?? failure.kind, message: failure.message },
       ...(usage ? { usage: encodeUsage(usage) } : {}),
     })
     send("response.failed", { response })
-    return { failure, started, response }
+    return { failure, started: true, response }
   }
   start()
   if (held && structuredAnswer) text(args(held.input))

package/src/responses/route.ts

@@ -56,7 +56,7 @@ export async function serveResponses(host: RouteHost, { app, body, response, sco
 
   if (exchange.stream) {
     const sse = sseWriter(response, scope.signal)
-    const { failure } = await runResponse(sse.paced(events), exchange, (event) => sse.write(sseFrame(event)))
+    const { failure } = await runResponse(sse.paced(events), exchange, (event) => sse.write(sseFrame(event)), () => sse.started)
     if (!sse.started && !response.headersSent) {
       if (!scope.signal.aborted || scope.timedOut) fail(failure ?? { status: 502, kind: "server", message: "No response from the model" })
     } else {

package/src/runtime.ts

@@ -44,7 +44,10 @@
  */
 
 import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http"
+import { setTimeout as delay } from "node:timers/promises"
 import { Cause, Effect, Stream } from "effect"
+import stableStringify from "safe-stable-stringify"
+import { raceAbort } from "./abort.js"
 import { isPlugError, type CatalogModel, type PlugError } from "./contract.js"
 import { errorMessage, log, logError, outsideRequest, setLogFormat } from "./log.js"
 import { createMetrics, type Metrics, type RuntimeSnapshot } from "./metrics.js"
@@ -104,8 +107,8 @@ const BACKEND_POLL_MS = 25
 const BIND_RETRY_MS = 15_000
 const BIND_REMINDER_MS = 5 * 60_000
 
-/** 6: the listener retries a failed bind (new fields on `Listener`). 5: adds the metrics registry and the start time. 4: the history sweep state and the session store's register hook. 3: confirmed directories and rejected generations. */
-const VERSION = 6
+/** 7: the options fingerprint comes from safe-stable-stringify, so it must not be compared with an older one. 6: the listener retries a failed bind (new fields on `Listener`). 5: adds the metrics registry and the start time. 4: the history sweep state and the session store's register hook. 3: confirmed directories and rejected generations. */
+const VERSION = 7
 const KEY = Symbol.for("opencode-plugboard.runtime")
 
 interface Listener {
@@ -298,19 +301,9 @@ export function loadServingCatalog(fallback: () => Promise<ReadonlyArray<Catalog
   return (rt ? (preferred(rt)?.loadCatalog ?? fallback) : fallback)()
 }
 
-/** JSON with object keys sorted at every level, so equal options compare equal whatever their key order. */
+/** JSON with object keys sorted at every level, so equal options compare equal whatever their key order (undefined values are left out, as in `JSON.stringify`). */
 function canonicalJson(value: unknown): string {
-  const canonical = (item: unknown): unknown => {
-    if (Array.isArray(item)) return item.map(canonical)
-    if (typeof item !== "object" || item === null) return item
-    return Object.fromEntries(
-      Object.entries(item)
-        .filter(([, entry]) => entry !== undefined)
-        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
-        .map(([key, entry]) => [key, canonical(entry)]),
-    )
-  }
-  return JSON.stringify(canonical(value))
+  return stableStringify(value) ?? ""
 }
 
 const unavailable = (response: ServerResponse, message: string) => {
@@ -512,30 +505,8 @@ export function ensurePump(subscribe: () => Stream.Stream<unknown, unknown, neve
 
 const backendUnavailable = (message: string): PlugError => ({ status: 503, kind: "server", code: "backend_unavailable", message })
 
-/** Rejects when `signal` aborts; the underlying promise is left running (its late result or error is swallowed). */
-function abortable<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
-  return new Promise<T>((resolve, reject) => {
-    const onAbort = () => reject(new Error("aborted"))
-    if (signal.aborted) return onAbort()
-    signal.addEventListener("abort", onAbort, { once: true })
-    promise.then(
-      (value) => (signal.removeEventListener("abort", onAbort), resolve(value)),
-      (error) => (signal.removeEventListener("abort", onAbort), reject(error)),
-    )
-  })
-}
-
-const sleep = (ms: number, signal: AbortSignal) =>
-  new Promise<void>((resolve) => {
-    if (signal.aborted) return resolve()
-    const timer = setTimeout(done, ms)
-    function done() {
-      clearTimeout(timer)
-      signal.removeEventListener("abort", done)
-      resolve()
-    }
-    signal.addEventListener("abort", done, { once: true })
-  })
+/** Waits `ms`, or until `signal` aborts (which resolves, never rejects). */
+const sleep = (ms: number, signal: AbortSignal): Promise<void> => delay(ms, undefined, { signal }).catch(() => {})
 
 /** Rebuild the transforms of a generation set up before its directory was confirmed; shared by concurrent requests. */
 function activate(generation: Generation): Promise<void> {
@@ -593,7 +564,7 @@ export async function ensureBackend(
         if (!booted) {
           booted = true
           try {
-            await abortable(boot(directory), bounded)
+            await raceAbort(boot(directory), bounded)
           } catch (error) {
             if (bounded.aborted) continue
             logError("backend.boot_failed", { app, error: errorMessage(error) })
@@ -603,7 +574,7 @@ export async function ensureBackend(
         }
       } else {
         try {
-          await abortable(Promise.all(here.filter((generation) => !generation.activated).map(activate)), bounded)
+          await raceAbort(Promise.all(here.filter((generation) => !generation.activated).map(activate)), bounded)
         } catch (error) {
           if (bounded.aborted) continue
           throw error