opencode-plugboard 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jjjermiah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,229 @@
-# Temporary Holding Version
+# opencode-plugboard
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An OpenCode V2 plugin that turns your OpenCode server into an OpenAI-compatible endpoint, backed by the providers you already connected there.
+
+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.
+
+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).
+
+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).
+
+## 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.
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "opencode-plugboard",
+      "options": {
+        "keys": { "my-app": "{env:PLUGBOARD_KEY_MY_APP}" },
+        "models": ["anthropic/claude-sonnet-4-6", "github-copilot/*", "opencode-go/glm-5.3-flash"],
+        "aliases": { "fast": "opencode-go/glm-5.3-flash" }
+      }
+    }
+  ]
+}
+```
+
+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`.
+
+```sh
+export PLUGBOARD_KEY_MY_APP=choose-a-long-random-string   # before starting OpenCode
+
+curl 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"}]}'
+```
+
+Any OpenAI SDK works by changing the base URL and key:
+
+```python
+from openai import OpenAI
+
+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)
+```
+
+```js
+import OpenAI from "openai"
+
+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 ?? "")
+```
+
+`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).
+
+## Clients
+
+One short page per client, with a config snippet, a chat, a tool call, a structured-output note and the gotchas found in testing. Versions and dates are on each page; the raw evidence is in [`compat/results`](https://github.com/jjjermiah/opencode-plugboard/tree/main/compat/results).
+
+| Client | Page | Last run (2026-10-11) |
+| --- | --- | --- |
+| 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` |
+| 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` |
+| Open WebUI | [open-webui](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/clients/open-webui.md) | pass over its HTTP API; no browser, no structured output in its UI |
+| 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.
+
+## 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).
+- Only `n=1`, no `logprobs`, no embeddings, audio or image generation.
+- No history pruning, no per-app concurrency limit.
+
+## 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. |
+| `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. Nothing deletes them yet ([pruning is a roadmap item](https://github.com/jjjermiah/opencode-plugboard/issues/8)).
+
+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.
+
+## 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.
+
+## 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.
+
+Not planned: V1 support, embeddings, audio, image generation.
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,99 @@
+/**
+ * opencode-plugboard: an OpenAI-compatible HTTP endpoint served from inside an OpenCode V2
+ * server, backed by the server's own providers.
+ *
+ * Install in the GLOBAL OpenCode config. OpenCode loads the plugin once per Location:
+ *   - everywhere, a generation asks to join the process-wide listener (src/runtime.ts); an
+ *     accepted one can serve requests (a confirmed app-directory Location is preferred, else the
+ *     newest), a rejected one does nothing at all;
+ *   - every accepted generation also registers the context hook, the agent deny and the seed
+ *     tools, but all three are no-ops until a request has confirmed, asynchronously, that the
+ *     Location is a plugboard app directory (`.../opencode-plugboard/<app>/`, real path strictly
+ *     inside the data root; `ensureBackend` in src/runtime.ts). Until then, and in every other
+ *     project, nothing is rewritten.
+ *
+ * Freeze safety: this effect only registers and returns. It makes no `ctx` call that waits on
+ * location readiness, touches no filesystem and never blocks, and its finalizer is synchronous
+ * and calls nothing on `ctx` (a plugin effect that blocked once froze every prompt in a project).
+ * The event pump starts lazily from request handling. See docs/architecture.md.
+ */
+
+import { Plugin } from "@opencode/plugin/effect"
+import { Effect } from "effect"
+import { parseOptions } from "./src/config.js"
+import { errorMessage, logError } from "./src/log.js"
+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"
+
+export default Plugin.define({
+  id: "opencode-plugboard",
+  effect: (ctx) =>
+    Effect.gen(function* () {
+      let options
+      try {
+        options = parseOptions(ctx.options)
+      } catch (error) {
+        // Invalid options: stay inert and say why, instead of failing the Location's plugin load.
+        logError("options.invalid", { error: errorMessage(error) })
+        return
+      }
+
+      // ---- every Location: join the shared listener (sync registration only).
+      const sessions = sessionStore()
+      // Started lazily from request handling (handler, catalog load); never from setup.
+      const startPump = () => ensurePump(() => ctx.event.subscribe())
+      const ownCatalog = () => loadCatalog(ctx)
+      // Request handling only: an agent lookup scoped to another directory makes the host build that
+      // Location, which loads this plugin there. Plugin setup never calls it.
+      const bootLocation = (directory: string) => Effect.runPromise(ctx.agent.list({ location: { directory } }))
+      const callerDeps = {
+        port: createSessionPort(ctx),
+        sessions,
+        maxTools: options.maxTools,
+        remoteImages: options.remoteImages,
+        // The readiness gate the caller awaits before creating a session (fails closed: 503 `backend_unavailable`).
+        ensureBackend: (app: string, signal: AbortSignal) => ensureBackend(app, signal, bootLocation),
+      }
+      const handle = createOpenAiRoute({
+        options,
+        caller: createSessionCaller(callerDeps),
+        // The catalog comes from the preferred accepted generation (a data-root Location when there is
+        // one), not from whichever Location registered last; this generation's own is the fallback.
+        loadCatalog: async () => {
+          startPump()
+          return loadServingCatalog(ownCatalog)
+        },
+      })
+      const registration = registerGeneration({
+        listen: options.listen,
+        options,
+        // The host's string, compared with the real path `ensureBackend` confirms; no filesystem access here.
+        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 })),
+        handler: (request, response) => {
+          startPump()
+          handle(request, response).catch((error) => {
+            logError("request.unhandled", { error: errorMessage(error) })
+            if (response.headersSent) return void response.end()
+            response.writeHead(500, { "content-type": "application/json" })
+            response.end(JSON.stringify({ error: { message: "Internal server error", type: "server_error" } }))
+          })
+        },
+        loadCatalog: ownCatalog,
+      })
+      yield* Effect.addFinalizer(() => Effect.sync(() => registration.dispose()))
+
+      // ---- a rejected generation (different options or `listen`, foreign runtime) serves nothing and installs nothing.
+      if (!registration.accepted) return
+
+      // ---- the context hook, the agent deny and the seed tools. Ownership of the Location is only
+      // known after an asynchronous check (`ensureBackend`), so all three are no-ops until
+      // `registration.confirmed()`: in real projects nothing is ever added or rewritten.
+      yield* installSessionHooks(ctx, { maxTools: options.maxTools, sessions, active: registration.confirmed })
+      registration.ready()
+    }),
+})

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "opencode-plugboard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.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.",
+  "keywords": ["opencode", "opencode-plugin", "openai", "openai-compatible", "chat-completions"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jjjermiah/opencode-plugboard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jjjermiah/opencode-plugboard/issues"
+  },
+  "homepage": "https://github.com/jjjermiah/opencode-plugboard#readme",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": ["index.ts", "src/", "README.md", "LICENSE"],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@opencode/plugin": "2.0.26",
+    "@types/node": "^26.6.2",
+    "effect": "4.0.0-rc.112",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "@opencode/plugin": ">=2.0.26 <2.1",
+    "effect": "4.0.0-rc.112"
+  }
+}

package/src/config.ts

@@ -0,0 +1,150 @@
+/** Plugin options: type, defaults, validation, caller authentication and the loopback check. */
+
+import type { PlugError } from "./contract.js"
+
+/** Plugin options, after defaults and validation (see `parseOptions`). */
+export interface PlugboardOptions {
+  readonly listen: { readonly host: string; readonly port: number }
+  /** App name -> API key. App names match APP_NAME_PATTERN; "default" is reserved. */
+  readonly keys: Readonly<Record<string, string>>
+  /** Allowlist: exact `provider/model`, `provider/model#variant`, or `provider/*` patterns. Empty = nothing allowed. */
+  readonly models: ReadonlyArray<string>
+  /** Alias -> `provider/model[#variant]`. Targets must also pass the allowlist. */
+  readonly aliases: Readonly<Record<string, string>>
+  readonly maxTools: number
+  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
+}
+
+export const APP_NAME_PATTERN = /^[a-z0-9-]+$/
+export const DEFAULT_APP = "default"
+const DEFAULTS = {
+  host: "127.0.0.1",
+  port: 4010,
+  maxTools: 32,
+  requestTimeoutMs: 600_000,
+} as const
+
+const KNOWN = new Set(["listen", "keys", "models", "aliases", "maxTools", "requestTimeoutMs", "remoteImages"])
+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. */
+const CANONICAL_SHAPE = /^[^/\s]+\/\S/
+/** Largest delay Node timers accept (2^31 - 1); longer values overflow and fire immediately. */
+const MAX_TIMER_MS = 2_147_483_647
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+/**
+ * The hosts plugboard treats as loopback: `localhost`, `127.0.0.1` and `::1` (brackets and case
+ * ignored). This is exactly the set the Host header check in `src/http.ts` accepts, so a listen
+ * address that passes the keyless-loopback rule can also be reached by a request that passes the
+ * Host check; other loopback addresses (`127.0.0.2`) are not loopback here and need `keys`.
+ */
+export function isLoopbackHost(host: string): boolean {
+  const h = host.toLowerCase().replace(/^\[|\]$/g, "")
+  return h === "localhost" || h === "127.0.0.1" || h === "::1"
+}
+
+function positiveInt(value: unknown, name: string, fallback: number, max = Number.MAX_SAFE_INTEGER): number {
+  if (value === undefined) return fallback
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > max)
+    throw new Error(`plugboard option \`${name}\` must be an integer between 1 and ${max}`)
+  return value
+}
+
+/** Validates raw plugin options and applies defaults. Throws `Error` with an actionable message. */
+export function parseOptions(raw: unknown): PlugboardOptions {
+  if (raw !== undefined && raw !== null && !isRecord(raw)) throw new Error("plugboard options must be an object")
+  const input: Record<string, unknown> = raw ?? {}
+  for (const key of Object.keys(input))
+    if (!KNOWN.has(key)) throw new Error(`Unknown plugboard option \`${key}\` (known: ${[...KNOWN].join(", ")})`)
+
+  const listenInput = input.listen
+  if (listenInput !== undefined && !isRecord(listenInput)) throw new Error("plugboard option `listen` must be an object")
+  const host = listenInput?.host ?? DEFAULTS.host
+  if (typeof host !== "string" || host.length === 0) throw new Error("plugboard option `listen.host` must be a non-empty string")
+  const port = listenInput?.port
+  if (port !== undefined && (typeof port !== "number" || !Number.isInteger(port) || port < 1 || port > 65535))
+    throw new Error("plugboard option `listen.port` must be an integer between 1 and 65535")
+
+  const keyEntries: Array<[string, string]> = []
+  if (input.keys !== undefined && !isRecord(input.keys)) throw new Error("plugboard option `keys` must be an object of app name -> key")
+  const appOfKey = new Map<string, string>()
+  for (const [app, key] of Object.entries(input.keys ?? {})) {
+    if (app === DEFAULT_APP) throw new Error(`plugboard key name \`${DEFAULT_APP}\` is reserved for keyless loopback use`)
+    if (!APP_NAME_PATTERN.test(app)) throw new Error(`plugboard key name \`${app}\` must match ${APP_NAME_PATTERN}`)
+    if (typeof key !== "string" || key.length === 0)
+      throw new Error(`plugboard key \`${app}\` must be a non-empty string (is its {env:VAR} set?)`)
+    // Two apps sharing a key value would be indistinguishable: the last one would win silently.
+    const other = appOfKey.get(key)
+    if (other !== undefined) throw new Error(`plugboard keys \`${other}\` and \`${app}\` have the same value; every app needs its own key`)
+    appOfKey.set(key, app)
+    keyEntries.push([app, key])
+  }
+  // Own-property construction: a key such as `__proto__` must stay a key, never reach the prototype.
+  const keys: Record<string, string> = Object.fromEntries(keyEntries)
+  if (keyEntries.length === 0 && !isLoopbackHost(host))
+    throw new Error(`plugboard refuses to listen on non-loopback host \`${host}\` without \`keys\``)
+
+  const models = input.models ?? []
+  if (!Array.isArray(models)) throw new Error("plugboard option `models` must be an array of strings")
+  for (const pattern of models)
+    if (typeof pattern !== "string" || !MODEL_PATTERN.test(pattern))
+      throw new Error(`plugboard model \`${String(pattern)}\` must be \`provider/model\`, \`provider/model#variant\` or \`provider/*\``)
+
+  const aliasEntries: Array<[string, string]> = []
+  if (input.aliases !== undefined && !isRecord(input.aliases)) throw new Error("plugboard option `aliases` must be an object of alias -> model")
+  for (const [alias, target] of Object.entries(input.aliases ?? {})) {
+    if (alias.length === 0 || /[\s]/.test(alias)) throw new Error(`plugboard alias \`${alias}\` must be a non-empty string without whitespace`)
+    // Plain-object lookups downstream would hit the prototype accessor instead of the alias.
+    if (alias === "__proto__") throw new Error("plugboard alias `__proto__` is not allowed")
+    if (typeof target !== "string" || !ALIAS_TARGET.test(target))
+      throw new Error(`plugboard alias \`${alias}\` must target \`provider/model\` or \`provider/model#variant\``)
+    if (CANONICAL_SHAPE.test(alias))
+      throw new Error(`plugboard alias \`${alias}\` is written like a \`provider/model\` id; aliases must not contain \`/\` (use a short name such as \`fast\`)`)
+    aliasEntries.push([alias, target])
+  }
+  const aliases: Record<string, string> = Object.fromEntries(aliasEntries)
+
+  if (input.remoteImages !== undefined && typeof input.remoteImages !== "boolean")
+    throw new Error("plugboard option `remoteImages` must be a boolean")
+
+  return {
+    listen: { host, port: port ?? DEFAULTS.port },
+    keys,
+    models: models as string[],
+    aliases,
+    maxTools: positiveInt(input.maxTools, "maxTools", DEFAULTS.maxTools, 1024),
+    requestTimeoutMs: positiveInt(input.requestTimeoutMs, "requestTimeoutMs", DEFAULTS.requestTimeoutMs, MAX_TIMER_MS),
+    remoteImages: input.remoteImages === true,
+  }
+}
+
+const UNAUTHORIZED: PlugError = {
+  status: 401,
+  message: "Missing or invalid API key",
+  kind: "authentication",
+  code: "invalid_api_key",
+}
+
+function same(a: string, b: string): boolean {
+  let diff = a.length ^ b.length
+  const length = Math.max(a.length, b.length)
+  for (let i = 0; i < length; i++) diff |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0)
+  return diff === 0
+}
+
+/** No keys -> app `default`; with keys every request needs `Authorization: Bearer <key>`. */
+export function authenticate(options: PlugboardOptions, authorization: string | undefined): { app: string } | PlugError {
+  const entries = Object.entries(options.keys)
+  if (entries.length === 0) return { app: DEFAULT_APP }
+  const token = /^Bearer\s+(\S+)\s*$/i.exec(authorization ?? "")?.[1]
+  if (!token) return UNAUTHORIZED
+  let app: string | undefined
+  for (const [name, key] of entries) if (same(token, key)) app = name
+  return app === undefined ? UNAUTHORIZED : { app }
+}