## Description A `POST` whose path ends in a wire endpoint but that sits at a host's origin root (`/messages`, `/responses`, `/chat/completions`) is no longer routed to the proxy unless that origin is a configured provider base URL. Closes #4781. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) ## Changes Made - `plugins/opencode/src/transport.ts` — `hasWireRootBefore` no longer treats "no segment before the endpoint" as a wire root, so a bare `/messages` at an unknown host goes direct. - `plugins/opencode/src/transport.test.ts` — the bare-endpoint assertions from #4758 move into a #4781 case that pins both directions: direct by default, routed once the base is registered; the #4758 case keeps the prefixes that still route. - `plugins/opencode/README.md` — states the actual routing rule, and the two shapes that still route without a configured base. - `headroom/providers/opencode/_dist/index.js`, `headroom/providers/opencode/hook-shim/handler.js` — rebuilt, since the `opencode-plugin` gate compares bytes against `dist-standalone`. - `plugins/opencode/scripts/live-proof-4781.mjs` — the live proof below, committed so it can be rerun. ## Why #4758 stopped a suffix match from routing non-LLM hosts, but kept bare endpoints routable "because compatible gateways use those paths". That left exactly one non-LLM shape still leaking: `POST https://rest.messagebird.com/messages` with `Authorization: AccessKey ...` went to the proxy, carrying a non-LLM credential (#4781). Becoming the bare path is not evidence of a provider — it is equally the shape of a messaging API. A provider mounted at an origin root is still routed, because its base URL *is* a configured wire root (`isConfiguredWireRoot` matches every path on that origin when the base path is empty), which is how OpenCode reports `provider.<id>.options.baseURL`. ```ts return ( last !== undefined && (isVersionSegment(last) || IMMEDIATE_WIRE_ROOTS.has(last) || segments.some((s) => NAMED_WIRE_ROOTS.has(s))) ); ``` Everything else is untouched: version prefixes (`/v1`, `/v1beta`, `/v4`), immediate `api`, named roots (`backend-api`, `codex`, `openai`, `anthropic`, `zen`), Gemini colon actions, configured bases, `excludeHosts`, and the method gate. ## Testing - [x] New tests added for new functionality - [x] Manual testing performed `plugins/opencode` is a TypeScript package, so its gates are npm scripts rather than `pytest` / `ruff` / `mypy`; `npm audit` and the rest run in the repo's own CI. ### Test Output ```text > vitest run Test Files 4 passed (4) Tests 80 passed (80) > node node_modules/@typescript/native/bin/tsc --noEmit (clean, no output) > node scripts/live-proof-4781.mjs === decisions (real sockets, real fetch, real built plugin) === PASS MessageBird-shaped POST /messages -> left alone PASS MessageBird batches POST /messages/batches -> left alone PASS LLM control POST /v1/messages -> REROUTED to proxy PASS LLM control POST /v1/chat/completions -> REROUTED to proxy === what reached the proxy === POST /v1/messages x-headroom-base-url=http://localtest.me:8899 original-path=null POST /v1/chat/completions x-headroom-base-url=http://localtest.me:8899 original-path=/v1/chat/completions === MessageBird-shaped requests that reached the proxy: 0 === === what reached the upstream directly === POST /messages auth=AccessKey FAKE-TEST-VALUE (no proxy headers: true) POST /messages/batches auth=AccessKey FAKE-TEST-VALUE (no proxy headers: true) ALL CASES PASS ``` Before the fix, same script, source reverted to `HEAD~1` and the bundle rebuilt: ```text === decisions (real sockets, real fetch, real built plugin) === FAIL MessageBird-shaped POST /messages -> REROUTED to proxy PASS MessageBird batches POST /messages/batches -> left alone PASS LLM control POST /v1/messages -> REROUTED to proxy PASS LLM control POST /v1/chat/completions -> REROUTED to proxy === what reached the proxy === POST /messages x-headroom-base-url=http://localtest.me:8899 original-path=null ``` Reverting only `src/transport.ts` also fails the unit test (`1 failed | 79 passed`), satisfying "a test that fails before your fix and passes after". ## Real Behavior Proof - Environment: Windows 11 (win32), Node v26.10.0, this branch of `plugins/opencode`, committed wheel bundle `headroom/providers/opencode/_dist/index.js` loaded via `plugin.server(...)` as `headroom wrap opencode` does; upstream and proxy are local HTTP fixtures on real TCP sockets and `globalThis.fetch` is Node's undici, not a stub. - Exact command / steps: `cd plugins/opencode && npm ci && npm run build:standalone && node scripts/live-proof-4781.mjs`, which POSTs a MessageBird-shaped SMS payload and two LLM control requests to `http://localtest.me:8899` (resolves to 127.0.0.1 but is not a loopback spelling, so traffic really leaves the process) and records which server received each one. - Observed result: after the patch `POST /messages` and `POST /messages/batches` reach the upstream directly with no `x-headroom-base-url` header and the proxy receives zero MessageBird-shaped requests, while `/v1/messages` and `/v1/chat/completions` still reach the proxy with the upstream origin header; with `src/transport.ts` reverted to `HEAD~1` the same run reroutes `POST /messages` to the proxy, reproducing the reported leak over a real socket (full output in `Testing` → `Test Output`). - Not tested: a real MessageBird account and the real `rest.messagebird.com` host, since the payload and `AccessKey` are fake and routing is decided before DNS; the proxy's handling of an SMS body, which never arrives after this change; and a live OpenCode host process, since the fixture drives the plugin's own `server()` entry rather than an OpenCode session. ## Runtime Rollout Safety - Rollout-managed feature(s): none, no feature flag is involved. - Minimum rollout channel: next released `headroom-opencode` / wheel. - Stable/default behavior changed: yes, deliberately — a `POST` to `/messages`, `/responses` or `/chat/completions` at a host's origin root now goes direct unless that origin is a configured provider base URL; users whose gateway is configured via `provider.<id>.options.baseURL` are unaffected. - Kill switch / disable path: `excludeHosts` / `HEADROOM_OPENCODE_EXCLUDE_HOSTS` forces a host direct, and configuring the base URL or listing it in `wireRoots` forces a bare-path provider through the proxy. - Unsafe override required: no. - Qualification impact: none. - Rollback path: revert the commits; the transport and the committed bundle revert together. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title ## Additional Notes Residual, deliberately not solved and now stated in the README: `/api/v2/messages` and `/v2/responses` still route. No path shape separates those from a gateway rooted at `/api` or `/v2`; only the host or the request body could, and reading the body inside a sync `fetch` wrapper buys a new class of failure for a shape `excludeHosts` already covers. I did not add a known-host allowlist either: it can only recognise hosts someone already thought of, and it regresses compatible gateways silently — the failure mode #4747 was filed about. --------- Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
6.7 KiB
headroom-opencode
OpenCode integration helpers for Headroom. The package supports two integration paths:
- Provider config helpers used by
headroom wrap opencodeand persistent installs. - A native OpenCode plugin that installs Headroom transport interception and exposes the retrieve tool.
Install
npm install headroom-opencode
Building from source
Tsup 9 requires Node.js ^22.18.0 || ^24.11.0 || >=26.0.0. The current locked
graph also includes ini 7, which requires ^22.22.2 || ^24.15.0 || >=26.0.0.
These are development-install requirements; the published plugin and its host
retain their own runtime requirements. Node.js 24.22.2 is a verified choice
for this dependency graph. From plugins/opencode, run:
npm ci
npm test
npm run typecheck
npm run build
npm run build:standalone
For a reproducible real OpenCode 2.x → proxy → local SSE upstream check, see the transport runtime proof. It records the tested scope and limitations.
Provider Config Helpers
Use these helpers when you need to generate OpenCode config that routes a headroom provider through a running Headroom proxy.
import {
buildOpencodeConfigContent,
createHeadroomProvider,
} from "headroom-opencode";
const provider = createHeadroomProvider({ proxyPort: 8787 });
const config = buildOpencodeConfigContent({
proxyPort: 8787,
defaultModel: "claude-sonnet-4-6",
});
console.log(provider.provider.headroom.npm);
console.log(config.model);
The generated provider uses @ai-sdk/openai-compatible and points model requests at http://127.0.0.1:<port>/v1.
Native OpenCode Plugin
The package's default export is an OpenCode plugin that loads on both OpenCode 1.x and 2.x. Register it in opencode.json:
{
"plugin": [
["headroom-opencode", { "proxyUrl": "http://127.0.0.1:8787" }]
]
}
OpenCode 2.x migrates the 1.x plugin key automatically. To configure it the 2.x way, use "plugins": [{ "package": "headroom-opencode", "options": { ... } }].
The default export is { id: "headroom", server, setup }. OpenCode 1.x calls server (HeadroomPlugin) and 2.x calls setup (headroomSetup); each ignores the other's field. Both entry points:
- install Headroom transport interception for OpenCode provider traffic.
- expose the
headroom_retrievetool (a direct tool on 2.x, not only through code mode). - add
HEADROOM_ACTIVE,HEADROOM_PROXY_URL,HEADROOM_PROJECT(andHEADROOM_BACKENDwhen set) to shell command environments. - default to
HEADROOM_PROXY_URL, thenhttp://127.0.0.1:8787, when noproxyUrloption is supplied. - skip routing for hosts listed in
excludeHosts(orHEADROOM_OPENCODE_EXCLUDE_HOSTS); those requests go straight upstream with no compression or telemetry. - route the provider base URLs configured in OpenCode, so a compatible gateway with an arbitrary path prefix is still compressed. Only wire endpoints (
/chat/completions,/responses,/messages) under a configured base route; other paths on that host pass through.
Routing is decided by method, path shape, and configured bases, never by host identity. A POST routes when its path ends in a wire endpoint and the segment before that endpoint is a version (/v1, /v1beta, /v4), api, or a recognised root (backend-api, codex, openai, anthropic, zen) — or when it sits under one of OpenCode's configured provider base URLs. Everything else goes direct, including a bare /messages on an unknown host: that is the same shape as a messaging API, so becoming the bare path is not evidence of a provider. Two shapes still route without a configured base, because no path can tell them from a gateway: /api/v2/messages and /v2/responses. List the host in excludeHosts if one of your own services has that shape.
On 2.x, setup returns a cleanup that releases the transport, so hot reloads do not stack interceptors.
OpenCode 2.x keeps its own reference to fetch from before plugins load, so patching fetch alone does not catch its model traffic. For models with a resolved baseURL, the plugin also rewrites OpenAI chat-completions, Responses, and Anthropic Messages traffic so that it points at the proxy — including GitHub Copilot's Claude models. Anthropic Messages base URLs with a path prefix (for example a gateway rooted at /api/...) stay on their own base URL, because the proxy's Messages route ignores the original-path header and cannot preserve that prefix. Headers name the real upstream and request path, as the transport does, and authentication settings are retained. Local, excluded, and unsupported-protocol models are left alone. headroom wrap opencode routes native Anthropic and OpenAI through the proxy separately, via their baseURL.
To keep a provider off the proxy, list its host. An entry matches the host and all of its subdomains, and .example.com / *.example.com are accepted as spellings of example.com:
// opencode.json
{
"plugin": [["/path/to/headroom/providers/opencode/_dist", { "excludeHosts": ["opencode.ai"] }]]
}
or, for headroom wrap opencode and spawned Node child processes, set the environment variable before launching:
HEADROOM_OPENCODE_EXCLUDE_HOSTS="opencode.ai,.corp.internal" headroom wrap opencode
Retrieve Tool
import { createHeadroomRetrieveTool } from "headroom-opencode";
const retrieve = createHeadroomRetrieveTool({
proxyBaseUrl: "http://127.0.0.1:8787",
});
const result = await retrieve.execute({
hash: "0123456789abcdef01234567",
});
The tool calls /v1/retrieve/<hash> on the Headroom proxy.
Compression Helper
import { compressWithHeadroom } from "headroom-opencode";
const result = await compressWithHeadroom(
[{ role: "user", content: "Summarize this file" }],
{ model: "gpt-4o", proxyUrl: "http://127.0.0.1:8787" },
);
console.log(`Saved ${result.tokensSaved} tokens`);
Models
| Model | Context | Output |
|---|---|---|
claude-sonnet-4-6 |
200K | 16K |
claude-opus-4-6 |
200K | 16K |
claude-haiku-4-5-20251001 |
200K | 8K |
gpt-4o |
128K | 16K |
gpt-4.1 |
1M | 32K |
The provider config exposes these as headroom/<model> and defaults to headroom/claude-sonnet-4-6.
Environment
| Variable | Used by | Description |
|---|---|---|
HEADROOM_PROXY_URL |
Native plugin | Proxy URL used by HeadroomPlugin |
HEADROOM_OPENCODE_EXCLUDE_HOSTS |
Native plugin | Comma-separated hosts (and their subdomains) that bypass the proxy; the excludeHosts plugin option takes precedence |
HEADROOM_OPENCODE_WIRE_ROOTS |
Native plugin | Set from OpenCode's configured provider base URLs so spawned Node processes route the same bases; rarely set by hand |
OPENCODE_CONFIG_CONTENT |
OpenCode wrapper | Generated OpenCode provider, model, and MCP config |
License
Apache-2.0