opencode-plugboard 0.9.0 → 0.9.1

package/README.md

@@ -30,7 +30,7 @@ export PLUGBOARD_KEY_MY_APP=choose-a-long-random-string
 {
   "plugins": [
     {
-      "package": "opencode-plugboard@0.9.0",
+      "package": "opencode-plugboard@0.9.1",
       "options": {
         "keys": { "my-app": "{env:PLUGBOARD_KEY_MY_APP}" },
         "models": ["anthropic/claude-sonnet-4-6", "github-copilot/*", "opencode-go/glm-5.3-flash"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-plugboard",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "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/gemini/request.ts

@@ -0,0 +1,445 @@
+/**
+ * Gemini `generateContent` / `streamGenerateContent` request -> neutral `PlugRequest` plus the
+ * `GeminiExchange` the response encoder needs.
+ *
+ * Pure function: no I/O. The model and the stream flag come from the URL, the rest from the body.
+ * Stateless like the other front-ends: the caller sends the whole conversation in `contents`.
+ * Gemini function calls carry no id, so calls get generated ids (`call_0`, `call_1`, ...) and a
+ * `functionResponse` is paired with the earliest unanswered call of the same name (or with the
+ * call that has its `id`, when the client sends one). Hosted tools (`googleSearch`,
+ * `codeExecution`, ...) and server-side state (`cachedContent`) are rejected with a 400.
+ *
+ * Field names are read in camelCase, the form every SDK sends, and in snake_case, which the REST
+ * API also accepts.
+ */
+import type { PlugboardOptions } from "../config.js"
+import {
+  isPlugError,
+  type PlugError,
+  type PlugGeneration,
+  type PlugMessage,
+  type PlugPart,
+  type PlugRequest,
+  type PlugTool,
+  type PlugToolChoice,
+} from "../contract.js"
+import type { GeminiExchange } from "./response.js"
+
+type JsonObject = Record<string, unknown>
+
+export interface ParsedGemini {
+  /** The model call, minus the model ref the route resolves from `request.model`. */
+  readonly request: Omit<PlugRequest, "ref">
+  /** Response presentation state for the encoder; never reaches the model call. */
+  readonly exchange: GeminiExchange
+  /** From `generationConfig.thinkingConfig`: picks the model variant of that name when the model has one. */
+  readonly reasoningEffort?: string
+}
+
+/** Name of the forced tool that carries structured output (same as the other front-ends). */
+const RESPOND_TOOL = "respond"
+/** Property that carries a non-object structured answer (an array or a scalar) through the object-only `respond` tool. */
+export const WRAP_KEY = "value"
+
+/** System instruction for `responseMimeType: application/json` without a schema. */
+const JSON_OBJECT_INSTRUCTION = "Respond with a single valid JSON object only."
+
+const MAX_STOP = 5
+
+const isRecord = (value: unknown): value is JsonObject => typeof value === "object" && value !== null && !Array.isArray(value)
+
+const bad = (message: string, param?: string, code?: string): PlugError => ({
+  status: 400,
+  kind: "invalid_request",
+  message,
+  ...(code ? { code } : {}),
+  ...(param ? { param } : {}),
+})
+
+const unsupported = (message: string, param: string) => bad(message, param, "unsupported_parameter")
+
+const snake = (name: string) => name.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`)
+
+/** A field in camelCase, or snake_case when only that is present. */
+const field = (object: JsonObject, name: string): unknown => object[name] ?? object[snake(name)]
+
+// ---------------------------------------------------------------- schemas
+
+/** `format` values that mean the same in JSON Schema; the rest (`int32`, `float`, `enum`, ...) are Gemini-only. */
+const JSON_SCHEMA_FORMATS = new Set(["date-time", "date", "time", "email", "uri", "uuid", "hostname", "ipv4", "ipv6"])
+/** Gemini types int64 limits as strings. */
+const NUMERIC_STRING_KEYS = new Set(["minItems", "maxItems", "minLength", "maxLength", "minProperties", "maxProperties"])
+const COPIED_KEYS = new Set(["description", "title", "enum", "required", "pattern", "default", "minimum", "maximum"])
+
+/**
+ * Gemini `Schema` (the OpenAPI subset of `parameters` and `responseSchema`) -> JSON Schema:
+ * `OBJECT` becomes `object`, `nullable` becomes a `null` type, int64 strings become numbers, and
+ * keys JSON Schema does not have (`example`, `propertyOrdering`, Gemini-only formats) are dropped.
+ */
+export function convertSchema(schema: unknown): unknown {
+  if (!isRecord(schema)) return schema
+  const out: JsonObject = {}
+  for (const [key, value] of Object.entries(schema)) {
+    if (key === "type") {
+      if (typeof value === "string") {
+        const type = value.toLowerCase()
+        if (type !== "type_unspecified") out.type = type
+      }
+    } else if (key === "format") {
+      if (typeof value === "string" && JSON_SCHEMA_FORMATS.has(value)) out.format = value
+    } else if (key === "properties") {
+      if (isRecord(value)) out.properties = Object.fromEntries(Object.entries(value).map(([name, child]) => [name, convertSchema(child)]))
+    } else if (key === "items") {
+      out.items = convertSchema(value)
+    } else if (key === "anyOf") {
+      if (Array.isArray(value)) out.anyOf = value.map(convertSchema)
+    } else if (key === "additionalProperties") {
+      out.additionalProperties = typeof value === "boolean" ? value : convertSchema(value)
+    } else if (NUMERIC_STRING_KEYS.has(key)) {
+      const n = typeof value === "string" ? Number(value) : value
+      if (typeof n === "number" && Number.isFinite(n)) out[key] = n
+    } else if (COPIED_KEYS.has(key)) {
+      out[key] = value
+    }
+  }
+  if (schema.nullable === true && typeof out.type === "string") out.type = [out.type, "null"]
+  return out
+}
+
+/** The parameters of a function declaration as a JSON Schema object (a tool with none takes no arguments). */
+const toolParameters = (declaration: JsonObject): JsonObject | undefined => {
+  const json = field(declaration, "parametersJsonSchema")
+  if (isRecord(json)) return json
+  const schema = convertSchema(declaration.parameters)
+  if (!isRecord(schema)) return undefined
+  return schema.type === undefined || schema.type === "object" ? { type: "object", properties: {}, ...schema } : schema
+}
+
+// ---------------------------------------------------------------- contents
+
+const dataUrl = (mimeType: string, data: string) => `data:${mimeType};base64,${data}`
+
+const textOf = (value: unknown, param: string): string | PlugError => {
+  if (typeof value === "string") return value
+  if (!isRecord(value)) return bad("Expected a string or a content object with text parts", param)
+  if (typeof value.text === "string") return value.text
+  const parts = value.parts
+  if (!Array.isArray(parts)) return bad("Content needs a parts array", `${param}.parts`)
+  const texts: string[] = []
+  for (const [index, part] of parts.entries()) {
+    if (!isRecord(part) || typeof part.text !== "string") return unsupported("Only text parts are supported here", `${param}.parts[${index}]`)
+    texts.push(part.text)
+  }
+  return texts.join("\n")
+}
+
+/** `a` then `b`, with the text parts at the seam merged. */
+const joinParts = (a: ReadonlyArray<PlugPart>, b: ReadonlyArray<PlugPart>): PlugPart[] => {
+  const tail = a.at(-1)
+  const head = b[0]
+  if (tail?.type === "text" && head?.type === "text") return [...a.slice(0, -1), { type: "text", text: tail.text + head.text }, ...b.slice(1)]
+  return [...a, ...b]
+}
+
+interface Call {
+  readonly id: string
+  readonly name: string
+  answered: boolean
+}
+
+/**
+ * `contents` -> neutral messages. A model turn is one assistant message (text and calls). A user
+ * turn is one tool message per `functionResponse` (first, so each directly follows the calls it
+ * answers) and then one user message with the rest.
+ */
+const parseContents = (raw: unknown): PlugMessage[] | PlugError => {
+  if (!Array.isArray(raw) || raw.length === 0) return bad("contents must be a non-empty array", "contents")
+  const messages: PlugMessage[] = []
+  const calls: Call[] = []
+  const used = new Set<string>()
+  let counter = 0
+  const nextId = () => {
+    while (used.has(`call_${counter}`)) counter++
+    return `call_${counter}`
+  }
+
+  for (const [index, content] of raw.entries()) {
+    const param = `contents[${index}]`
+    if (!isRecord(content)) return bad("Each content must be an object", param)
+    const role = content.role ?? "user"
+    if (role !== "user" && role !== "model" && role !== "function") return bad(`Unsupported role "${String(role)}": use "user" or "model"`, `${param}.role`)
+    if (!Array.isArray(content.parts)) return bad("Each content needs a parts array", `${param}.parts`)
+
+    const parts: PlugPart[] = []
+    const results: PlugMessage[] = []
+    for (const [p, part] of content.parts.entries()) {
+      const at = `${param}.parts[${p}]`
+      if (!isRecord(part)) return bad("Each part must be an object", at)
+      const call = field(part, "functionCall")
+      const response = field(part, "functionResponse")
+      const inline = field(part, "inlineData")
+      const file = field(part, "fileData")
+      if (typeof part.text === "string") {
+        // Thought summaries from an earlier turn are not replayable context.
+        if (part.thought !== true && part.text.length > 0) parts.push({ type: "text", text: part.text })
+      } else if (call !== undefined) {
+        if (role !== "model") return bad("functionCall parts belong in a model turn", `${at}.functionCall`)
+        if (!isRecord(call) || typeof call.name !== "string" || call.name.length === 0) return bad("functionCall needs a name", `${at}.functionCall.name`)
+        const args = call.args ?? {}
+        if (!isRecord(args)) return bad("functionCall args must be an object", `${at}.functionCall.args`)
+        const id = typeof call.id === "string" && call.id.length > 0 && !used.has(call.id) ? call.id : nextId()
+        used.add(id)
+        calls.push({ id, name: call.name, answered: false })
+        parts.push({ type: "tool-call", id, name: call.name, input: args })
+      } else if (response !== undefined) {
+        if (role === "model") return bad("functionResponse parts belong in a user turn", `${at}.functionResponse`)
+        if (!isRecord(response) || typeof response.name !== "string" || response.name.length === 0)
+          return bad("functionResponse needs a name", `${at}.functionResponse.name`)
+        const wanted = typeof response.id === "string" ? response.id : undefined
+        const match =
+          (wanted !== undefined ? calls.find((c) => !c.answered && c.id === wanted) : undefined) ?? calls.find((c) => !c.answered && c.name === response.name)
+        if (!match)
+          return bad(`functionResponse "${response.name}" answers no earlier functionCall of that name (calls are paired by name and order)`, `${at}.functionResponse`)
+        match.answered = true
+        const body = response.response ?? {}
+        // The convention is {output: ...} for a result and {error: ...} for a failure.
+        const failed = isRecord(body) && body.error !== undefined && body.output === undefined
+        results.push({
+          role: "tool",
+          content: [{ type: "tool-result", id: match.id, name: match.name, result: JSON.stringify(body), ...(failed ? { isError: true } : {}) }],
+        })
+      } else if (inline !== undefined) {
+        if (role === "model") return unsupported("inlineData is not supported in a model turn", `${at}.inlineData`)
+        if (!isRecord(inline) || typeof inline.data !== "string" || typeof inline.mimeType !== "string")
+          return bad("inlineData needs mimeType and base64 data", `${at}.inlineData`)
+        parts.push({ type: "media", url: dataUrl(inline.mimeType, inline.data), mediaType: inline.mimeType })
+      } else if (file !== undefined) {
+        if (role === "model") return unsupported("fileData is not supported in a model turn", `${at}.fileData`)
+        const uri = isRecord(file) ? field(file, "fileUri") : undefined
+        if (typeof uri !== "string" || !/^https?:\/\//i.test(uri))
+          return unsupported("fileData needs an http(s) fileUri; Gemini file ids and gs:// URIs are not supported (send inlineData)", `${at}.fileData.fileUri`)
+        const mimeType = isRecord(file) ? field(file, "mimeType") : undefined
+        parts.push({ type: "media", url: uri, ...(typeof mimeType === "string" ? { mediaType: mimeType } : {}) })
+      } else if (isRecord(part) && Object.keys(part).every((key) => key === "thoughtSignature" || key === "thought_signature" || key === "thought")) {
+        // A signature-only or empty part carries nothing to replay.
+      } else {
+        const kind = Object.keys(part).find((key) => key !== "thoughtSignature" && key !== "thought_signature" && key !== "thought") ?? "unknown"
+        return unsupported(`Unsupported part "${kind}": plugboard handles text, inlineData, fileData (http), functionCall and functionResponse`, at)
+      }
+    }
+    if (role === "model") {
+      // A streamed turn replayed by an SDK arrives as one model content per chunk: they are one assistant message.
+      const last = messages.at(-1)
+      if (parts.length > 0 && last?.role === "assistant") messages[messages.length - 1] = { role: "assistant", content: joinParts(last.content, parts) }
+      else if (parts.length > 0) messages.push({ role: "assistant", content: parts })
+    } else {
+      messages.push(...results)
+      if (parts.length > 0) messages.push({ role: "user", content: parts })
+    }
+  }
+  const open = calls.find((call) => !call.answered)
+  if (open) return bad(`functionCall "${open.name}" has no functionResponse; send one for every call in the conversation`, "contents")
+  if (messages.length === 0) return bad("contents has no text, media or tool parts", "contents")
+  return messages
+}
+
+// ---------------------------------------------------------------- tools
+
+/** Tool types that run on Google's side; plugboard only hands function calls back to the caller. */
+const HOSTED = ["googleSearch", "googleSearchRetrieval", "codeExecution", "urlContext", "retrieval", "fileSearch", "googleMaps", "computerUse", "mcpServers", "enterpriseWebSearch"]
+
+const parseTools = (raw: unknown): PlugTool[] | PlugError => {
+  if (raw == null) return []
+  if (!Array.isArray(raw)) return bad("tools must be an array", "tools")
+  const tools: PlugTool[] = []
+  const names = new Set<string>()
+  for (const [index, entry] of raw.entries()) {
+    const at = `tools[${index}]`
+    if (!isRecord(entry)) return bad("Each tool must be an object", at)
+    const hosted = HOSTED.find((key) => field(entry, key) !== undefined)
+    if (hosted)
+      return unsupported(`Unsupported tool "${hosted}": only functionDeclarations are supported (Google's built-in tools run on Google's servers)`, `${at}.${hosted}`)
+    const declarations = field(entry, "functionDeclarations")
+    if (declarations === undefined) {
+      const other = Object.keys(entry)[0]
+      if (other !== undefined) return unsupported(`Unsupported tool "${other}": only functionDeclarations are supported`, `${at}.${other}`)
+      continue
+    }
+    if (!Array.isArray(declarations)) return bad("functionDeclarations must be an array", `${at}.functionDeclarations`)
+    for (const [i, declaration] of declarations.entries()) {
+      const param = `${at}.functionDeclarations[${i}]`
+      if (!isRecord(declaration) || typeof declaration.name !== "string" || declaration.name.length === 0) return bad('Each function declaration needs a "name"', `${param}.name`)
+      if (names.has(declaration.name)) return bad(`Duplicate tool name "${declaration.name}"`, `${param}.name`)
+      if (declaration.description != null && typeof declaration.description !== "string") return bad("Tool description must be a string", `${param}.description`)
+      names.add(declaration.name)
+      tools.push({
+        name: declaration.name,
+        description: typeof declaration.description === "string" ? declaration.description : "",
+        parameters: toolParameters(declaration) ?? { type: "object", properties: {} },
+      })
+    }
+  }
+  return tools
+}
+
+/**
+ * `toolConfig.functionCallingConfig`: AUTO -> auto, NONE -> none, ANY -> required, and
+ * `allowedFunctionNames` narrows the tools offered (one name with ANY forces that tool).
+ */
+const parseToolConfig = (raw: unknown, tools: PlugTool[]): { tools: PlugTool[]; toolChoice?: PlugToolChoice } | PlugError => {
+  if (raw == null) return { tools }
+  if (!isRecord(raw)) return bad("toolConfig must be an object", "toolConfig")
+  const config = field(raw, "functionCallingConfig")
+  if (config == null) return { tools }
+  if (!isRecord(config)) return bad("functionCallingConfig must be an object", "toolConfig.functionCallingConfig")
+  const mode = config.mode == null ? "AUTO" : typeof config.mode === "string" ? config.mode.toUpperCase() : undefined
+  if (mode === undefined || !["AUTO", "ANY", "NONE", "VALIDATED", "MODE_UNSPECIFIED"].includes(mode))
+    return bad(`Unsupported functionCallingConfig mode "${String(config.mode)}": use AUTO, ANY or NONE`, "toolConfig.functionCallingConfig.mode")
+  const allowed = field(config, "allowedFunctionNames")
+  if (allowed != null && (!Array.isArray(allowed) || !allowed.every((name) => typeof name === "string")))
+    return bad("allowedFunctionNames must be an array of strings", "toolConfig.functionCallingConfig.allowedFunctionNames")
+  let offered = tools
+  if (Array.isArray(allowed) && allowed.length > 0 && mode !== "NONE") {
+    const missing = allowed.find((name) => !tools.some((tool) => tool.name === name))
+    if (missing !== undefined) return bad(`allowedFunctionNames names "${missing}", which is not in tools`, "toolConfig.functionCallingConfig.allowedFunctionNames")
+    offered = tools.filter((tool) => allowed.includes(tool.name))
+  }
+  if (mode === "NONE") return { tools, toolChoice: "none" }
+  if (mode === "ANY") {
+    if (offered.length === 1 && Array.isArray(allowed) && allowed.length > 0) return { tools: offered, toolChoice: { type: "tool", name: offered[0]!.name } }
+    return { tools: offered, toolChoice: "required" }
+  }
+  return { tools: offered, toolChoice: "auto" }
+}
+
+// ---------------------------------------------------------------- generation
+
+/** `thinkingConfig` -> the variant name to try: `thinkingLevel` as is, or a `thinkingBudget` bucketed into none/low/medium/high. */
+const effortOf = (config: unknown): string | undefined => {
+  if (!isRecord(config)) return undefined
+  const level = field(config, "thinkingLevel")
+  if (typeof level === "string" && level.length > 0 && level.toUpperCase() !== "THINKING_LEVEL_UNSPECIFIED") return level.toLowerCase()
+  const budget = field(config, "thinkingBudget")
+  if (typeof budget !== "number" || !Number.isFinite(budget) || budget < 0) return undefined
+  return budget === 0 ? "none" : budget <= 1024 ? "low" : budget <= 8192 ? "medium" : "high"
+}
+
+const parseGeneration = (config: JsonObject): PlugGeneration | PlugError => {
+  const out: { -readonly [K in keyof PlugGeneration]: PlugGeneration[K] } = {}
+  for (const [key, to, min, max, integer] of [
+    ["temperature", "temperature", 0, 2, false],
+    ["topP", "topP", 0, 1, false],
+    ["presencePenalty", "presencePenalty", -2, 2, false],
+    ["frequencyPenalty", "frequencyPenalty", -2, 2, false],
+    ["maxOutputTokens", "maxTokens", 1, Number.MAX_SAFE_INTEGER, true],
+  ] as const) {
+    const value = field(config, key)
+    if (value == null) continue
+    const param = `generationConfig.${key}`
+    if (typeof value !== "number" || !Number.isFinite(value)) return bad(`${key} must be a number`, param)
+    if (integer && !Number.isInteger(value)) return bad(`${key} must be an integer`, param)
+    if (value < min || value > max) return bad(max === Number.MAX_SAFE_INTEGER ? `${key} must be at least ${min}` : `${key} must be between ${min} and ${max}`, param)
+    out[to] = value
+  }
+  const stop = field(config, "stopSequences")
+  if (stop != null) {
+    if (!Array.isArray(stop) || !stop.every((s) => typeof s === "string")) return bad("stopSequences must be an array of strings", "generationConfig.stopSequences")
+    if (stop.length > MAX_STOP) return bad(`stopSequences takes at most ${MAX_STOP} sequences`, "generationConfig.stopSequences")
+    if (stop.length > 0) out.stop = stop as string[]
+  }
+  return out
+}
+
+/** `responseMimeType` / `responseSchema` / `responseJsonSchema`: same outcomes as `response_format` in the other front-ends. */
+const parseResponseFormat = (config: JsonObject): { structured?: PlugTool; wrap?: boolean; instruction?: string } | PlugError => {
+  const mime = field(config, "responseMimeType")
+  const schema = field(config, "responseJsonSchema") ?? field(config, "responseSchema")
+  if (mime != null && typeof mime !== "string") return bad("responseMimeType must be a string", "generationConfig.responseMimeType")
+  if (mime !== undefined && mime !== null && mime !== "" && mime !== "text/plain" && mime !== "application/json")
+    return unsupported(`Unsupported responseMimeType "${mime}": use application/json or text/plain`, "generationConfig.responseMimeType")
+  if (schema == null) return mime === "application/json" ? { instruction: JSON_OBJECT_INSTRUCTION } : {}
+  if (!isRecord(schema)) return bad("responseSchema must be a schema object", "generationConfig.responseSchema")
+  const converted = field(config, "responseJsonSchema") !== undefined ? schema : (convertSchema(schema) as JsonObject)
+  // The `respond` tool takes an object; an array or scalar answer travels under one property and is unwrapped.
+  const wrap = converted.type !== undefined && converted.type !== "object"
+  return {
+    wrap,
+    structured: {
+      name: RESPOND_TOOL,
+      description: "Give your final answer by calling this tool with JSON matching its schema.",
+      parameters: wrap ? { type: "object", properties: { [WRAP_KEY]: converted }, required: [WRAP_KEY] } : converted,
+    },
+  }
+}
+
+/** Fields that need server-side state or features plugboard does not have. */
+const checkUnsupported = (body: JsonObject, config: JsonObject): PlugError | undefined => {
+  if (field(body, "cachedContent") != null) return unsupported("cachedContent is not supported: plugboard is stateless, send the full contents", "cachedContent")
+  const count = field(config, "candidateCount")
+  if (count != null) {
+    if (typeof count !== "number" || !Number.isInteger(count) || count < 1) return bad("candidateCount must be a positive integer", "generationConfig.candidateCount")
+    if (count > 1) return unsupported("Only candidateCount 1 is supported", "generationConfig.candidateCount")
+  }
+  if (field(config, "responseLogprobs") === true) return unsupported("responseLogprobs is not supported", "generationConfig.responseLogprobs")
+  const modalities = field(config, "responseModalities")
+  if (Array.isArray(modalities) && modalities.some((m) => String(m).toUpperCase() !== "TEXT"))
+    return unsupported("Only the TEXT response modality is supported", "generationConfig.responseModalities")
+}
+
+export function parseGeminiRequest(model: string, stream: boolean, body: unknown, options: PlugboardOptions): ParsedGemini | PlugError {
+  if (!isRecord(body)) return bad("Request body must be a JSON object")
+  const configRaw = field(body, "generationConfig")
+  if (configRaw != null && !isRecord(configRaw)) return bad("generationConfig must be an object", "generationConfig")
+  const config = isRecord(configRaw) ? configRaw : {}
+  const refused = checkUnsupported(body, config)
+  if (refused) return refused
+
+  const messages = parseContents(body.contents)
+  if (isPlugError(messages)) return messages
+  const instruction = field(body, "systemInstruction")
+  const system = instruction == null ? "" : textOf(instruction, "systemInstruction")
+  if (isPlugError(system)) return system
+  const declared = parseTools(body.tools)
+  if (!Array.isArray(declared)) return declared
+  const configured = parseToolConfig(field(body, "toolConfig"), declared)
+  if (isPlugError(configured)) return configured
+  const format = parseResponseFormat(config)
+  if (isPlugError(format)) return format
+  const generation = parseGeneration(config)
+  if (isPlugError(generation)) return generation
+
+  const callerTools = configured.tools
+  const toolChoice = configured.toolChoice
+  const respond = format.structured
+  if (respond && callerTools.some((tool) => tool.name === RESPOND_TOOL))
+    return bad(`A tool named "${RESPOND_TOOL}" collides with responseSchema, which plugboard answers through that name`, "tools", "reserved_tool_name")
+  if (respond && typeof toolChoice === "object")
+    return unsupported("Mode ANY with a single allowed function cannot be combined with responseSchema", "toolConfig.functionCallingConfig")
+  // Same rule as the other front-ends: with caller tools on offer the model may call one of them or
+  // `respond`, so the choice is `required`; mode NONE leaves only `respond`.
+  const withCallerTools = respond !== undefined && callerTools.length > 0 && toolChoice !== "none"
+  const tools = respond ? (withCallerTools ? [...callerTools, respond] : [respond]) : callerTools
+  if (tools.length > options.maxTools)
+    return bad(`Request has ${tools.length} tools; plugboard allows ${options.maxTools} (option \`maxTools\`)`, "tools", "too_many_tools")
+  const forced: PlugToolChoice | undefined = respond ? (withCallerTools ? "required" : { type: "tool", name: RESPOND_TOOL }) : toolChoice
+
+  const request: Omit<PlugRequest, "ref"> = {
+    model,
+    system: [...(system.length > 0 ? [system] : []), ...(format.instruction ? [format.instruction] : [])],
+    messages,
+    tools,
+    ...(forced && tools.length > 0 ? { toolChoice: forced } : {}),
+    generation,
+  }
+  const reasoningEffort = effortOf(field(config, "thinkingConfig"))
+  return {
+    request,
+    exchange: {
+      model,
+      stream,
+      ...(respond ? { structuredTool: RESPOND_TOOL, ...(format.wrap ? { wrapped: true } : {}), ...(withCallerTools ? { callerTools: true } : {}) } : {}),
+      ...(format.instruction ? { jsonObject: true } : {}),
+    },
+    ...(reasoningEffort ? { reasoningEffort } : {}),
+  }
+}

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