Commit Graph
9 Commits
Author SHA1 Message Date
ParideboyandJerrettDavis 87c12931fb fix(opencode): stop routing a host's bare /messages or /responses to the proxy (#4781) (#4791)
## 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>
2026-11-17 02:36:58 +05:30
ParideboyandJD Davis c48778c4ab fix(opencode): stop routing non-LLM hosts and paths to the proxy (#4747) (#4758)
Closes #4747.

## Description

The OpenCode transport shim decides whether to reroute a request from
the URL string alone. That decision had three blind spots: two too
literal, one too narrow.

**Hosts.** `isLoopback` compared the raw hostname against exactly
`"127.0.0.1"` and `"::1"`, so every other spelling of loopback counted
as remote and its request — with the caller's `Authorization` header —
went to the proxy:

| URL host | `URL.hostname` | old check | new check |
| --- | --- | --- | --- |
| `127.0.0.2` | `127.0.0.2` | remote | loopback |
| `127.1.2.3` | `127.1.2.3` | remote | loopback |
| `[::ffff:127.0.0.2]` | `[::ffff:7f00:2]` | remote | loopback |
| `localhost.` | `localhost.` | remote | loopback |
| `api.x.example.` | `api.x.example.` | not excluded | excluded |

The trailing-dot row is the same bug on the `excludeHosts` path:
`example.com.` is the fully qualified spelling of `example.com`, so an
excluded host was routed anyway.

**Paths.** Any path ending in `/messages` or `/responses` was treated as
an LLM endpoint, so Discord's `/api/v10/channels/123/messages` and a
forms API's `/forms/123/responses` were rerouted. That needs a wire root
in front of the endpoint.

**Configured bases.** The first version of that wire-root rule could
only recognise root names it knew (`v1`, `api`, `openai`, …), so a
compatible gateway configured at `https://gateway.invalid/tenant/acme`
lost its routing entirely: OpenCode 1.x sent
`/tenant/acme/chat/completions` through the patched `fetch` straight
upstream, with no compression and no telemetry. The plugin's own
`modelBaseRoutesThroughProxy` still accepted that base, so the transport
disagreed with the plugin. Provider base URLs from OpenCode's
configuration are now authoritative, matched by origin and path prefix
rather than by root name, and the path heuristics stay as the fallback
when no configuration is available.

## 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
- [ ] Refactoring (no functional changes)
- [ ] Tests only

## Reproduction

On `main`, with the plugin's transport installed:

```js
installHeadroomTransport({ proxyUrl: "http://127.0.0.1:8787/v1", excludeHosts: ["api.x.example"] });
await fetch("http://127.0.0.2:11434/v1/chat/completions", { method: "POST" });   // routed to proxy
await fetch("http://localhost./v1/chat/completions", { method: "POST" });        // routed to proxy
await fetch("https://api.x.example./v1/chat/completions", { method: "POST" });   // routed to proxy
await fetch("https://discord.com/api/v10/channels/123/messages", { method: "POST" }); // routed to proxy
```

A local provider on `127.0.0.2` or `[::ffff:127.0.0.2]`, a `.internal`
host spelled with a trailing dot, and a non-LLM `POST` all ended up at
the Headroom proxy instead of their own server.

For the configured-base half, on the previous head `b695e697` with a
provider base URL of `https://gateway.invalid/tenant/acme`:

```js
await fetch("https://gateway.invalid/tenant/acme/chat/completions", { method: "POST" });
// main: proxy. b695e697: gateway, with no x-headroom-base-url, so no compression.
```

## Changes Made

`plugins/opencode/src/transport.ts`:

- Added `canonicalHostname()` — lowercase, strip IPv6 brackets, strip
trailing dots — and used it in `isLoopback`, `isExcludedHost`, and
`normalizeExcludeHosts`, so all three agree on what a host *is*.
- `isLoopback` now covers all of `127.0.0.0/8` (not just `.0.1`),
`0.0.0.0`, `localhost`, `::1`, and IPv4-mapped IPv6. The mapped form is
tested as a full 32-bit address, because `URL` canonicalizes it to hex
(`127.1.2.3` → `::ffff:7f01:203`) and the last two octets share the low
16-bit group.
- `isLlmEndpointPath` now requires a *wire root* before the endpoint
suffix:
  - the URL is under a **configured provider base** (see below), **or**
- the segment immediately before the suffix is a version (`v1`,
`v1beta`, `v4`) or a base a compatible gateway mounts the wire directly
under (`api`), which keeps prefixed gateways working
(`/api/coding/paas/v4/chat/completions`, `/base/v1/messages`,
`/zen/v1/responses`, and a provider base URL of
`https://gateway.example/api`), **or**
- the path contains a named root (`openai`, `anthropic`, `zen`, `codex`,
`backend-api`) anywhere, which is what Azure OpenAI needs — its
deployment name sits between `/openai/` and the endpoint
(`/openai/deployments/{name}/chat/completions`).
- A bare `/messages` or `/responses` (no preceding segment) still
routes.
- Position matters for the version/`api` branch: `api` counts only when
it abuts the endpoint, so `/api/chat/completions` routes while Discord's
`/api/v10/channels/123/messages` (immediate segment `123`) does not. The
same is true of the version branch — a version segment *anywhere* would
be too weak.
- Gemini's `:generateContent` / `:streamGenerateContent` suffixes are
unchanged and still need no wire root.
- Added `WireRoot` / `normalizeWireRoots` / `isConfiguredWireRoot`: a
configured base is matched by **origin plus path prefix**, and only when
the URL also ends in a wire endpoint. So an OpenAI-compatible provider
at `/tenant/acme` routes its `/tenant/acme/chat/completions`, while
`/tenant/acme/files/1` on the same host passes through, and a different
origin sharing that path prefix does not match at all. Malformed entries
are skipped rather than disabling the set.
- `installHeadroomTransport` takes `wireRoots` and exports the effective
set to child processes as `HEADROOM_OPENCODE_WIRE_ROOTS`, so the
`--import` hook shim routes the same bases; it is removed from the
environment when empty, like `HEADROOM_OPENCODE_EXCLUDE_HOSTS`.
- `setHeadroomWireRoots()` widens a live transport when configured bases
are discovered later, so routing can start before OpenCode answers.
- Regenerated `headroom/providers/opencode/_dist/index.js` and
`headroom/providers/opencode/hook-shim/handler.js` from `npm run
build:standalone` (CI `cmp`s them).

`plugins/opencode/src/plugin.ts`:

- 1.x reads `client.config.get()` and `client.provider.list()` **without
awaiting them**, and applies **each response as it arrives**: the two
reads are independent, so a fulfilled `config.get()` widens routing even
while `provider.list()` is still pending. A round trip to the server
that is loading the plugin cannot be allowed to gate plugin startup, a
server that is not answering yet must not disable routing, and a stalled
`/provider` call must not suppress a base the config already reported. A
failed read costs only its own bases; requests before either answer use
the path heuristics.
- 2.x reads the base URLs its own `ctx.model.transform` already sees, so
no extra round trip is needed.
- `HeadroomOpenCodePluginOptions.wireRoots` lets a user supply a base
the plugin cannot see; normally it is unused.

The residual over-match is `/api/v2/messages`, which still routes;
distinguishing it from a provider needs the host or the body, and
`excludeHosts` already covers any host a user controls. That trade-off
is recorded in the code comment rather than left implicit.

## Testing

- [x] New tests added for new functionality
- [x] Manual testing performed

Six new tests, all tagged `#4747`:

1. non-LLM `POST` paths that merely end in an endpoint
(`discord.com/api/v10/channels/123/messages`, `discord.com/api/v9/...`,
`forms.example.com/forms/123/responses`,
`chat.example.com/rooms/42/chat/completions`) pass through untouched,
with no `x-headroom-base-url` and no session token added.
2. provider-rooted wire paths still route: bare `/messages`,
`/responses`, `/api/chat/completions` (a gateway base URL of `.../api`),
`/api/v2/chat/completions`, `/openai/deployments/x/chat/completions`,
`/zen/v1/responses`, `/backend-api/codex/responses`.
3. every loopback spelling (`127.0.0.1`, `127.0.0.2`, `127.1.2.3`,
`127.255.255.254`, `localhost.`, `[::1]`, `[::ffff:127.0.0.1]`,
`[::ffff:127.1.2.3]`) and a trailing-dot excluded host stay off the
proxy for `fetch`.
4. the same failures stay off the proxy for Node's `http.request`
(`http://` loopbacks) and `https.request` (the excluded and
Discord-shaped `https://` cases). This one spies on both, because real
`https.request` rejects an `http://` URL — asserting one against the
https spy would have proved nothing.
5. a configured base with no version or reserved prefix
(`https://gateway.invalid/tenant/acme`) routes
`/tenant/acme/chat/completions` in **both** the fetch and the Node
request paths, with the right `x-headroom-base-url`;
`/tenant/acme/files/1` on the same host and origin stays unrouted; and
the same path on a different origin stays unrouted. A separate plugin
test asserts that a base URL returned by `client.config.get()` reaches
the transport.
6. a config response applies while `provider.list()` **never settles**:
the configured fetch and Node paths already route, and a non-endpoint
path on the same base still passes through. This is the
partial-availability case from review, and it fails on the previous head
(`expected [] to include 'https://gateway.invalid/tenant/acme'`).

Red/green check for test 5 against the previous head `b695e697`:

```
$ git checkout b695e697 -- plugins/opencode/src/transport.ts
$ npx vitest run src/transport.test.ts
 Test Files  1 failed (1)
      Tests  1 failed | 45 passed (46)

AssertionError: expected 'https://gateway.invalid/tenant/acme/c…' to be an instance of URL
```

The fetch assertion is where it fails first: on `b695e697` the request
passes through untouched, so the recorded first argument is still the
original URL string. Restore the branch sources and all 78 pass.

Earlier red/green, still true: tests 1, 3 and 4 fail before the first
fix; the `/api/chat/completions` assertion fails against the first
commit's rule; test 4 fails against `upstream/main`'s `transport.ts`
(`127.0.0.2` was proxied).

```
$ npm test          → Test Files 4 passed (4) | Tests 78 passed (78)
$ npm run typecheck → clean
$ npm run build     → success
$ npm run build:standalone → success
```

## Real Behavior Proof

- Environment: Windows 11, Node v26.10.0, npm 11. The probe loads the
*built* `dist-standalone/index.js` bundle (before = the committed `HEAD`
bundle, after = this branch), wires the plugin's `server` hook exactly
as OpenCode does, points `proxyUrl` at a real `http.createServer`
listener on `127.0.0.1:19400`, and starts real target servers on
`127.0.0.1:19401`, `127.0.0.2:19401`, `[::1]:19401`, plus the machine's
LAN IPv4 on `:19401`. Every request is a real `fetch` over the stack —
no mocks. Two non-loopback cases use `.invalid` hosts so they cannot
leave the machine; they only need to be *classified*, and the shim drops
the response on the floor. The configured-base rows run on the LAN
address, because loopback is deliberately never routed.
- Exact command / steps: `node proof4747.mjs file:///<abs path to
bundle>` (10-row probe); `node proof4747-shim.mjs <hook-shim/handler.js>
<child>` (child `--import` shim probe); `node proof4747-partial.mjs
file:///<bundle>` (stalled discovery probe)

**Before (committed `HEAD` bundle):**

```
┌──────────────────────────────────────┬──────────┬──────────┬─────────┬──────────────┐
│ label                                │ landed   │ expect   │ verdict │ outcome      │
├──────────────────────────────────────┼──────────┼──────────┼─────────┼──────────────┤
│ loopback 127.0.0.2                   │ target   │ target   │ ok      │ 200 target   │
│ loopback mapped v6                   │ target   │ target   │ ok      │ 200 target   │
│ loopback trailing dot                │ target   │ target   │ ok      │ 200 target   │
│ non-LLM path (Discord shape)         │ target   │ target   │ ok      │ 200 target   │
│ bare loopback endpoint               │ target   │ target   │ ok      │ 200 target   │
│ custom gateway base /api             │ proxy    │ proxy    │ ok      │ 200 proxy    │
│ configured base /tenant/acme         │ target   │ proxy    │ WRONG   │ 200 target   │
│ configured base, non-endpoint path   │ target   │ target   │ ok      │ 200 target   │
│ real provider endpoint               │ proxy    │ proxy    │ ok      │ 200 proxy    │
│ Azure-style endpoint                 │ proxy    │ proxy    │ ok      │ 200 proxy    │
└──────────────────────────────────────┴──────────┴──────────┴─────────┴──────────────┘
proxy saw: ['/v1/chat/completions', '/v1/messages', '/v1/chat/completions']
target saw: ['/v1/chat/completions', '/v1/chat/completions', '/v1/chat/completions',
             '/api/v10/channels/123/messages', '/chat/completions',
             '/tenant/acme/chat/completions', '/tenant/acme/files/1']
```

**After (this branch):**

```
┌──────────────────────────────────────┬──────────┬──────────┬─────────┬──────────────┐
│ label                                │ landed   │ expect   │ verdict │ outcome      │
├──────────────────────────────────────┼──────────┼──────────┼─────────┼──────────────┤
│ loopback 127.0.0.2                   │ target   │ target   │ ok      │ 200 target   │
│ loopback mapped v6                   │ target   │ target   │ ok      │ 200 target   │
│ loopback trailing dot                │ target   │ target   │ ok      │ 200 target   │
│ non-LLM path (Discord shape)         │ target   │ target   │ ok      │ 200 target   │
│ bare loopback endpoint               │ target   │ target   │ ok      │ 200 target   │
│ custom gateway base /api             │ proxy    │ proxy    │ ok      │ 200 proxy    │
│ configured base /tenant/acme         │ proxy    │ proxy    │ ok      │ 200 proxy    │
│ configured base, non-endpoint path   │ target   │ target   │ ok      │ 200 target   │
│ real provider endpoint               │ proxy    │ proxy    │ ok      │ 200 proxy    │
│ Azure-style endpoint                 │ proxy    │ proxy    │ ok      │ 200 proxy    │
└──────────────────────────────────────┴──────────┴──────────┴─────────┴──────────────┘
proxy saw: ['/v1/chat/completions', '/v1/chat/completions', '/v1/messages',
            '/v1/chat/completions']
target saw: ['/v1/chat/completions', '/v1/chat/completions', '/v1/chat/completions',
             '/api/v10/channels/123/messages', '/chat/completions', '/tenant/acme/files/1']
```

All ten rows correct after the patch. The configured base routes; the
unrelated path on that same host still reaches the target; the three
pre-existing provider cases still reach the proxy — so the fix redirects
false positives without disarming the shim.

- Observed result: all ten rows `ok` after the patch; inside the before
bundle the same probe reports `configured base /tenant/acme → target,
WRONG`, and the same two rows for the child `--import` shim (`shim:
WRONG` before, `shim: ok` after), and for the stalled discovery probe
(both wire calls `WRONG` before, all `ok` after). Full tables above.

**Child process (the `--import` hook shim), before and after.** A real
Node child loads the shipped `hook-shim/handler.js` with the env the
plugin exports, then makes two wire calls and one non-endpoint call
against the configured base:

```
before:  /tenant/acme/chat/completions -> target   /tenant/acme/messages -> target
         proxy saw: []                              shim: WRONG
after:   /tenant/acme/chat/completions -> proxy    /tenant/acme/messages -> proxy
         /tenant/acme/files/1 -> target             proxy saw: ['/v1/chat/completions', '/tenant/acme/messages']
                                                    shim: ok
```

**Partial availability (`config.get()` answers, `/provider` stalls),
before and after.** Real built bundle, real listeners, `provider.list()`
returns a promise that never settles:

```
┌──────────────────────────────────────────────────┬────────┬────────┬─────────┐
│ label                                            │ landed │ expect │ verdict │
├──────────────────────────────────────────────────┼────────┼────────┼─────────┤
│ fetch: configured base, provider.list pending    │ target │ proxy  │ WRONG   │   before
│ fetch: non-endpoint path on that base            │ target │ target │ ok      │
│ node http: configured base, provider.list pending│ target │ proxy  │ WRONG   │
└──────────────────────────────────────────────────┴────────┴────────┴─────────┘

after: all three ok — both wire calls reach the proxy, the non-endpoint path does not.
```

- Not tested: no live provider traffic (no API keys were used); a real
`headroom wrap opencode` session against a hosted provider; macOS/Linux.
The loopback and LAN target servers are local stand-ins for a
self-hosted or gateway OpenAI-compatible endpoint (Ollama, LM Studio,
vLLM, a proxy at `/tenant/acme`), which is the shape from the issue. The
config-read path is exercised with a stubbed `client` in the unit test,
not inside a running OpenCode server.

## Runtime Rollout Safety

- Rollout-managed feature(s): none — the OpenCode transport shim is not
behind a rollout flag; it ships as the committed wheel bundle.
- Minimum rollout channel: n/a (no rollout-gated behaviour).
- Stable/default behavior changed: yes, deliberately. Loopback spellings
beyond `127.0.0.1`/`::1` and trailing-dot host spellings now stay off
the proxy; non-LLM paths ending in `/messages` or `/responses` (Discord,
forms shapes) stay off the proxy; configured provider bases route again
(they routed on `main`). Traffic that routed before and still must is
asserted by existing tests (`/base/v1/messages`,
`/api/coding/paas/v4/chat/completions`, `opencode.ai/zen/v1/responses`,
Gemini `:generateContent`).
- Kill switch / disable path: uninstall the transport (`headroom.wrap`
without `opencode`, remove the plugin), or add a provider host to the
`excludeHosts` option / `HEADROOM_OPENCODE_EXCLUDE_HOSTS` env;
`HEADROOM_OPENCODE_TRANSPORT_PROXY_URL` unset also disables the shim.
- Unsafe override required: none. One new optional option (`wireRoots`)
and one new environment variable (`HEADROOM_OPENCODE_WIRE_ROOTS`), both
default to unset; existing calls are unaffected. No wire format or
header changes.
- Qualification impact: route classification only; the proxy wire
protocol is unchanged, so qualification suites that talk to the proxy
are unaffected.
- Rollback path: revert the commit; nothing is persisted and no
migration exists. The committed wheel bundles are byte-identical to `npm
run build:standalone` output (CI `cmp` gate).
- A request that stops routing now reaches its original URL with the
caller's own headers intact — a failure there is a normal provider
error, not a dropped request. Configured-base routing never widens an
arbitrary path: it still requires a wire endpoint, so WebFetch-style
traffic on a provider host is unaffected. The config read is
non-blocking and failure-tolerant; each discovery response applies
independently, and a rejected lookup falls back to the path heuristics
without failing a session. The residual over-match (`/api/v2/messages`)
is inherited from `main` and covered by `excludeHosts`.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review
- [x] Follows `CONTRIBUTING.md` (reproduction + failing-before test +
real behavior proof)
- [x] No `CHANGELOG.md` edit
- [x] Typecheck, tests, both builds run locally
- [x] Behaviour that must be preserved is covered by pre-existing tests

Note for reviewers: #4748 and #4749 are open against the same file
(`transport.ts`) and the same committed bundles. Whichever lands first,
the others will need a rebase and a `build:standalone` refresh; the
conflicts are all in disjoint functions.

Review findings from #4758 addressed in b695e697: `api` is now an
accepted immediate wire root (a provider base URL of
`https://gateway.example/api` routes again, while Discord's
`/api/v10/...` stays out), and the Node test spies on both
`http.request` and `https.request` instead of asserting an `http://` URL
against the https spy, which real Node rejects.

Addressed in 98b5ba2a: configured compatible provider bases are
preserved rather than dropped. Provider base URLs from OpenCode's
configuration are authoritative and matched by origin plus path prefix,
so `/tenant/acme/chat/completions` routes again while Discord and forms
paths stay out; the root-name allowlist remains only as the fallback for
when no configuration is available. Covered in both the fetch and Node
request paths, plus the child-process shim.

Addressed in 3e84b5f2: the two discovery reads no longer gate each
other. Each fulfilled response applies its bases immediately, so a
successful `config.get()` routes the configured wire while
`provider.list()` is still pending; a stalled `/provider` no longer
leaves a known base bypassing Headroom. Startup still never awaits
discovery, and a failed read costs only its own bases.

## Checklist

- [x] My code follows the style of this project
- [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 added tests that prove my fix is effective
- [x] New and existing unit tests pass locally

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-11-10 23:49:30 -06:00
Chen YufeiyangandJD Davis 3d9a6f2cf7 fix(opencode): route Copilot Claude models through the proxy (#4594)
## Description

Closes #4248. The OpenCode 2.x plugin routes models through Headroom by
rewriting model `baseURL`s in `ctx.model.transform`, but it recognized
only the OpenAI wires (`openai-compatible`, `*/chat`, `*/responses`).
Copilot's Claude models use `@opencode/ai/providers/anthropic` (Messages
wire), so they were skipped and their requests never reached the proxy,
while Copilot GPT models kept working.

`modelWireSuffix` now also maps `anthropic`, `anthropic-compatible` and
model-level `*/messages` packages to `/messages`, reusing the existing
rewrite. The config-level `headroom wrap opencode` path cannot cover
Copilot because OpenCode creates that provider dynamically.

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

<details>
<summary>changes details</summary>

- `plugins/opencode/src/plugin.ts`: rename `openAiWireSuffix` to
`modelWireSuffix`, map the Anthropic Messages wires to `/messages`.
- `plugins/opencode/README.md`: document that Anthropic Messages models
are rewritten too.
- `plugins/opencode/src/plugin.test.ts`: three new cases plus a narrowed
negative case.
- `headroom/providers/opencode/_dist/index.js`: rebuilt so the wheel
bundle stays byte-identical (CI `cmp` gate).
</details>

## Testing

<details>
<summary>testing details</summary>

- [x] Unit tests pass (`npm test -- --maxWorkers=2`: 66 passed at
current head)
- [x] Type checking passes (`npm run typecheck`)
- [x] Linting: repo lint is Python-only; plugin gates are typecheck,
build, test, bundle `cmp`, all run
- [x] New tests added
- [x] Manual testing performed — actual OpenCode CLI plus real proxy and
controlled upstream; live Copilot not tested

### Test Output

<!-- Paste relevant command output or artifact links here -->

<details><summary>commands and output</summary>

```text
npm test -- --maxWorkers=2 -> 4 files, 66 passed at 95ef917320 | npm run typecheck -> exit 0 | cmp dist-standalone/index.js headroom/providers/opencode/_dist/index.js -> BUNDLE_MATCH
```

The earlier red/green check recorded three new rewrite cases failing
before the fix (`3 failed | 61 passed`). Fresh current-head validation
is 66/66 plugin tests plus a successful no-emit typecheck;
full-repository Python pytest/Ruff were not run for this transport-only
verification.

</details>
</details>

## Real Behavior Proof

- Environment: Current head `95ef9173`, macOS arm64, official OpenCode
2.2.5, Python 3.12.8, Node 26.13.0; real plugin, Anthropic adapter and
Headroom proxy; local SSE upstream; Python-only transport mode.
- Exact command / steps: Build both plugin bundles, then run the runtime
harness with the official CLI in four scenarios. Exact commands, macOS
fixture adaptation, and the committed Linux reproduction are in the
details below.
- Observed result: All four actual CLI scenarios passed; auth retained,
internal headers stripped, streamed text and `step_finish` returned.
Current-head plugin tests 66/66, typecheck and byte-for-byte wheel
bundle comparison pass.
- Not tested: Live Copilot account/discovery or endpoint compatibility,
live z.ai, Rust/compression/cache, TLS, retries, latency, production
rollout, and other OpenCode versions. Full limits are below.

| Actual OpenCode scenario | Plugin | Proxy POSTs | Upstream POSTs |
Observed upstream path |
| --- | --- | --- | --- | --- |
| Baseline | disabled | 0 | 2 | `/messages` |
| Copilot-shaped root URL | enabled | 2 | 2 | `/v1/messages` |
| `/v1` gateway | enabled | 2 | 2 | `/v1/messages` |
| Prefixed gateway | enabled | 0 | 2 | `/api/coding/paas/v4/messages` |

<details>
<summary>Current-head transport evidence and platform-specific harness
setup</summary>

- Environment: Fresh run on 2026-11-04 at 22:10 UTC, PR head
`95ef9173200eb3b0f047e8fe661e1d9924d41c82`; macOS 27.3 arm64, Python
3.12.8, Node 26.13.0, npm 11.20.0, official installed **OpenCode 2.2.5**
CLI, source Headroom 0.42.1-dev, headroom-opencode 0.42.0. OpenCode
loaded the built standalone plugin itself and used its real
`@opencode/ai/providers/anthropic` adapter. Only the upstream API was a
strict-path local SSE fixture. The proxy explicitly ran in **Python-only
degraded mode**, with `HEADROOM_REQUIRE_RUST_CORE=false`, `--no-optimize
--no-cache`; Rust/compression is outside this proof.
- Exact command / steps: Install proxy dependencies with `uv sync
--frozen --extra proxy --no-default-groups --no-install-project --python
<CPython-3.12.8>`. In `plugins/opencode`, run `npm ci --ignore-scripts
--no-audit --no-fund --fetch-timeout=45000`, `npm run build`, and `npm
run build:standalone`. Run `.venv/bin/python
.cache/runtime-proof-macos.py --opencode
/Applications/OpenCode.app/Contents/Resources/opencode-cli --output
.cache/runtime-proof-macos`. This local copy of the checked-in [runtime
harness](https://github.com/headroomlabs-ai/headroom/blob/95ef9173200eb3b0f047e8fe661e1d9924d41c82/plugins/opencode/scripts/runtime-proof.py)
adapts its Linux loopback fixture to macOS as detailed below. For each
scenario the harness starts a real Headroom proxy and upstream, then
executes `opencode-cli run --standalone --print-logs --log-level debug
--format json 'Reply with HEADROOM_RUNTIME_OK.'` with isolated config,
synthetic auth, model-catalog fetching/updates disabled and a 60-second
timeout. It never invokes `headroomSetup` manually or replaces the model
request with `fetch`.
- Observed result: **All four actual CLI scenarios passed in 40.05
seconds.** Both title and user-turn requests traversed the expected
route, preserved the exact synthetic bearer/API-key values, and sent no
internal `x-headroom-*` headers upstream. Every user turn produced the
text event `HEADROOM_RUNTIME_OK` and a completed `step_finish` after
individual SSE events were flushed by the fixture. The rebuilt
standalone bundle matched the checked-in wheel bundle byte-for-byte,
SHA-256
`78fae6e51ef5d1c534a3299216ba3b467131c17594de34f0fe8bb7b5be4b7533`. No
tracked files or lockfiles changed during this run; all eight
proxy/upstream listening ports were closed afterward and no owned
CLI/proxy process remained.
- Not tested: Live GitHub Copilot discovery, subscription auth/token
refresh, Copilot-specific headers, actual model inference, or whether
the live Copilot origin accepts `/v1/messages`. This is a configured
Copilot-shaped provider, **not** native Copilot discovery. The prefix
control uses the real Anthropic adapter, not a live z.ai account or its
specific adapter. Rust core, optimization/compression/cache,
HTTPS/HTTP2, latency/backpressure, retry/rate-limit behavior, production
rollout, and OpenCode versions other than 2.2.5 were not exercised.

The proxied root-URL run recorded the actual OpenCode user agent and
original path at Headroom:

```text
proxy inbound: POST /v1/messages
user-agent: opencode/latest/2.2.5/cli
x-headroom-original-path: /messages
proxy outbound: POST http://[::ffff:7f00:1]:<fixture-port>/v1/messages
upstream: model=claude-sonnet-4-6, stream=true
upstream: authorization and x-api-key exactly matched synthetic fixtures
upstream: anthropic-version=2023-06-01; no x-headroom-* headers
client: text=HEADROOM_RUNTIME_OK; step_finish present
```

The root origin deliberately distinguishes direct `/messages` from
proxied `/v1/messages`. The fixture rejects an unexpected endpoint
rather than answering every path. These observations establish the
plugin/proxy transport boundary; they do **not** establish live Copilot
endpoint compatibility. The `/v1` origin remains `/v1/messages`, and the
prefixed origin remains `/api/coding/paas/v4/messages` with zero model
POSTs reaching Headroom.

The committed harness originally binds `127.0.0.2`, unavailable on this
macOS host (`Errno 49`). The ignored local copy uses an IPv4-mapped
loopback address with an IPv6 HTTP server and WHATWG-normalized fixture
URLs. It also fixes its checkout-relative path after copying, explicitly
allowlists only that fixture origin, sets supported offline/update
flags, creates its isolated proxy cache, accepts an existing isolated
home directory, and bounds each CLI run to 60 seconds. It does not
change production code or the expected endpoint/auth/SSE assertions. No
network interfaces or account settings were changed. All server
processes are scoped to the harness and terminated/waited in cleanup.

For the original independently recorded Linux run, reproducible
commands, and committed machine-readable results, see
[RUNTIME_PROOF.md](https://github.com/headroomlabs-ai/headroom/blob/95ef9173200eb3b0f047e8fe661e1d9924d41c82/plugins/opencode/RUNTIME_PROOF.md)
and
[runtime-proof-result.json](https://github.com/headroomlabs-ai/headroom/blob/95ef9173200eb3b0f047e8fe661e1d9924d41c82/plugins/opencode/scripts/runtime-proof-result.json).
Those artifacts explicitly identify their earlier source revision and
environment; the current-head macOS build hash above is from this fresh
run. Both proofs execute an actual OpenCode 2.x process. The earlier
PR-body experiment that manually supplied a minimal plugin context and
Node `fetch` has been superseded here.

</details>

## Runtime Rollout Safety

- Rollout-managed feature(s): none.
- Minimum rollout channel: n/a.
- Stable/default behavior changed: only previously skipped Anthropic
Messages models are rewritten; the negative test pins the rest.
- Kill switch / disable path: disable the plugin.
- Unsafe override required: no.
- Qualification impact: none expected.
- Rollback path: revert the commit; no state changes.

## 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`

## Screenshots (if applicable)

N/A — no UI change.

## Additional Notes

The rebuilt `_dist` bundle is part of the diff because CI enforces byte
equality with `dist-standalone`. Actual OpenCode transport is now
verified with a controlled upstream. Live provider/account behavior and
the additional limits listed above remain unverified.

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4594"
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: JD Davis <mxjerrett@gmail.com>
2026-11-04 23:09:28 -06:00
dependabot[bot]andJerrettDavis 99e223c0e2 deps: Bump tsup from 8.5.1 to 9.0.0 in /plugins/opencode (#4385)
Build the OpenCode plugin with the patched esbuild line inside tsup's
supported range. Headroom's existing esbuild 0.28 security override is
outside tsup 8.5.1's ^0.27.0 declaration. Tsup 9 declares ^0.28.2, so
retain the major upgrade and raise the override floor from ^0.28.1 to
^0.28.2. The original tsup 9 lock still selected 0.28.1; this follow-up
corrects that mismatch and documents the source-build requirements.

## Dependency assessment

- **Version reason:** use an upstream-supported build combination for
the existing dependency-security mitigation, rather than forcing the
selected esbuild release outside the old bundler's range. This does not
claim a new advisory in 0.28.1 or that the old built plugin was
demonstrated broken. Tsup remains the existing builder;
[v9](https://github.com/egoist/tsup/releases/tag/v9.0.0) also changes
debug/obug, watchers and related toolchain packages.
- **Maintenance/security:** reviewed the published release/manifest and
resolved graph. Fresh audit reports zero vulnerabilities; this does not
imply every upstream project has a spotless history. Platform-selector
metadata outside the esbuild refresh is preserved instead of accepting
unrelated npm-version normalization.
- **Node/build boundary:** tsup requires `^22.18.0 || ^24.11.0 ||
>=26.0.0`; the current graph's ini 7 also requires `^22.22.2 || ^24.15.0
|| >=26.0.0`. The README documents both and the verified Node 24.22.2
choice. Published plugin/host runtime declarations are unchanged. An
earlier Node 22.22.0 pass emitted the existing ini warning; acceptance
uses the supported Node 24 install.
- **Native/install/network:** existing esbuild/Rollup platform code and
lifecycle scripts remain build inputs. Rollup's optional GNU Linux-x64
LZMA and Android-x64 bindings are present; the LZMA entry is a real
optional dependency, not an orphan. Windows x64 installation/build was
tested; these non-Windows paths were not. No new install-script flag is
introduced. Existing plugin runtime dependencies are unchanged; tsup
remains a development dependency. npm and host support-dependency
installation use the registry. No plugin is published and no
inference/provider message is requested.

The branch is synchronized with main's merged security and SDK updates.

## Real behavior proof

Windows x64 / Node 24.22.2 / npm 10.9.4, fresh isolated checkout. From
`plugins/opencode`, under that Node:

```bash
npm ci --ignore-scripts=false --no-audit --no-fund
npm test
npm run typecheck
npm run build
npm run build:standalone
npm audit --json
node ../../scripts/verify_opencode_bundle.mjs .
```

The install has no engine warning; **61 tests pass**, typecheck and both
builds succeed, audit reports zero vulnerabilities. The committed
portable proof imports actual `dist/index.js` and
`dist-standalone/index.js`, invokes the built server entry and performs
real chat/retrieve HTTP requests against an ephemeral loopback fixture.
It asserts original upstream/path, project/session headers, response and
retrieval content; output reports PASS. The plugin routes the synthetic
OpenAI URL to the fixture. Hooks/sockets/processes are disposed. This is
built-artifact wire behavior, not a claim that the fixture is the Python
service.

**Actual host loading:** installed official `opencode-ai@1.19.4`,
matching the installed 1.x plugin SDK, into a task-only prefix/cache.
Its native Windows `opencode.cmd debug config --print-logs` ran from an
isolated task workspace with the built main entry
`file:///G:/git/headroom-dep4385/plugins/opencode/dist/index.js`
configured directly. No wrapper was used for this check. It exited 0
with successful bootstrap/configuration/disposal and no loader error. A
separate instrumentation probe preserved the exported object shape and
delegated its actual `server` function; it recorded `id=headroom`,
retrieval-tool registration and the shell-environment hook. It did not
adapt the object into a legacy function.

The host's XDG config/data/state/cache point at task-only directories.
Enabled providers are empty; auto-update, remote model fetching and
default plugins are disabled. Credential environment names are removed
in the child shell only; user home/config/auth files are not repurposed.
The CLI installed support dependencies in the isolated config, so
registry traffic occurred. No inference command or provider action was
requested.

Node syntax and whitespace checks pass. Independent technical review
found no code or dependency-policy blocker in the corrected build
range/source-runtime boundaries.

Untested: actual OpenCode 2.x, registry-tarball plugin installation, the
Python compression proxy in this smoke, streaming, live providers,
hook-shim spawning, non-Windows native installation, or production
publishing. Current-head hosted CI must pass before approval.

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-03 08:45:19 -06:00
1d4b357ca7 feat(opencode): support the OpenCode 2.x plugin API (#3999)
## Description

Takeover of #3719 by @laurence-diack-pk, who has been unavailable since
Sep 23 and whose branch was left conflicted with `main`. The original
commit is preserved and @laurence-diack-pk remains its author; this
branch adds follow-up commits addressing @JerrettDavis's review and the
findings from live OpenCode 2.x testing.

It makes the OpenCode plugin and `headroom wrap opencode` work on both
OpenCode 1.x and 2.x. On 2.x the 1.x function plugin was silently
dropped (the loader requires a `{ id, setup }` default export loaded
from a directory), and Effect's `FetchHttpClient` keeps its own `fetch`
reference from before plugins load — so `wrap opencode` loaded no plugin
and routed nothing.

Closes #3669. Supersedes #3719.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)

## Changes Made

Carried from #3719:
- One plugin for both versions: default export `{ id: "headroom",
server, setup }`; 1.x calls `server`, 2.x calls `setup`.
- 2.x `setup`: registers `headroom_retrieve` via `ctx.tool.transform`
(`codemode: false`), sets `HEADROOM_*` shell env through the
`create.before` hook, and returns a cleanup that releases the refcounted
transport so hot reloads do not stack interceptors.
- 2.x model routing: `ctx.model.transform` points remote OpenAI-wire
models at the proxy with `x-headroom-base-url` /
`x-headroom-original-path` headers, since 2.x keeps its own `fetch`
reference and the transport patch alone misses model traffic.
- Wheel ships the bundle as `_dist/index.js`;
`headroom_opencode_plugin_path()` returns the directory; `wrap opencode`
adds `--standalone` on 2.x so the private server sees
`OPENCODE_CONFIG_CONTENT`.

Follow-up commits (review from #3719 + live testing):
- Rebased on current `main` (0.40.0). Fixed the routing-contract
conflict: replaced `routesThroughProxy` (TS2554 against `shouldRoute`'s
3-arg signature) with `modelBaseRoutesThroughProxy`, a deliberate
model-base eligibility check that keeps the shared protocol / loopback /
proxy-origin / excluded-host contract but drops the endpoint-suffix
requirement, since 2.x hands us model base URLs (e.g. `/v1`), not
inference endpoints.
- `setup` now resolves the effective `excludeHosts` once (option over
`HEADROOM_OPENCODE_EXCLUDE_HOSTS`) and applies it to both the transport
install and the model rewrite, with new tests for both paths.
- Fixed `test_build_launch_env_with_project` to decode
`OPENCODE_CONFIG_CONTENT` instead of substring-matching the raw path,
which JSON backslash escaping makes impossible on Windows.
- `opencode_major_version` now reads the `v2` channel marker in dev
builds (`opencode v0.0.0-v2-<stamp>`), which previously parsed as major
0, so `wrap` skips `--standalone` and the private server never loads
Headroom's config.
- Rebuilt `_dist/index.js` and `hook-shim/handler.js`; drift check
clean.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .` — run on the changed paths)
- [x] Type checking passes (`mypy headroom` — run on the changed paths)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
# plugins/opencode
$ npm ci && npm run typecheck && npm run build:standalone && npm test
tsc: clean (no TS2554)
vitest: Test Files 3 passed (3) | Tests 45 passed (45)
$ cmp dist-standalone/index.js ../../headroom/providers/opencode/_dist/index.js          # identical
$ cmp dist-standalone/hook-shim/handler.js ../../headroom/providers/opencode/hook-shim/handler.js  # identical

# focused Python suites (same set as #3719, plus the 2.x dev-build version case)
$ pytest tests/test_providers_opencode_plugin_path.py tests/test_providers_opencode_config.py \
    tests/test_providers_opencode_install.py tests/test_cli/test_wrap_opencode.py \
    tests/test_mcp_registry_opencode.py tests/test_learn/test_opencode_scanner.py -q
193 passed in 1.10s

$ ruff check / ruff format --check on changed paths: clean
$ mypy headroom/providers/opencode headroom/cli/wrap.py: Success: no issues found
```

## Real Behavior Proof

- Environment: macOS arm64, Node v26.10.0, Python 3.13, headroom from
this branch (0.41.0-dev). Tested against two real OpenCode 2.x clients,
each in throwaway XDG dirs with its own proxy port:
  - `opencode 2.0.19` (official 2.x binary);
- OpenCode 2.x head built from `anomalyco/opencode@v2`
(`0.0.0-v2-202610061051`, Bun 1.4.2, `bun run script/build.ts --single`
in `packages/cli`).
- Exact command / steps: throwaway XDG dirs and a dedicated proxy port;
fake key first (routing proof), then the real key (end-to-end proof):
  ```bash
  # fake key first (routing proof), then the real key (end-to-end proof)
OPENCODE_API_KEY=<key> headroom wrap opencode --port 8799 --no-serena --
\
run -m opencode-go/deepseek-v4.1-flash "reply with the single word ok"
  # exclusion check
HEADROOM_OPENCODE_EXCLUDE_HOSTS=opencode.ai OPENCODE_API_KEY=<key>
headroom wrap opencode ...
  ```
(`opencode-go` declares `OPENCODE_API_KEY` as its env credential in the
catalog, so no interactive login is needed.)
- Observed result: routed 401 with the fake key and 200 with the real
key through the proxy, `--standalone` added automatically, exclusion
honored — details:
- **Fake key** — proxy log: `proxy_inbound_request POST
/v1/chat/completions` with `user-agent: opencode/latest/2.0.19/cli` (and
`opencode/v2/0.0.0-v2-202610061051/cli` for the head), headers
`x-headroom-base-url: https://opencode.ai` and
`x-headroom-original-path: /zen/go/v1/chat/completions`; forwarded
upstream, `401` from the fake key — routed through Headroom.
- **Real key** — the model answered `ok`; proxy `status=200` with
upstream `https://opencode.ai/inference/go/openai/v1/chat/completions`.
- `wrap` added `--standalone` automatically on 2.0.19, and again on the
v2 head after the dev-build version fix (explicit `--standalone` also
works, per the kill-switch path).
- **Exclusion** — with `HEADROOM_OPENCODE_EXCLUDE_HOSTS=opencode.ai` the
model still answered while the proxy saw **zero** new chat requests: the
2.x model transform honors the exclusion list.
- Not tested: Windows; OpenAI "responses"-wire against a live 2.x
server; Anthropic-wire custom providers on 2.x; loading the plugin by
npm name (`headroom-opencode`), which needs a published release;
OpenCode 1.x older than 1.2.20.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: on OpenCode 2.x, `wrap opencode`
launches with `--standalone` (a private server per session); on 1.x
behaviour is unchanged apart from the plugin path now being a directory.
- Kill switch / disable path: pass `--server <url>` or `--standalone`
explicitly; `HEADROOM_OPENCODE_PLUGIN_PATH` still overrides the plugin
location.
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert this PR; the wheel bundle and plugin path revert
with it.

## 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 (a CI guard enforces
this)

## Additional Notes

@laurence-diack-pk — thank you for the original implementation; the
commit is preserved verbatim at the base of this branch. @JerrettDavis —
this addresses the routing-contract conflict you described in #3719 (the
missing `excludeHosts` argument and the model-base vs endpoint
mismatch), the Windows assertion, and a dev-build version-detection gap
found while validating on macOS. Live 2.x validation is done on both
2.0.19 and today's `v2` head; details above.

---------

Co-authored-by: laurence <laurence.diack@peekrobotics.co.nz>
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-07 20:52:53 -05:00
Ayush Kumar JhaandJD Davis 0024b57405 feat(opencode): exclude hosts from transport plugin routing (#3668)
## Description

The OpenCode transport plugin rewrites every non-loopback HTTP(S)
request to the Headroom proxy, both in the OpenCode process and in every
spawned Node child via the hook-shim. When a provider validates the
client on the wire and rejects the proxy hop (OpenCode Zen free tier,
some enterprise gateways), the only way to keep that provider working is
to unload the plugin, which drops Headroom for every other provider too.

This adds an exclude list to `shouldRoute()`. Hosts come from the
`excludeHosts` plugin option, or from `HEADROOM_OPENCODE_EXCLUDE_HOSTS`
(comma-separated) when the option is absent, with the same
option-over-env precedence `proxyUrl` already uses. An entry matches the
host and all of its subdomains (`example.com`, `.example.com` and
`*.example.com` are equivalent). Excluded requests go straight upstream
with their original URL, init and headers: no `x-headroom-base-url`, no
compression, no telemetry. The effective list is exported to
`process.env` and to spawned child env so the hook-shim copy of the
transport makes the same decision. Default is empty, so nothing changes
for existing installs.

Root cause: `shouldRoute()` (unchanged since #1105) only checked scheme,
loopback and the proxy origin; it had no configuration input at all, and
the child-process shim configures itself purely from env, so any opt-out
has to be env-readable and exported by `withShimEnv`/`installProcessEnv`
or children silently diverge from the parent (#3633 points this out).

Considered and not done here: path-level globs (both reported cases are
host-level; can be layered on later as a separate variable), proxy-side
passthrough (still a proxy hop, which is what the Zen gate rejects), and
a default exclusion for `registry.npmjs.org` (a separate decision; this
keeps zero behavior change by default). The Zen `/responses` bug itself
is #3656 / #3659.

Closes #3657
Refs #3633

Note: #3657 is a feature request and did not yet have a maintainer 👍
when I opened this, so I am keeping it small and happy to change the
surface: drop the plugin option and ship env-only, rename the variable
to #3633's `HEADROOM_OPENCODE_ROUTE_EXCLUDE`, or hold until the surface
is agreed.

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] 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`: `normalizeExcludeHosts` /
`isExcludedHost`; `shouldRoute` takes the list and returns `false` on a
match (fetch, `http`/`https.request`/`get`, and `http2.connect`, which
is now allowed for excluded hosts instead of blocked);
`installHeadroomTransport` resolves `options.excludeHosts ??
process.env.HEADROOM_OPENCODE_EXCLUDE_HOSTS`; `installProcessEnv` and
`withShimEnv` export the **effective** list through
`withExcludeHostsEnv` — set when non-empty, deleted when empty — so an
explicit `excludeHosts: []` clears a pre-existing variable for the
process and for every spawned child (review finding, second commit).
- `plugins/opencode/src/plugin.ts`: `excludeHosts?: string[]` on
`HeadroomOpenCodePluginOptions`, passed through.
- `plugins/opencode/src/transport.test.ts`: six tests — env var with
subdomain/case/`.`/`*.` forms and non-matching hosts still routed;
option precedence over env; Node `https.request` and `http2.connect` on
excluded hosts; child env propagation (and no variable set when nothing
is excluded); explicit empty override clears a pre-existing variable
in-process, in `process.env`, and in default/custom/stale-carrying child
env; the variable tracks each re-install's resolved list.
- `headroom/providers/opencode/_dist/entry.opencode.js`,
`headroom/providers/opencode/hook-shim/handler.js`: rebuilt with `npm
run build:standalone`.
- `plugins/opencode/README.md`, `docs/content/docs/opencode.mdx`:
document the option, the variable and the matching rule.

## Testing

- [ ] Unit tests pass (`pytest`) — not run in full locally;
`tests/test_providers_opencode_plugin_path.py` and
`tests/test_providers_opencode_config.py` give the same result as `main`
on my Windows checkout (44 passed, 1 pre-existing Windows-only
path-escaping failure in `test_build_launch_env_with_project`). No
Python source changed.
- [ ] Linting passes (`ruff check .`) — no Python changed.
- [ ] Type checking passes (`mypy headroom`) — no Python changed.
- [x] New tests added for new functionality
- [x] Manual testing performed

Plugin CI sequence from `.github/workflows/opencode-plugin.yml`, run
after rebasing onto `main` (`67eb910e`): typecheck, build, test,
standalone build, bundle parity, plus commitlint and `npm audit`.

### Test Output

```text
$ cd plugins/opencode && npm ci && npm run typecheck && npm run build && npm test
found 0 vulnerabilities
typecheck exit=0
 Test Files  2 passed (2)
      Tests  23 passed (23)

$ npm run build:standalone && cmp dist-standalone/entry.opencode.js ../../headroom/providers/opencode/_dist/entry.opencode.js && cmp dist-standalone/hook-shim/handler.js ../../headroom/providers/opencode/hook-shim/handler.js
entry.opencode.js: IDENTICAL
handler.js: IDENTICAL

# the four new tests against unpatched transport.ts (fix stashed, tests kept):
 ❯ src/transport.test.ts (19 tests | 4 failed)
     × keeps HEADROOM_OPENCODE_EXCLUDE_HOSTS hosts and their subdomains off the proxy (#3657)
     × prefers the excludeHosts option over HEADROOM_OPENCODE_EXCLUDE_HOSTS
     × leaves excluded hosts alone for Node https.request and http2.connect
     × propagates excluded hosts into child process env so the hook-shim matches
AssertionError: expected URL { href: 'http://127.0.0.1:8787/v1/responses', ... } to be 'https://opencode.ai/zen/v1/responses'

$ npx commitlint --config .commitlintrc.json --edit <msg>   # exit 0
$ npm audit --package-lock-only --audit-level=low            # found 0 vulnerabilities
```

## Real Behavior Proof

- Environment: Windows 11, Node v24.13.0, plugin built from this branch
(`npm run build` for the in-process check, the committed wheel
`hook-shim/handler.js` from this branch for the child-process check),
fake proxy on `127.0.0.1` recording `x-headroom-base-url`.
`HEADROOM_OPENCODE_EXCLUDE_HOSTS=opencode.ai`.
- Exact command / steps: (1) import `dist/index.js`, install the
transport with `excludeHosts: ["opencode.ai"]`,
`fetch("https://opencode.ai/zen/v1/responses")` then
`fetch("https://api.anthropic.com/v1/messages")`, record what the
original `fetch` received; (2) spawn `node
--import=<hook-shim/handler.js>` with
`HEADROOM_OPENCODE_TRANSPORT_PROXY_URL=<fake proxy>` and the variable
above, `fetch("https://opencode.ai/zen/v1/responses")` from the child,
watch the fake proxy; (3) same two scripts on unpatched `main` as the
control.
- Observed result: (1)
`{"url":"https://opencode.ai/zen/v1/responses","base":null}` then
`{"url":"http://127.0.0.1:8787/v1/messages","base":"https://api.anthropic.com"}`
— excluded host untouched, Anthropic still routed; (2) `child: fetch
resolved status 401 from https://opencode.ai/zen/v1/responses` / `fake
proxy saw: []` — the child went direct to the real host (401 is
opencode.ai answering an unauthenticated request) and the proxy never
saw it; (3) on `main` both scripts route `opencode.ai` to the proxy with
`base: https://opencode.ai`, and on this branch the same happens when
the variable is spelled wrong (`HEADROOM_OPENCODE_ROUTE_EXCLUDE`), i.e.
an unknown variable changes nothing.
- Empty-override check (review finding): parent env
`HEADROOM_OPENCODE_EXCLUDE_HOSTS=api.anthropic.com`, transport installed
with `excludeHosts: []`, a child spawned through the wrapped
`child_process.spawn` preloaded with the committed hook-shim, both fetch
`api.anthropic.com`: on the reviewed head the child inherited
`"api.anthropic.com"` and went direct; on this head `child env var:
undefined` and the fake proxy saw `x-headroom-base-url:
["https://api.anthropic.com","https://api.anthropic.com"]` — parent and
child agree.
- Not tested: a live OpenCode session against the real Zen free-tier
model (I don't have OpenCode Zen credentials); macOS/Linux; Bun-spawned
children (they inherit `process.env`, which `installProcessEnv` now
sets, same path as `NODE_OPTIONS`); the full Python suite (CI).

## Runtime Rollout Safety

- Rollout-managed feature(s): none.
- Minimum rollout channel: n/a.
- Stable/default behavior changed: no. With no `excludeHosts` option and
no `HEADROOM_OPENCODE_EXCLUDE_HOSTS`, `shouldRoute()` is unchanged and
the variable is never written. Only configured hosts bypass the proxy;
for them `http2.connect` is now allowed instead of throwing.
- Kill switch / disable path: unset the variable / remove the option;
excluded traffic goes back through the proxy on next launch.
- Unsafe override required: no.
- Qualification impact: none.
- Rollback path: revert this commit (source and the two committed
bundles change 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 (a CI guard enforces
this)

## Additional Notes

Start reading at `shouldRoute()` and `normalizeExcludeHosts()` in
`plugins/opencode/src/transport.ts`, then `installHeadroomTransport` for
the option/env resolution and the two env exports. The bundle diffs are
the same hunks compiled. The one decision I'd most like challenged is
shipping both a plugin option and an env var: the env var is required
regardless (it is the only surface that reaches `headroom wrap
opencode`, which registers the plugin as a bare path, and the hook-shim
in child processes), and the option mirrors the reporter's proposed API;
dropping the option is a six-line change if you'd rather keep one
surface.

Known limits: entries are bare hosts (no scheme, port or path), IDN
entries must be given in punycode, and like
`HEADROOM_OPENCODE_TRANSPORT_PROXY_URL` the exported variable is not
removed from `process.env` on dispose.

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-09-24 22:03:28 -05:00
Tejas Chopra c2fc4d3753 fix(ccr): make headroom_retrieve a hash-only full-content lookup (#1532)
The optional `query` parameter on headroom_retrieve routed retrieval
through CompressionStore.search(), which BM25-scored the items inside a
single cached blob and dropped everything below a 0.3 relevance floor.
On small per-blob corpora with conversational queries this returned an
empty result the large majority of the time, so the LLM saw "nothing
found" for content that was actually present — pushing users to turn
compression off entirely.

Retrieval is fundamentally a hash lookup (this already matches the Rust
proxy's CCR store, which is put/get only — "no BM25 search"). Remove the
query/search path end to end and always return the full original
content:

Core (Python proxy):
- tool schemas (anthropic/openai/google) drop the `query` property
- parse_tool_call returns the hash (str | None) instead of (hash, query)
- response handler, proxy POST/GET/tool-call handlers, the MCP retrieve
tool, and the streaming feedback recorders retrieve by hash only
- proactive context-tracker expansion always restores full content
- delete CompressionStore.search() and its BM25 machinery (the bm25
module stays — it is still used by relevance/)
- CCRToolCall.query, CCRToolResult.was_search, and
ExpansionRecommendation.expand_full/search_query are removed

Plugins (advertised a now-defunct query param to the LLM):
- hermes (Python), openclaw + opencode (TypeScript) retrieve tools drop
`query` from their schemas, signatures, request URLs, and tests

Benchmarks/docs:
- ccr_regression + adversarial benchmarks switch from store.search() to
full hash retrieval (search input-injection tests repurposed to the
hash, the only remaining input surface)
- wiki/ARCHITECTURE.md, wiki/ccr.md, docs/content/docs/ccr.mdx,
config.py and store docstrings updated to describe hash-only retrieval

Tests updated to assert full-content retrieval and guard the removed
surface; the full CCR/proxy/store/TOIN suite passes. ruff + mypy clean.

## Description

<!-- Briefly explain the change and why it is needed. -->

Closes #

## Type of Change

- [ ] 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

- 

## Testing

<!-- Check what you actually ran, then paste the real command output
below. -->

- [ ] Unit tests pass (`pytest`)
- [ ] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [ ] New tests added for new functionality
- [ ] Manual testing performed

### Test Output

```text
# Paste relevant command output or artifact links here
```

## Real Behavior Proof

- Environment:
- Exact command / steps:
- Observed result:
- Not tested:

## Review Readiness

- [ ] I have performed a self-review
- [ ] This PR is ready for human review

## Checklist

- [ ] My code follows the project's style guidelines
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] I have updated the CHANGELOG.md if applicable

## Screenshots (if applicable)

Add screenshots to help explain your changes.

## Additional Notes

<!-- Mention any N/A checklist items, tradeoffs, follow-ups, or
maintainer context. -->
2026-06-28 10:32:43 -07:00
Rudimar Ronsoni fa05ebc849 docs: clarify OpenCode integration (#1317)
## Description

Clarifies the OpenCode documentation follow-up for PR #1105 so users can
install `headroom-opencode`, configure provider routing, use the native
plugin, and copy working retrieve/compression helper examples.

## Type of Change

- [x] Documentation update
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change

## Changes Made

- Documented how `headroom wrap opencode` wires provider config, MCP
tools, and runtime environment.
- Documented the native `HeadroomPlugin` path, `HEADROOM_PROXY_URL`,
retrieve tooling, and programmatic config helpers.
- Fixed `plugins/opencode/README.md` examples so `compressWithHeadroom`
uses the exported options-object API and `headroom_retrieve` uses
`hash`.

## Testing

- [x] Type checks pass.
- [x] Unit tests pass.
- [x] Whitespace check passes.

### Test Output

```text
plugins/opencode: npm run typecheck
> tsc --noEmit

plugins/opencode: npm test
Test Files  2 passed (2)
Tests  9 passed (9)

docs: npm run types:check
✓ Types generated successfully

repo: git diff --check
(no output)
```

## Real Behavior Proof

- Environment: Local macOS worktree at
`docs/pr-1105-documentation-followup`, Node/npm project commands run
from `plugins/opencode` and `docs`.
- Exact command / steps: Updated the README snippets, ran `npm run
typecheck`, reran `npm test` with elevated permissions after the sandbox
blocked a local `127.0.0.1` listener, ran `npm run types:check` in
`docs`, and ran `git diff --check`.
- Observed result: Typecheck completed with `tsc --noEmit`; the OpenCode
package test suite reported 2 files and 9 tests passed; docs type
generation completed successfully; `git diff --check` produced no
output.
- Not tested: Browser-rendered documentation preview. `docs: npm run
build` was started locally but produced no output for roughly 90 seconds
and was stopped, so this follow-up does not claim a fresh local docs
build result.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Additional Notes

- The linked review comment asked for README examples to match
`compressWithHeadroom(messages, options)` and
`createHeadroomRetrieveTool` requiring `hash`; both snippets now match
the exported API.
2026-06-24 21:54:05 -05:00
Rudimar RonsoniandRudimar Ronsoni b4571cc346 feat: headroom wrap opencode / unwrap opencode CLI (#1105)
## Summary

This PR implements transparent `headroom wrap opencode` support without
asking users to edit OpenCode provider URLs, choose an extra CLI flag,
or maintain a static provider list.

The wrapper now lives at the runtime transport boundary: OpenCode keeps
its user/provider config, while Headroom intercepts outbound provider
traffic in-process and routes it through the local Headroom proxy.

## What changed

### Transparent OpenCode wrapping

- `headroom wrap opencode` injects the `headroom-opencode` plugin
through `OPENCODE_CONFIG_CONTENT`.
- Existing OpenCode provider URLs are preserved. We do not rewrite user
config URLs to point at Headroom.
- Existing `OPENAI_BASE_URL` and `ANTHROPIC_BASE_URL` env vars are
preserved.
- Local OpenCode traffic, localhost traffic, and Headroom proxy traffic
bypass the shim to avoid loops.

### Runtime transport interception

- Added an OpenCode plugin transport shim that wraps:
  - `globalThis.fetch`
  - `http.request` / `http.get`
  - `https.request` / `https.get`
- External provider calls are routed to the local Headroom proxy.
- The original upstream origin is passed through `x-headroom-base-url`,
so the proxy can forward to the real provider without changing OpenCode
config.
- External `http2.connect` is blocked loudly instead of allowing direct
provider traffic to leak outside Headroom.

### Live provider additions

Provider coverage is no longer based on a static config scan. Because
routing happens at outbound request time, providers added mid-session
are routed through Headroom automatically as long as they use the
covered Node transport paths.

### Subagent and child-process coverage

- The parent OpenCode plugin sets a packaged Node preload shim through
`NODE_OPTIONS=--import=.../hook-shim/handler.js`.
- The transport shim patches `child_process.spawn`, `exec`, `execFile`,
and `fork` so child Node processes receive the Headroom preload even
when OpenCode passes a custom `env`.
- The child-process shim fails closed if it loads without
`HEADROOM_OPENCODE_TRANSPORT_PROXY_URL`.
- This closes the subagent leak path where a child Node process could
otherwise start without Headroom transport interception.

## Why this goes beyond PR #1089

PR #1089 improves OpenCode provider registration, but it still focuses
on provider config shape. This PR moves the enforcement boundary to
runtime transport interception.

This PR goes further because:

- No provider URL rewriting is required.
- New providers added mid-session are covered automatically.
- Subagents and child Node processes inherit the Headroom transport
shim.
- Direct external HTTP/2 paths fail loudly instead of leaking.
- The wrap remains transparent to the user's OpenCode provider config.
- The wrapper is fail-closed for unsupported child-process preload
state.

## Additional robustness fixes

While validating the change in Docker, the full Python suite exposed
unrelated Linux/container robustness issues. These are fixed in this PR
so the suite is green:

- Binary cache handling now treats cache paths under a non-writable
existing parent as unavailable, including when tests run as root in
Docker.
- `release_version.py` honors `MANUAL_VER` before git calls so direct
script execution works outside a `.git` checkout.
- Test logger isolation now resets relevant Headroom child loggers so
proxy logging setup cannot poison later `caplog` tests.
- The scanner missing-path test now uses a guaranteed missing `tmp_path`
child instead of relying on `/nonexistent/path`.

## Validation

All implementation validation was run inside Docker.

- Full Python suite from a fresh Docker copy: `6605 passed, 523
skipped`.
- Ruff on changed Python/OpenCode paths: passed.
- OpenCode plugin typecheck: passed.
- OpenCode plugin tests: `9 passed`.
- OpenCode plugin build: passed.
- Hook shim preload smoke test: passed.

## Notes

This PR intentionally does not add a CLI option. `headroom wrap
opencode` means full wrap. Either Headroom wraps OpenCode transparently,
or the path fails loudly instead of silently leaking provider traffic.

---------

Co-authored-by: Rudimar Ronsoni <6081613+rudironsoni@users.noreply.github.com>
2026-06-22 11:07:12 -05:00