opencode-plugboard 0.3.0 → 0.4.0

package/README.md

@@ -105,6 +105,7 @@ Options live under `options` in the plugin entry. `{env:VAR}` is expanded by Ope
 | `maxTools` | `32` | Most tools one request may carry. Fixed when the plugin loads. |
 | `requestTimeoutMs` | `600000` | A request that runs longer is interrupted. |
 | `history` | none (keep forever) | `{ maxSessions, maxAgeDays }`. `maxSessions` keeps the newest N sessions per app, `maxAgeDays` deletes older ones; with both, the stricter wins. |
+| `dropUnsupportedParams` | `true` | Drop `temperature`, `top_p` and penalties the target model is known to reject, and list them in the `x-plugboard-dropped-params` response header. `false` forwards them as sent. |
 | `remoteImages` | `false` | Let the server fetch `http(s)` image URLs from requests (20 MB cap, no redirects, `image/*` only). Off by default because it lets callers make the host request internal addresses; callers can always send `data:` URLs. |
 
 Changes to `listen` need a server restart; other option changes apply on config reload.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-plugboard",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "license": "MIT",
   "description": "OpenCode V2 plugin that serves an OpenAI-compatible /v1/chat/completions and /v1/models from your OpenCode server, backed by the providers you already connected there.",

package/src/config.ts

@@ -18,6 +18,8 @@ export interface PlugboardOptions {
   readonly remoteImages: boolean
   /** Prune old request sessions (see `src/session/prune.ts`). A limit that is unset is not applied; with neither, history is kept forever. Applies per app. */
   readonly history: HistoryLimits
+  /** Drop sampling parameters the target model is known to reject (reported in `x-plugboard-dropped-params`). On by default; off forwards them as sent. */
+  readonly dropUnsupportedParams: boolean
 }
 
 export const APP_NAME_PATTERN = /^[a-z0-9-]+$/
@@ -29,7 +31,7 @@ const DEFAULTS = {
   requestTimeoutMs: 600_000,
 } as const
 
-const KNOWN = new Set(["listen", "keys", "models", "aliases", "maxTools", "requestTimeoutMs", "remoteImages", "history"])
+const KNOWN = new Set(["listen", "keys", "models", "aliases", "maxTools", "requestTimeoutMs", "remoteImages", "history", "dropUnsupportedParams"])
 const HISTORY_KNOWN = new Set(["maxSessions", "maxAgeDays"])
 /** About 100 years: keeps `maxAgeDays * 86_400_000` a safe integer. */
 const MAX_AGE_DAYS = 36_500
@@ -118,6 +120,8 @@ export function parseOptions(raw: unknown): PlugboardOptions {
 
   if (input.remoteImages !== undefined && typeof input.remoteImages !== "boolean")
     throw new Error("plugboard option `remoteImages` must be a boolean")
+  if (input.dropUnsupportedParams !== undefined && typeof input.dropUnsupportedParams !== "boolean")
+    throw new Error("plugboard option `dropUnsupportedParams` must be a boolean")
 
   const historyInput = input.history
   if (historyInput !== undefined && !isRecord(historyInput)) throw new Error("plugboard option `history` must be an object")
@@ -135,6 +139,7 @@ export function parseOptions(raw: unknown): PlugboardOptions {
     requestTimeoutMs: positiveInt(input.requestTimeoutMs, "requestTimeoutMs", DEFAULTS.requestTimeoutMs, MAX_TIMER_MS),
     remoteImages: input.remoteImages === true,
     history: { ...(maxSessions === undefined ? {} : { maxSessions }), ...(maxAgeDays === undefined ? {} : { maxAgeDays }) },
+    dropUnsupportedParams: input.dropUnsupportedParams !== false,
   }
 }
 

package/src/http.ts

@@ -15,6 +15,8 @@ const MAX_TIMER_MS = 2 ** 31 - 1
 const LINGER_MS = 5_000
 /** After the deadline passes, a response that has not finished flushing (a client that stopped reading) is destroyed after this long. */
 const DEADLINE_GRACE_MS = 2_000
+/** An SSE stream idle for this long gets a comment line, so a client with a header or idle timeout keeps waiting for a model that is still reasoning. */
+const KEEPALIVE_MS = 15_000
 
 /** A request body that cannot be accepted: too large, or not JSON. `status` is the HTTP status to answer with. */
 export class BodyError extends Error {
@@ -196,10 +198,18 @@ export const sendJson = (response: ServerResponse, status: number, payload: unkn
  * is something to send; chunks after the client is gone are dropped. `write` is synchronous (the
  * encoder's contract); backpressure is honoured by `paced`, which holds back the next event while
  * the socket buffer is full. `signal` (the request scope's) ends those waits when it aborts.
+ *
+ * Keepalive: `paced` commits the response (200 and SSE headers) at the first event that is not a
+ * terminal one (reasoning counts), then writes an SSE comment whenever the stream has been idle
+ * for `keepaliveMs`, until the events end. A failure before that first event still gets its real
+ * HTTP status; after it, the caller must report failures as SSE frames. A tick is skipped while
+ * the socket buffer is full, and stops when the client is gone or the scope aborted.
  */
-export function sseWriter(response: ServerResponse, signal?: AbortSignal) {
+export function sseWriter(response: ServerResponse, signal?: AbortSignal, keepaliveMs = KEEPALIVE_MS) {
   let started = false
   let blocked = false
+  let lastWrite = Date.now()
+  let timer: ReturnType<typeof setTimeout> | undefined
   const waiters: Array<() => void> = []
   const release = () => {
     blocked = false
@@ -207,6 +217,45 @@ export function sseWriter(response: ServerResponse, signal?: AbortSignal) {
   }
   response.on("drain", release)
   response.on("close", release)
+  const commit = () => {
+    if (started || response.destroyed || response.writableEnded) return
+    started = true
+    response.writeHead(200, {
+      "content-type": "text/event-stream; charset=utf-8",
+      "cache-control": "no-cache, no-transform",
+      connection: "keep-alive",
+      "x-accel-buffering": "no",
+    })
+    // `writeHead` alone queues the headers until the first body write; a keepalive commit has no body yet.
+    response.flushHeaders()
+  }
+  const send = (chunk: string) => {
+    if (!response.write(chunk)) blocked = true
+    lastWrite = Date.now()
+  }
+  const stopKeepalive = () => {
+    clearTimeout(timer)
+    timer = undefined
+  }
+  const arm = (delay: number) => {
+    timer = setTimeout(tick, delay)
+    timer.unref?.()
+  }
+  const tick = () => {
+    timer = undefined
+    if (response.destroyed || response.writableEnded || signal?.aborted) return
+    const idle = Date.now() - lastWrite
+    if (idle < keepaliveMs) return arm(keepaliveMs - idle)
+    if (!blocked) send(": keepalive\n\n")
+    arm(keepaliveMs)
+  }
+  const beginKeepalive = () => {
+    commit()
+    if (!started || timer !== undefined) return
+    lastWrite = Date.now()
+    arm(keepaliveMs)
+  }
+  response.on("close", stopKeepalive)
   const drained = (): Promise<void> => {
     if (!blocked || response.destroyed || signal?.aborted) return Promise.resolve()
     return new Promise((resolve) => {
@@ -226,16 +275,8 @@ export function sseWriter(response: ServerResponse, signal?: AbortSignal) {
     },
     write(chunk: string) {
       if (response.destroyed || response.writableEnded) return
-      if (!started) {
-        started = true
-        response.writeHead(200, {
-          "content-type": "text/event-stream; charset=utf-8",
-          "cache-control": "no-cache, no-transform",
-          connection: "keep-alive",
-          "x-accel-buffering": "no",
-        })
-      }
-      if (!response.write(chunk)) blocked = true
+      commit()
+      send(chunk)
     },
     /** Resolves when the socket buffer has room again, the client is gone, or the request scope aborted. */
     drained,
@@ -252,9 +293,11 @@ export function sseWriter(response: ServerResponse, signal?: AbortSignal) {
           if (response.destroyed) return
           const next = await iterator.next()
           if (next.done) return
+          if (next.value.type !== "error" && next.value.type !== "finish") beginKeepalive()
           yield next.value
         }
       } finally {
+        stopKeepalive()
         void iterator.return?.(undefined)?.catch?.(() => {})
       }
     },

package/src/openai/request.ts

@@ -328,6 +328,7 @@ export function parseChatRequest(body: unknown, options: PlugboardOptions): Pars
       stream: body.stream === true,
       includeUsage: streamOptions.include_usage === true,
       ...(respond ? { structuredTool: RESPOND_TOOL, ...(withCallerTools ? { callerTools: true } : {}) } : {}),
+      ...(format.instruction ? { jsonObject: true } : {}),
     },
     ...(typeof body.reasoning_effort === "string" ? { reasoningEffort: body.reasoning_effort } : {}),
   }

package/src/openai/response.ts

@@ -27,6 +27,12 @@ export interface OpenAiExchange {
    * answer is content only when the step called no caller tool.
    */
   readonly callerTools?: boolean
+  /**
+   * `response_format: json_object`: the model is only asked in a system instruction, and sometimes
+   * wraps the answer in a markdown code fence. A single fence around text that parses as JSON is
+   * stripped from the content (`unfence`).
+   */
+  readonly jsonObject?: boolean
 }
 
 /** How a streamed exchange ended. Nothing was written when `failure` is set and `started` is false: the caller answers with a real HTTP error. */
@@ -123,6 +129,24 @@ const structured = {
         },
 }
 
+/** One markdown code fence (```json or a bare ```) around the whole text. */
+const FENCED = /^```[ \t]*(?:json)?[ \t]*\r?\n([\s\S]*?)\r?\n?[ \t]*```$/i
+
+/**
+ * The inside of a single code fence that wraps the whole text, when the inside parses as JSON;
+ * anything else comes back unchanged (prose around the fence, two fences, non-JSON).
+ */
+export function unfence(text: string): string {
+  const inside = FENCED.exec(text.trim())?.[1]
+  if (inside === undefined) return text
+  try {
+    JSON.parse(inside)
+    return inside.trim()
+  } catch {
+    return text
+  }
+}
+
 const newId = () => `chatcmpl-${crypto.randomUUID().replaceAll("-", "").slice(0, 29)}`
 const now = () => Math.floor(Date.now() / 1000)
 
@@ -169,7 +193,9 @@ export async function collectCompletion(
         ? structured.content(answer)
         : null
       : exchange.structuredTool === undefined && text.length > 0
-        ? text
+        ? exchange.jsonObject
+          ? unfence(text)
+          : text
         : null,
     refusal: null,
   }
@@ -229,6 +255,18 @@ export async function streamCompletion(
     started = true
     chunk({ role: "assistant", content: "" })
   }
+  // json_object: text that opens with a backtick may be a fenced answer, so it waits (as `pending`)
+  // until a tool call or the finish shows the whole text; anything else streams as it comes. A
+  // fenced answer therefore arrives as one chunk.
+  let pending = ""
+  let passing = false
+  const flush = () => {
+    if (pending.length === 0) return
+    const text = unfence(pending)
+    pending = ""
+    start()
+    chunk({ content: text })
+  }
 
   for await (const event of events) {
     if (event.type === "error") {
@@ -258,6 +296,16 @@ export async function streamCompletion(
       }
       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()
     start()
     if (event.type === "text-delta") {
       if (event.text.length > 0) chunk({ content: event.text })
@@ -276,6 +324,7 @@ export async function streamCompletion(
     write("data: [DONE]\n\n")
     return { failure, started }
   }
+  flush()
   start()
   if (held && isStructured) chunk({ content: structured.content(held) })
   chunk({}, finishReason(finish!, calls, isStructured))

package/src/openai/route.ts

@@ -33,6 +33,7 @@ import { listAvailableModels, resolveModel } from "../models.js"
 import { serveResponses } from "../responses/route.js"
 import { parseChatRequest } from "./request.js"
 import { collectCompletion, encodeError, encodeModelList, streamCompletion } from "./response.js"
+import { dropRejected } from "./sampling.js"
 
 /** What the serving generation supplies per request. */
 export interface RouteHost {
@@ -43,6 +44,7 @@ export interface RouteHost {
 }
 
 const SESSION_HEADER = "x-plugboard-session"
+const DROPPED_HEADER = "x-plugboard-dropped-params"
 const MODEL_PREFIX = "/v1/models/"
 const KNOWN_ROUTES = ["GET /v1/models", "POST /v1/chat/completions", "POST /v1/responses"]
 
@@ -61,6 +63,8 @@ interface RequestInfo {
   model?: string
   /** Set when a response committed as 200 and then failed (a stream error frame): the log outcome and the error code. */
   failed?: string
+  /** Sampling parameters dropped for this model (comma list), when any. */
+  dropped?: string
 }
 
 export function createOpenAiRoute(host: RouteHost) {
@@ -127,7 +131,13 @@ export function createOpenAiRoute(host: RouteHost) {
     const ref = resolveModel(host.options, parsed.request.model, catalog, parsed.reasoningEffort)
     if (isPlugError(ref)) return fail(response, ref)
     info.model = `${ref.providerID}/${ref.id}${ref.variant ? `#${ref.variant}` : ""}`
-    const call: PlugRequest = { ...parsed.request, ref }
+    // Sampling parameters the model is known to reject are dropped and reported (header and log), 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.
@@ -145,14 +155,19 @@ export function createOpenAiRoute(host: RouteHost) {
     )
 
     if (exchange.stream) {
-      // Nothing is committed until the encoder writes its first frame, so a failure before any
-      // wire-visible output (including suppressed reasoning or structured prose) is a real HTTP error.
+      // Nothing is committed until the first model event that is not a terminal one (reasoning
+      // counts: `paced` then commits 200 and sends keepalive comments), so a failure before that is a
+      // real HTTP error. After it, a failure is an SSE error frame.
       const sse = sseWriter(response, scope.signal)
-      const { failure } = await streamCompletion(sse.paced(events), exchange, sse.write)
+      const { failure, started } = await streamCompletion(sse.paced(events), exchange, sse.write)
       if (!sse.started && !response.headersSent) {
         if (!scope.signal.aborted || scope.timedOut) fail(response, failure ?? { status: 502, kind: "server", message: "No response from the model" })
       } else {
-        if (failure) info.failed = failure.code ?? failure.kind
+        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(`data: ${JSON.stringify(encodeError(failure))}\n\ndata: [DONE]\n\n`)
+        }
         if (!response.writableEnded) response.end()
       }
       return
@@ -207,7 +222,7 @@ export function createOpenAiRoute(host: RouteHost) {
         finishRequest(request, response)
       } catch {}
       if (info.route !== "GET /healthz" || outcome !== "ok") {
-        const fields = { id, route: info.route, app: info.app, model: info.model, status: response.statusCode, ms: Date.now() - started, outcome, error }
+        const fields = { id, route: info.route, app: info.app, model: info.model, dropped: info.dropped, status: response.statusCode, ms: Date.now() - started, outcome, error }
         if (outcome === "error" || response.statusCode >= 500) logError("request.failed", fields)
         else log("request", fields)
       }

package/src/openai/sampling.ts

@@ -0,0 +1,96 @@
+/**
+ * Sampling parameters a model is known to reject.
+ *
+ * OpenAI clients send `temperature`, `top_p` and the penalties as if every model took them, but
+ * some providers answer a 400 for them. The OpenCode host passes them through untouched, so
+ * plugboard drops the ones a rule below says the model refuses and reports each drop in the
+ * `x-plugboard-dropped-params` response header (option `dropUnsupportedParams` turns this off).
+ *
+ * The rules are an observed table, not a specification: each line says what the provider answered
+ * when it was probed (OpenCode 2.0.26, October 2026). A model no rule matches keeps every
+ * parameter, so a new model that rejects one still fails with the provider's own 400.
+ */
+import type { ModelRef, PlugGeneration } from "../contract.js"
+
+type Param = "temperature" | "topP" | "frequencyPenalty" | "presencePenalty"
+
+/** Wire names, in the order the header lists them. */
+const WIRE: ReadonlyArray<readonly [Param, string]> = [
+  ["temperature", "temperature"],
+  ["topP", "top_p"],
+  ["frequencyPenalty", "frequency_penalty"],
+  ["presencePenalty", "presence_penalty"],
+]
+
+interface Rule {
+  readonly applies: (ref: ModelRef) => boolean
+  /** `null`: the model takes no value; a number: the only value it takes (any other is dropped). */
+  readonly only?: Readonly<Partial<Record<Param, number | null>>>
+  /** The model takes the key or the one it is listed under, not both: the listed one is dropped when the other is set. */
+  readonly notWith?: Readonly<Partial<Record<Param, Param>>>
+}
+
+/** `claude-opus-4-7`, `claude-sonnet-5.5`, `claude-haiku-5-5-20260101`: family and version. */
+const claude = (id: string): { modern: boolean } | undefined => {
+  if (/^claude-fable/.test(id)) return { modern: true }
+  const match = /^claude-(?:opus|sonnet|haiku)-(\d+)(?:[-.](\d{1,2})(?!\d))?/.exec(id)
+  if (!match) return undefined
+  const major = Number(match[1])
+  const minor = Number(match[2] ?? 0)
+  // Opus 4.7 and newer, and every 5.x: temperature and top_p are deprecated, or limited to
+  // their defaults while adaptive thinking is on (which is the default).
+  return { modern: major > 4 || (major === 4 && minor >= 7) }
+}
+
+const gpt = (id: string) => /^gpt-[56]/.test(id)
+
+const RULES: ReadonlyArray<Rule> = [
+  // Claude through the Anthropic protocol: 400 "`temperature` is deprecated for this model" /
+  // "`temperature` may only be set to 1 when thinking is enabled or in adaptive mode".
+  // Probed: anthropic opus-4-7, opus-4-8, opus-5, opus-5-5, sonnet-5, sonnet-5-5, haiku-5-5,
+  // fable-5, fable-5-1; opencode-go claude-haiku-5-5. GitHub Copilot's haiku-5.5 took them.
+  {
+    applies: (ref) => ref.providerID !== "github-copilot" && claude(ref.id)?.modern === true,
+    only: { temperature: null, topP: null },
+  },
+  // Older Claude: 400 "`temperature` and `top_p` cannot both be specified for this model".
+  // Probed: anthropic haiku-4-5, sonnet-4-5, sonnet-4-6, opus-4-5, opus-4-6; copilot haiku-4.5.
+  { applies: (ref) => claude(ref.id)?.modern === false, notWith: { topP: "temperature" } },
+  // GPT-5 and 6 reasoning models: 400 "Unsupported parameter: temperature" (and the other three).
+  // Probed: openai gpt-5.5, gpt-5.6-luna, gpt-6.1-sol; opencode-go gpt-5.6-luna, gpt-6-luna.
+  { applies: (ref) => gpt(ref.id) && ref.providerID !== "github-copilot", only: { temperature: null, topP: null, frequencyPenalty: null, presencePenalty: null } },
+  // Copilot's GPT-5/6 refuse only temperature and top_p (gpt-5-mini, gpt-5.5, gpt-6-luna; penalties passed).
+  { applies: (ref) => gpt(ref.id) && ref.providerID === "github-copilot", only: { temperature: null, topP: null } },
+  // opencode-go glm-5.3-flash: 400 "only frequency_penalty=0 is supported".
+  { applies: (ref) => ref.providerID === "opencode-go" && ref.id === "glm-5.3-flash", only: { frequencyPenalty: 0, presencePenalty: 0 } },
+  // opencode-go kimi-k2.7-code: 400 "invalid temperature: only 1 is allowed for this model" (and the other three).
+  {
+    applies: (ref) => ref.providerID === "opencode-go" && ref.id === "kimi-k2.7-code",
+    only: { temperature: 1, topP: 0.95, frequencyPenalty: 0, presencePenalty: 0 },
+  },
+]
+
+export interface Sampled {
+  readonly generation: PlugGeneration
+  /** Wire names of the dropped parameters, in header order (`temperature`, `top_p`, `frequency_penalty`, `presence_penalty`). */
+  readonly dropped: ReadonlyArray<string>
+}
+
+/** `generation` without the parameters the model is known to reject, and which ones those were. */
+export function dropRejected(ref: ModelRef, generation: PlugGeneration): Sampled {
+  const rules = RULES.filter((rule) => rule.applies(ref))
+  if (rules.length === 0) return { generation, dropped: [] }
+  const out: { -readonly [K in keyof PlugGeneration]: PlugGeneration[K] } = { ...generation }
+  const drop = new Set<Param>()
+  for (const rule of rules)
+    for (const [param, allowed] of Object.entries(rule.only ?? {}) as Array<[Param, number | null]>) {
+      const value = generation[param]
+      if (value !== undefined && value !== allowed) drop.add(param)
+    }
+  // `notWith` looks at what survives the rules above.
+  for (const rule of rules)
+    for (const [param, other] of Object.entries(rule.notWith ?? {}) as Array<[Param, Param]>)
+      if (generation[param] !== undefined && !drop.has(param) && generation[other] !== undefined && !drop.has(other)) drop.add(param)
+  for (const param of drop) delete out[param]
+  return { generation: out, dropped: WIRE.filter(([param]) => drop.has(param)).map(([, wire]) => wire) }
+}