## Description The OpenCode plugin set `x-headroom-project` to the raw project name in `plugins/opencode/src/transport.ts` (two sites) and `plugins/opencode/src/plugin.ts`. A header value must be a ByteString, so a project name with any character above U+00FF (Thai, Chinese, Cyrillic, Arabic, `€`, emoji and so on) made `Headers.set` throw a `TypeError` inside the patched `fetch` and `https.request`, and every routed request failed. `headroom/cli/wrap.py` already percent-encodes this header for the same reason, and the proxy decodes it (`sanitize_project_name` calls `unquote`). This PR does the same in the plugin through one helper, `projectHeaderValue`, used at the three sites. Header values that contain only characters from the URL-unreserved set are sent as before. Closes #4779 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `plugins/opencode/src/transport.ts`: new exported `projectHeaderValue(project)` (`encodeURIComponent`), used for `x-headroom-project` in the fetch and Node request paths. - `plugins/opencode/src/plugin.ts`: the model headers set by `routeModelsThroughProxy` use `projectHeaderValue(project)`. - `plugins/opencode/src/transport.test.ts`: two tests with a Thai, Chinese, Cyrillic and Polish project name, one through `fetch` and one through Node `https.request` against a loopback server. - `headroom/providers/opencode/_dist/index.js` and `hook-shim/handler.js`: regenerated with `npm run build:standalone` (the CI step compares both with a fresh build; the staged blobs equal the build output). ## Testing - [ ] Unit tests pass (`pytest`) - [ ] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed This is a TypeScript-only change, so the Python checks above do not apply; the plugin equivalents were run (Node v24.22.2, vitest, `npm ci --ignore-scripts` from the committed lockfile, Ubuntu on WSL2). ### Test Output Fail before (`transport.ts` from `3c66c91e`, new tests kept): ```text vitest run src/transport.test.ts -t "non-Latin-1" × percent-encodes a non-Latin-1 project name instead of throwing on routed fetch calls × percent-encodes a non-Latin-1 project name on routed Node https.request calls TypeError: Cannot convert argument to a ByteString because the character at index 8 has a value of 3650 which is greater than 255. TypeError: Cannot convert argument to a ByteString because the character at index 0 has a value of 3650 which is greater than 255. Tests 2 failed | 47 skipped (49) ``` Pass after (this branch): ```text vitest run src/transport.test.ts -t "non-Latin-1" Tests 2 passed | 47 skipped (49) vitest run (whole plugins/opencode suite) Test Files 4 passed (4) Tests 81 passed (81) npm run typecheck -> exit 0 npm run build:standalone -> success; the committed bundle equals this build ``` ## Real Behavior Proof - Environment: Ubuntu on WSL2, Node v24.22.2, the committed wheel bundle `headroom/providers/opencode/_dist/index.js` (not vitest), and a loopback `node:http` server standing in for the proxy. - Exact command / steps: load the bundle (`origin/main` for "before", this branch for "after"), call `default.server({ project: { id: "p" }, directory: "/work" }, { proxyUrl: "http://127.0.0.1:<port>", project })`, then `fetch("https://api.anthropic.com/v1/messages", { method: "POST", body: "{}" })`, once with `project = "my-project"` and once with a Thai, Chinese and Cyrillic string. - Observed result: before, `my-project` was sent as `my-project` and the Thai/Chinese/Cyrillic name made `fetch` throw `TypeError: Cannot convert argument to a ByteString ... 3650 ... greater than 255` with 0 requests recorded. After, `my-project` is still sent as `my-project`, and the multilingual name reaches the recorder as `%E0%B9%82...%2F%E4%B8%AD%E6%96%87%2F%D0%9F...` which `decodeURIComponent` turns back into the original string. - Not tested: a real Headroom proxy (the recorder only shows what is sent; the decode step is from reading `headroom/proxy/project_name_policy.py`), OpenCode 1.x or 2.x hosts, and anything outside the proxy that reads the header. ## Runtime Rollout Safety - Rollout-managed feature(s): none; OpenCode plugin transport only. - Minimum rollout channel: n/a - Stable/default behavior changed: only for a project name with characters outside the URL-unreserved set. Those are now percent-encoded (a path such as `/home/u/app` is sent as `%2Fhome%2Fu%2Fapp`) and the proxy decodes them; plain names like `my-project` are unchanged. - Kill switch / disable path: n/a - Unsafe override required: no - Qualification impact: none - Rollback path: revert this commit. ## 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 - [ ] 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 (a CI guard enforces this) ## Additional Notes - The plugin test for `routeModelsThroughProxy` was not extended; the `plugin.ts` site is the same one-line call to the helper, covered by the bundle proof above. - The shell env variable `HEADROOM_PROJECT` is unchanged: it is an environment value, not a header. AI assistance: this change, its tests and the runs above were done with Claude (Sonnet 5.5), operated by me (HetCreep). 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4780" target="_blank"><picture><source media="(prefers-color-scheme: dark)" srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4" alt="Devin Review"></picture></a> <!-- devin-review-badge-end --> Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com> Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
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