mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
## 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>
152 lines
6.7 KiB
Markdown
152 lines
6.7 KiB
Markdown
# headroom-opencode
|
|
|
|
OpenCode integration helpers for Headroom. The package supports two integration paths:
|
|
|
|
1. Provider config helpers used by `headroom wrap opencode` and persistent installs.
|
|
2. A native OpenCode plugin that installs Headroom transport interception and exposes the retrieve tool.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](RUNTIME_PROOF.md). 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.
|
|
|
|
```ts
|
|
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`:
|
|
|
|
```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_retrieve` tool (a direct tool on 2.x, not only through code mode).
|
|
- add `HEADROOM_ACTIVE`, `HEADROOM_PROXY_URL`, `HEADROOM_PROJECT` (and `HEADROOM_BACKEND` when set) to shell command environments.
|
|
- default to `HEADROOM_PROXY_URL`, then `http://127.0.0.1:8787`, when no `proxyUrl` option is supplied.
|
|
- skip routing for hosts listed in `excludeHosts` (or `HEADROOM_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`:
|
|
|
|
```jsonc
|
|
// 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:
|
|
|
|
```bash
|
|
HEADROOM_OPENCODE_EXCLUDE_HOSTS="opencode.ai,.corp.internal" headroom wrap opencode
|
|
```
|
|
|
|
## Retrieve Tool
|
|
|
|
```ts
|
|
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
|
|
|
|
```ts
|
|
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
|