Files
863b3c7cc7 fix(opencode): percent-encode the project name in x-headroom-project (#4780)
## 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>
2026-11-17 02:37:46 +05:30
..

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

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_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:

// 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