opencode-plugboard 0.3.0 → 0.4.1

package/README.md

@@ -1,24 +1,36 @@
 # opencode-plugboard
 
-An OpenCode V2 plugin that turns your OpenCode server into an OpenAI-compatible endpoint, backed by the providers you already connected there.
+[![npm](https://img.shields.io/npm/v/opencode-plugboard)](https://www.npmjs.com/package/opencode-plugboard)
+[![license](https://img.shields.io/npm/l/opencode-plugboard)](https://github.com/jjjermiah/opencode-plugboard/blob/main/LICENSE)
+[![CI](https://github.com/jjjermiah/opencode-plugboard/actions/workflows/ci.yml/badge.svg)](https://github.com/jjjermiah/opencode-plugboard/actions/workflows/ci.yml)
 
-You logged in to ChatGPT, Claude, Copilot or OpenCode Go once, in OpenCode. Your other tools (a Discord bot, n8n, Open WebUI, a script) only speak the OpenAI API, so each one wants its own key or its own gateway with its own logins. Plugboard serves `/v1/chat/completions` and `/v1/models` from inside OpenCode, so those tools can reuse the logins you already have. Tool calls go back to the caller to execute. OpenCode never runs your tools.
+An OpenCode V2 plugin that serves an OpenAI-compatible API from your OpenCode server, so your other apps reuse the provider logins you already made in OpenCode.
 
-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: 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).
+```
+client ──▶ plugboard listener ──▶ OpenCode session ──▶ provider
+  ▲                                                        │
+  └──── reply; tool calls go back to the caller ◀──────────┘
+```
 
-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).
+Tools like n8n, Open WebUI or a Discord bot only speak the OpenAI API, so each wants its own key or its own gateway. Plugboard serves `/v1/chat/completions`, `/v1/responses` and `/v1/models` from inside OpenCode. OpenCode never runs your tools.
 
 ## Quick start
 
-Install it in your global OpenCode config (`~/.config/opencode/opencode.jsonc`). It has to be global. See [History](#history) for why. OpenCode installs it from npm the first time it loads; to run a local checkout instead, set `package` to its path.
+Tested on OpenCode 2.0.26. The peer range `>=2.0.26 <2.1` allows 2.0.x patch releases.
+
+**1. Pick a key** for your app, in the environment OpenCode starts from:
+
+```sh
+export PLUGBOARD_KEY_MY_APP=choose-a-long-random-string
+```
+
+**2. Install it** in your global config (`~/.config/opencode/opencode.jsonc`). It has to be global, see [History](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/history.md). OpenCode installs it from npm the first time it loads.
 
 ```jsonc
 {
   "plugins": [
     {
-      "package": "opencode-plugboard",
+      "package": "opencode-plugboard@0.4.1",
       "options": {
         "keys": { "my-app": "{env:PLUGBOARD_KEY_MY_APP}" },
         "models": ["anthropic/claude-sonnet-4-6", "github-copilot/*", "opencode-go/glm-5.3-flash"],
@@ -29,43 +41,52 @@ Install it in your global OpenCode config (`~/.config/opencode/opencode.jsonc`).
 }
 ```
 
-Every alias target must also be allowed in `models`, which is why the example lists `opencode-go/glm-5.3-flash`. Restart OpenCode, then touch the server once so it loads the plugin (see [Warm-up](#warm-up-for-always-on-servers)). The endpoint listens on `127.0.0.1:4010`.
+Every alias target must also be allowed in `models`. Pin the version as shown. A bare `"opencode-plugboard"` means `latest`, so a cache refresh or `opencode plugin update` can pull code you have not read. A global plugin runs inside OpenCode in every project, next to your provider logins, so update the number on purpose after reading the [changelog](https://github.com/jjjermiah/opencode-plugboard/blob/main/CHANGELOG.md).
+
+**3. Restart OpenCode, then touch the server once.** OpenCode loads no plugin until a client connects, so the port stays closed until then:
 
 ```sh
-export PLUGBOARD_KEY_MY_APP=choose-a-long-random-string   # before starting OpenCode
+opencode api get /api/agent
+```
+
+For an always-on server, run that from the service unit, see [warm-up](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/warm-up.md).
+
+**4. Call it.** The endpoint listens on `127.0.0.1:4010`. This prints `pong`:
 
-curl http://127.0.0.1:4010/v1/chat/completions \
+```sh
+curl -s http://127.0.0.1:4010/v1/chat/completions \
   -H "Authorization: Bearer $PLUGBOARD_KEY_MY_APP" \
   -H "Content-Type: application/json" \
-  -d '{"model": "fast", "messages": [{"role": "user", "content": "reply with exactly: pong"}]}'
+  -d '{"model": "fast", "messages": [{"role": "user", "content": "reply with exactly: pong"}]}' \
+  | jq -r '.choices[0].message.content'
 ```
 
-Any OpenAI SDK works by changing the base URL and key:
+Any OpenAI SDK works by changing the base URL (`http://127.0.0.1:4010/v1`) and the key. Next:
 
-```python
-from openai import OpenAI
+- [Clients](#clients): config for Python, JS, Vercel AI SDK, LangChain, pydantic-ai, Open WebUI, n8n.
+- [Configuration](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/configuration.md): options, models, keys, errors.
+- [Reaching plugboard from another host or container](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/clients/any-app.md#reaching-plugboard-from-another-host-or-container).
+- [History](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/history.md): every request is kept as an OpenCode session.
+- [Architecture](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/architecture.md) and [development](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/development.md).
 
-client = OpenAI(base_url="http://127.0.0.1:4010/v1", api_key="<your key>")
-reply = client.chat.completions.create(
-    model="anthropic/claude-sonnet-4-6",
-    messages=[{"role": "user", "content": "Say hi."}],
-)
-print(reply.choices[0].message.content)
-```
+`GET /healthz` returns OK when the listener is up and needs no key.
 
-```js
-import OpenAI from "openai"
+## What this is not
 
-const client = new OpenAI({ baseURL: "http://127.0.0.1:4010/v1", apiKey: "<your key>" })
-const stream = await client.chat.completions.create({
-  model: "fast",
-  messages: [{ role: "user", content: "Say hi." }],
-  stream: true,
-})
-for await (const chunk of stream) process.stdout.write(chunk.choices[0]?.delta?.content ?? "")
-```
+Plugboard is early (0.x) and narrow on purpose.
+
+- **V2 only.** OpenCode V2 has no OpenAI endpoint, and the V1 plugins that had one stopped working when the plugin API changed. V1 is not planned.
+- **Two formats:** Chat Completions and Responses. `/v1/responses` is a stateless subset, see [docs/responses.md](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/responses.md). Anthropic Messages and Gemini front-ends are on the [roadmap](#roadmap).
+- **Not planned:** embeddings, audio, image generation. Only `n=1`, no `logprobs`.
+- **No concurrency limit per app** yet ([#54](https://github.com/jjjermiah/opencode-plugboard/issues/54), [#86](https://github.com/jjjermiah/opencode-plugboard/issues/86)).
+- **Not a gateway with its own provider keys.** It only reuses what OpenCode is logged in to.
 
-`GET /healthz` returns OK when the listener is up and needs no key. `GET /v1/models/{id}` returns one model from the list. Every chat response carries an `x-plugboard-session` header with the id of the OpenCode session that recorded it, so you can find the request in [History](#history). To call plugboard from another machine or a container, see [reaching plugboard from another host](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/clients/any-app.md#reaching-plugboard-from-another-host-or-container).
+How it differs from the alternatives:
+
+- [KochC/opencode-llm-proxy](https://github.com/KochC/opencode-llm-proxy) serves more API formats but targets OpenCode V1 only. Plugboard is V2 only and adds per-app keys and history, an explicit model allowlist, and rules that keep it from freezing the host (see [AGENTS.md](https://github.com/jjjermiah/opencode-plugboard/blob/main/AGENTS.md)).
+- [LiteLLM](https://github.com/BerriAI/litellm) is a separate gateway you run and give its own provider keys. It covers many more providers and API shapes. Pick it when you want a standalone service. Pick plugboard when OpenCode already holds the logins you want to reuse, such as a ChatGPT or Copilot subscription.
+
+The most common first failure is an SDK defaulting to `/v1/responses` for newer models. Plugboard serves it, but some clients need `store: false` or a "use chat completions" switch. Check the client's page below.
 
 ## Clients
 
@@ -83,147 +104,15 @@ 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 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
-
-- **`/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 per-app concurrency limit yet ([#54](https://github.com/jjjermiah/opencode-plugboard/issues/54), [#86](https://github.com/jjjermiah/opencode-plugboard/issues/86)).
-
-## Options
-
-Options live under `options` in the plugin entry. `{env:VAR}` is expanded by OpenCode.
-
-| Option | Default | Meaning |
-| --- | --- | --- |
-| `listen.host` | `127.0.0.1` | Interface to bind. A non-loopback host without `keys` refuses to start. |
-| `listen.port` | `4010` | Port to bind. |
-| `keys` | none | Map of app name to API key. The app name groups that app's history sessions. Names match `[a-z0-9-]+`. `default` is reserved. |
-| `models` | none (required) | Allowlist of models callers may use. See [Models](#models). |
-| `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. |
-| `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.
-
-OpenCode loads the plugin once per project directory, and all of those loads share one listener. The first one to load decides the options. A load elsewhere with different options logs once and stays inert, so a project entry cannot serve with weaker auth than the live one. When none is live, for example during a config reload, the next load's options are adopted. Requests are served from plugboard's own data directory when it is loaded, so a project's provider config doesn't change what callers get. So install it in the global config, which every project loads, and don't repeat it per project.
-
-On a loopback `listen.host`, requests with a `Host` header other than `127.0.0.1`, `localhost` or `[::1]` (on the listen port) get 403 `invalid_host`, and without `keys` a request with an `Origin` header gets 403 `cross_origin_forbidden`. The `Host` check only applies when `listen.host` is loopback. `POST` bodies must be `application/json` (415 otherwise).
-
-Without `keys`, only a loopback `listen.host` is accepted and every caller is the app `default`. Once any key exists, every `/v1` request needs a valid key, loopback included, and `/healthz` stays open. Callers send the key as `Authorization: Bearer <key>`. They never see or need the OpenCode server password.
-
-## Models
-
-Callers name models as `provider/model`, optionally `provider/model#variant` (for example `openai/gpt-6-luna#low`, since ChatGPT models need a variant). Nothing is exposed by accident, so you must list what callers may use in `models`:
-
-- `provider/model` allows that model with any variant.
-- `provider/model#variant` allows exactly that variant.
-- `provider/*` allows every model of the provider.
-
-With no `models`, `/v1/models` is empty and chat calls return 403. `/v1/models` lists the allowlist intersected with the models enabled on your server, plus your aliases. Each entry has `owned_by` set to the provider and an extra `plugboard` object (`capabilities`, `contextLimit`). The ids contain `/` and `#`, which some UIs mishandle, so define an alias for those.
-
-`reasoning_effort` in a request picks a variant when the model name has none and the model has one by that name. An alias can point at a model with a variant, which is the easy way to give a client a fixed effort level.
-
-## Apps and keys
-
-Each key name is an app. A request made with the `sparkyfitness` key is the app `sparkyfitness`, and its sessions are grouped under that app. Give every tool its own key. You can tell their traffic apart, and revoking one means removing one line.
-
-## History
-
-Every request is kept as an OpenCode session, so you can see what each app asked and what the model answered. Plugboard keeps the full caller transcript in each session (system prompt, messages, images as attachments, tool calls and results) plus the reply. The title is the first user message. A ten-turn chat is ten sessions, each complete.
-
-Each session is filed under a per-app directory, so it never shows up in your real projects:
-
-```
-$XDG_DATA_HOME/opencode-plugboard/<app>/        # default ~/.local/share/opencode-plugboard/<app>/
-```
-
-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. 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.
-
-History records every prompt and reply, so treat OpenCode's database as sensitive.
-
-## Warm-up for always-on servers
-
-OpenCode loads no plugin until a client touches the server, so after a restart the port stays closed until something connects. On a machine that runs `opencode serve` all the time, add one call right after start. Any request that makes OpenCode load a project works. `opencode api get /api/agent` does.
-
-On Linux, in the OpenCode systemd unit (retry until the server answers; pass the same server credentials your service uses, if you set any):
-
-```ini
-[Service]
-ExecStartPost=-/bin/sh -c 'for i in $(seq 1 30); do opencode api get /api/agent >/dev/null 2>&1 && exit 0; sleep 1; done; exit 1'
-```
-
-On macOS, a launchd job (`~/Library/LaunchAgents/dev.plugboard.warmup.plist`). It runs once when launchd loads it, which is at login and after boot. It does not run again when OpenCode restarts by itself, so after an OpenCode restart on its own, touch the server yourself (`launchctl kickstart -k gui/$(id -u)/dev.plugboard.warmup` reruns it) or run the same command from whatever restarts OpenCode.
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-  <key>Label</key><string>dev.plugboard.warmup</string>
-  <key>ProgramArguments</key>
-  <array>
-    <string>/bin/sh</string>
-    <string>-c</string>
-    <string>for i in $(seq 1 30); do opencode api get /api/agent >/dev/null 2>&amp;1 &amp;&amp; exit 0; sleep 1; done; exit 1</string>
-  </array>
-  <key>RunAtLoad</key><true/>
-</dict>
-</plist>
-```
-
-If `opencode` is not on the job's `PATH`, use its full path. A request to `/healthz` before the warm-up gets connection refused, which is expected. I'd like OpenCode to boot plugins at server start so none of this is needed ([upstream request](https://github.com/jjjermiah/opencode-plugboard/issues/2)).
-
-When config reloads happen, plugboard keeps the port open through a short grace period, so a reload does not drop connections. If no plugboard generation is alive when a request arrives, the caller gets a 503.
-
-## Limits and errors
-
-Errors use the OpenAI error body shape with the matching HTTP status.
-
-| Status | `code` | When | Message |
-| --- | --- | --- | --- |
-| 401 | `invalid_api_key` | Missing or wrong key | Missing or invalid API key |
-| 404 | `model_not_found` | Unknown model or not on the allowlist | Model &lt;m&gt; is not available |
-| 403 | `no_models_configured` | The `models` option is empty | No models are allowed: set the plugboard `models` option |
-| 400 | `too_many_tools` | More tools than `maxTools` | Request has &lt;n&gt; tools; plugboard allows &lt;max&gt; (option `maxTools`) |
-| 400 | `unsupported_parameter` | `n` above 1, `logprobs`, `top_logprobs` | names the parameter |
-
-Provider errors map to an OpenAI error body with the provider's status, including a provider's own rejection of a sampling parameter (ChatGPT models reject `temperature`, for example). Once a stream has started, a failure arrives as an `error` event followed by `[DONE]`. A client that disconnects, SSE included, interrupts the request. There is no per-app concurrency limit in v0.1.
-
-Supported request fields: messages with system, developer, user text and images, assistant `tool_calls` and tool results; `tools`, `tool_choice`, `response_format` (`json_object`, `json_schema`), `temperature`, `top_p`, `max_tokens`, `max_completion_tokens`, `stop`, `presence_penalty`, `frequency_penalty`, `reasoning_effort`, and streaming with a final usage chunk (`stream_options.include_usage`).
-
-Behaviours worth knowing:
-
-- `parallel_tool_calls` and `seed` are accepted and ignored.
-- `tool_choice` `auto` and `none` work as expected. `required` and a named function are applied as an instruction to the model, because the OpenCode session API has no tool-choice control. A model can still answer in text.
-- `response_format` `json_schema` works through a `respond` tool the model is instructed to call, and the arguments come back as the message content. The provider does not enforce the schema, so validate the result. `json_object` adds a system instruction instead and carries no schema, so name the keys in your prompt; weak models may still ignore them.
-- A request that carries both `tools` and a `json_schema` response format is changing: it will return the caller's tool calls ([#34](https://github.com/jjjermiah/opencode-plugboard/issues/34)). Don't rely on the current behaviour for that combination.
-- A streamed tool call arrives as one delta carrying the whole arguments string.
+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 is not a clean sweep, and the notes say where it was not. The latest full run is in [compat/results/release-candidate.md](https://github.com/jjjermiah/opencode-plugboard/blob/main/compat/results/release-candidate.md).
 
 ## How it works
 
-Each request becomes a session in the app's directory, using OpenCode's own request path, so provider fixes and auth plugins (Claude via an auth plugin, ChatGPT, Copilot) still apply.
-
-1. A front-end parses the OpenAI request into a format-neutral request, and the core checks the key and resolves the model.
-2. The session backend creates a session in the app directory and swaps the caller's system prompt, messages and tools in for OpenCode's own with a `context` hook.
-3. Caller tools map onto a pool of `maxTools` placeholder tools. A placeholder settles at once with a fixed no-op result, so history shows a completed call. Nothing of yours runs.
-4. When the model has emitted its tool calls, the plugin interrupts the turn and returns the calls to the caller. Text streams out as it arrives.
-5. The front-end encodes the events as JSON or SSE, and the session stays as history.
-
-The model call sits behind one interface, `ModelCaller`, so a native backend can replace the session backend later without touching the front-ends ([roadmap](https://github.com/jjjermiah/opencode-plugboard/issues/3)). [docs/architecture.md](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/architecture.md) has the details: lifetimes, process-wide state and the freeze-safety rules.
+Each request becomes an OpenCode session in the app's own directory, using OpenCode's request path, so provider fixes and auth plugins still apply. The plugin swaps the caller's prompt, messages and tools in for OpenCode's own. Caller tools map to placeholder tools that settle at once with a no-op result. When the model has emitted its tool calls, the plugin interrupts the turn and returns them to the caller. Text streams out as it arrives. [docs/architecture.md](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/architecture.md) has the lifetimes and the freeze-safety rules.
 
 ## 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/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.
+Work is tracked in GitHub issues: the [v0.1 milestone](https://github.com/jjjermiah/opencode-plugboard/milestone/1) and the [later milestone](https://github.com/jjjermiah/opencode-plugboard/milestone/2), which holds 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.
 
 ## License
 

package/package.json

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

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