opencode-plugboard 0.2.1 → 0.4.0

package/README.md

@@ -6,7 +6,7 @@ You logged in to ChatGPT, Claude, Copilot or OpenCode Go once, in OpenCode. Your
 
 OpenCode V2 has no such endpoint, and the V1 plugins that did this stopped working when the plugin API changed. Plugboard is V2 only. It was tested on OpenCode 2.0.26, and the peer range `>=2.0.26 <2.1` allows 2.0.x patch releases.
 
-Status: v0.1, in development and not published yet. Chat Completions and the model list only. There is no `/v1/responses`, see [Known gaps](#known-gaps) and the [roadmap](#roadmap).
+Status: early (0.x), [published on npm](https://www.npmjs.com/package/opencode-plugboard). Chat Completions, the Responses API and the model list. `/v1/responses` is a stateless subset, see [docs/responses.md](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/responses.md).
 
 Docs: [architecture](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/architecture.md), [development](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/development.md), [clients](#clients).
 
@@ -75,7 +75,7 @@ One short page per client, with a config snippet, a chat, a tool call, a structu
 | --- | --- | --- |
 | OpenAI Python SDK | [openai-python](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/clients/openai-python.md) | pass |
 | OpenAI JS SDK | [openai-js](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/clients/openai-js.md) | pass |
-| Vercel AI SDK | [vercel-ai-sdk](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/clients/vercel-ai-sdk.md) | pass with `createOpenAICompatible` or `.chat()`; structured output needs `supportsStructuredOutputs: true` there; the default `@ai-sdk/openai` call needs `/v1/responses` |
+| Vercel AI SDK | [vercel-ai-sdk](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/clients/vercel-ai-sdk.md) | pass with `createOpenAICompatible` or `.chat()`; structured output needs `supportsStructuredOutputs: true` there; the default `openai(id)` call works through `/v1/responses` (set `store: false` for multi-turn) |
 | LangChain Python | [langchain-python](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/clients/langchain-python.md) | pass; `json_mode` on `fast` was unreliable |
 | LangChain JS | [langchain-js](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/clients/langchain-js.md) | pass except `gpt-5.6*` ids, which force the Responses API, and `json_mode` on `fast` |
 | pydantic-ai | [pydantic-ai](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/clients/pydantic-ai.md) | pass with `OpenAIChatModel` |
@@ -83,13 +83,13 @@ One short page per client, with a config snippet, a chat, a tool call, a structu
 | n8n | [n8n](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/clients/n8n.md) | pass with "Use Responses API" off |
 | Anything else | [any-app](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/clients/any-app.md) | base URL, key, model id |
 
-Each run drove the client's own SDK or API against a dev server at an earlier commit: a plain chat, a tool round trip, streaming, an image and structured output on `fast`, a Claude model and a ChatGPT model. A pass here is not a clean sweep, and the notes in the table and on each page say where it was not. The release-candidate record has not been written yet.
+Each run drove the client's own SDK or API against a dev server at an earlier commit: a plain chat, a tool round trip, streaming, an image and structured output on `fast`, a Claude model and a ChatGPT model. A pass here is not a clean sweep, and the notes in the table and on each page say where it was not. The latest full acceptance run is in [compat/results/release-candidate.md](https://github.com/jjjermiah/opencode-plugboard/blob/main/compat/results/release-candidate.md).
 
 ## Known gaps
 
-- **No `/v1/responses` yet.** Clients that default to the Responses API fail with `404 No route for POST /v1/responses`. That includes the Vercel AI SDK's `@ai-sdk/openai` default call (use `createOpenAICompatible` or `.chat(id)`), LangChain JS for `gpt-5.6*` ids, and n8n's "Use Responses API" option (turn it off).
+- **`/v1/responses` is stateless.** `previous_response_id`, `conversation`, `item_reference`, `background` and hosted tools return 400. See [docs/responses.md](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/responses.md).
 - Only `n=1`, no `logprobs`, no embeddings, audio or image generation.
-- No history pruning, no per-app concurrency limit.
+- No per-app concurrency limit yet ([#54](https://github.com/jjjermiah/opencode-plugboard/issues/54), [#86](https://github.com/jjjermiah/opencode-plugboard/issues/86)).
 
 ## Options
 
@@ -104,6 +104,8 @@ Options live under `options` in the plugin entry. `{env:VAR}` is expanded by Ope
 | `aliases` | none | Map of alias to `provider/model[#variant]`. Each target must also pass `models`. |
 | `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.
@@ -142,7 +144,7 @@ $XDG_DATA_HOME/opencode-plugboard/<app>/        # default ~/.local/share/opencod
 
 That directory only groups sessions: it is the `directory` a session is filed under. The prompts and replies are not stored in it. OpenCode keeps them in its own database, `opencode.db` in its data directory (`opencode debug paths` prints the exact location, and `OPENCODE_DB` can override it). So deleting, locking down or backing up the app directory removes, protects or saves no history. To back up, restrict or purge history, work on that database, or remove sessions through OpenCode ([`compat/tools/sessions.py`](https://github.com/jjjermiah/opencode-plugboard/blob/main/compat/tools/sessions.py) does that for one app).
 
-In OpenCode the sessions appear as one group per app in the desktop and phone app home screen. In the TUI they are visible in the all-projects view (ctrl+a), not in a project's own list. Nothing deletes them yet ([pruning is a roadmap item](https://github.com/jjjermiah/opencode-plugboard/issues/8)).
+In OpenCode the sessions appear as one group per app in the desktop and phone app home screen. In the TUI they are visible in the all-projects view (ctrl+a), not in a project's own list. Set `history` to delete old ones: sweeps run on requests, at most every 10 minutes, in bounded batches, and never touch a running session. Only sessions created while a limit is set are pruned; remove older ones with `compat/tools/sessions.py`.
 
 OpenCode loads plugin hooks per directory, so plugboard has to be loaded in those app directories, which is why it needs the global config. Everywhere outside the data root it is inert: it only joins the shared listener and registers no hooks, tools or agent rules, so your real projects behave as before.
 
@@ -220,7 +222,7 @@ The model call sits behind one interface, `ModelCaller`, so a native backend can
 
 ## Roadmap
 
-Work is tracked in GitHub issues. The [v0.1 milestone](https://github.com/jjjermiah/opencode-plugboard/milestone/1) lists what is needed before the first release, and the [later milestone](https://github.com/jjjermiah/opencode-plugboard/milestone/2) holds the rest: the `/v1/responses`, `/v1/messages` and Gemini front-ends, agent mode, a native backend, history pruning and an upstream request to boot plugins at server start.
+Work is tracked in GitHub issues. The [v0.1 milestone](https://github.com/jjjermiah/opencode-plugboard/milestone/1) lists what is needed before the first release, and the [later milestone](https://github.com/jjjermiah/opencode-plugboard/milestone/2) holds the rest: the `/v1/messages` and Gemini front-ends, agent mode, a native backend, usage accounting, rate limits and an upstream request to boot plugins at server start.
 
 Not planned: V1 support, embeddings, audio, image generation.
 

package/index.ts

@@ -26,7 +26,7 @@ import { createOpenAiRoute } from "./src/openai/route.js"
 import { ensureBackend, ensurePump, loadServingCatalog, registerGeneration, sessionStore } from "./src/runtime.js"
 import { createSessionCaller } from "./src/session/caller.js"
 import { installSessionHooks } from "./src/session/context.js"
-import { createSessionPort, loadCatalog } from "./src/session/host.js"
+import { createHistoryPort, createSessionPort, loadCatalog } from "./src/session/host.js"
 
 export default Plugin.define({
   id: "opencode-plugboard",
@@ -74,6 +74,8 @@ export default Plugin.define({
         directory: ctx.location.directory,
         // Rebuild the transforms below once a request has confirmed this Location as an app directory.
         refresh: () => Effect.runPromise(Effect.all([ctx.agent.reload(), ctx.tool.reload()], { discard: true })),
+        // Host handles for indexing and pruning request sessions; only called from request handling.
+        history: { port: createHistoryPort(ctx), limits: options.history },
         handler: (request, response) => {
           startPump()
           handle(request, response).catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-plugboard",
-  "version": "0.2.1",
+  "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.",
@@ -19,7 +19,8 @@
   },
   "files": ["index.ts", "src/", "README.md", "LICENSE"],
   "scripts": {
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "release": "bun scripts/release.ts"
   },
   "devDependencies": {
     "@opencode/plugin": "2.0.26",

package/src/config.ts

@@ -1,6 +1,7 @@
 /** Plugin options: type, defaults, validation, caller authentication and the loopback check. */
 
 import type { PlugError } from "./contract.js"
+import type { HistoryLimits } from "./session/prune.js"
 
 /** Plugin options, after defaults and validation (see `parseOptions`). */
 export interface PlugboardOptions {
@@ -15,6 +16,10 @@ export interface PlugboardOptions {
   readonly requestTimeoutMs: number
   /** Fetch http(s) image URLs server-side. Off by default: it is an SSRF vector into the host's network. */
   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-]+$/
@@ -26,7 +31,10 @@ const DEFAULTS = {
   requestTimeoutMs: 600_000,
 } as const
 
-const KNOWN = new Set(["listen", "keys", "models", "aliases", "maxTools", "requestTimeoutMs", "remoteImages"])
+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
 const MODEL_PATTERN = /^[^/#*\s]+\/(\*|[^#*\s]+(#[^#*\s]+)?)$/
 const ALIAS_TARGET = /^[^/#*\s]+\/[^#*\s]+(#[^#*\s]+)?$/
 /** `provider/model...` shaped: an alias like this would collide with real model ids in listing and resolution. */
@@ -112,6 +120,15 @@ 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")
+  for (const key of Object.keys(historyInput ?? {}))
+    if (!HISTORY_KNOWN.has(key)) throw new Error(`Unknown plugboard option \`history.${key}\` (known: ${[...HISTORY_KNOWN].join(", ")})`)
+  const maxSessions = historyInput?.maxSessions === undefined ? undefined : positiveInt(historyInput.maxSessions, "history.maxSessions", 0)
+  const maxAgeDays = historyInput?.maxAgeDays === undefined ? undefined : positiveInt(historyInput.maxAgeDays, "history.maxAgeDays", 0, MAX_AGE_DAYS)
 
   return {
     listen: { host, port: port ?? DEFAULTS.port },
@@ -121,6 +138,8 @@ export function parseOptions(raw: unknown): PlugboardOptions {
     maxTools: positiveInt(input.maxTools, "maxTools", DEFAULTS.maxTools, 1024),
     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

@@ -1,6 +1,6 @@
 /**
  * OpenAI front-end route table: `GET /healthz`, `GET /v1/models`, `GET /v1/models/{id}`,
- * `POST /v1/chat/completions`.
+ * `POST /v1/chat/completions`, and the dispatch of `POST /v1/responses` to `src/responses/route.ts`.
  *
  * The flow is: establish cancellation and the deadline, check origin, authenticate, parse, resolve
  * the model, call the ModelCaller, encode. Parsing, policy and encoding are imported directly;
@@ -30,8 +30,10 @@ import {
 } from "../http.js"
 import { errorMessage, log, logError } from "../log.js"
 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 {
@@ -42,8 +44,9 @@ 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"]
+const KNOWN_ROUTES = ["GET /v1/models", "POST /v1/chat/completions", "POST /v1/responses"]
 
 const decodeSegment = (raw: string): string => {
   try {
@@ -60,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) {
@@ -119,13 +124,20 @@ export function createOpenAiRoute(host: RouteHost) {
     if (unsupported) return fail(response, unsupported)
 
     const body = await readJsonBody(request, scope.signal)
+    if (route === "POST /v1/responses") return serveResponses(host, { app: auth.app, body, response, scope, info })
     const parsed = parseChatRequest(body, host.options)
     if (isPlugError(parsed)) return fail(response, parsed)
     const catalog = await scope.race(host.loadCatalog())
     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.
@@ -143,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
@@ -205,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) }
+}