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>
This commit is contained in:
Chen Yufeiyang
2026-11-04 23:09:28 -06:00
committed by GitHub
co-authored by JD Davis
parent f9cae66b6b
commit 3d9a6f2cf7
7 changed files with 721 additions and 22 deletions
+14 -2
View File
@@ -20262,23 +20262,35 @@ function headroomShellEnv(proxyUrl, project, options) {
...options.backend ? { HEADROOM_BACKEND: options.backend } : {}
};
}
function openAiWireSuffix(pkg) {
function modelWireSuffix(pkg) {
if (!pkg?.startsWith("@opencode/ai/providers/")) return void 0;
if (pkg === "@opencode/ai/providers/openai-compatible" || pkg.endsWith("/chat")) {
return "/chat/completions";
}
if (pkg.endsWith("-responses") || pkg.endsWith("/responses")) return "/responses";
if (pkg === "@opencode/ai/providers/anthropic" || pkg === "@opencode/ai/providers/anthropic-compatible" || pkg.endsWith("/messages")) {
return "/messages";
}
return void 0;
}
function anthropicBaseKeepsPath(baseURL) {
try {
const pathname = trimTrailingSlashes(new URL(baseURL).pathname);
return pathname === "" || pathname === "/v1";
} catch {
return false;
}
}
function routeModelsThroughProxy(models, proxyUrl, project, excludeHosts, sessionToken) {
for (const model of models.list()) {
const providerID = String(model.providerID);
const modelID = String(model.id);
const provider = models.provider.get(providerID)?.provider;
const suffix = openAiWireSuffix(model.package ?? provider?.package);
const suffix = modelWireSuffix(model.package ?? provider?.package);
const baseURL = model.settings?.baseURL ?? provider?.settings?.baseURL;
if (!suffix || typeof baseURL !== "string") continue;
if (!modelBaseRoutesThroughProxy(baseURL, proxyUrl, excludeHosts)) continue;
if (suffix === "/messages" && !anthropicBaseKeepsPath(baseURL)) continue;
const upstream = new URL(baseURL);
models.update(providerID, modelID, (draft) => {
draft.settings = { ...draft.settings, baseURL: `${proxyUrl}/v1` };
+4 -1
View File
@@ -27,6 +27,9 @@ npm run build
npm run build:standalone
```
For a reproducible real OpenCode 2.x → proxy → local SSE upstream check, see
[the transport runtime proof](RUNTIME_PROOF.md). It records the tested scope and limitations.
## Provider Config Helpers
Use these helpers when you need to generate OpenCode config that routes a `headroom` provider through a running Headroom proxy.
@@ -73,7 +76,7 @@ The default export is `{ id: "headroom", server, setup }`. OpenCode 1.x calls `s
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. On 2.x the plugin also rewrites each remote model that uses the OpenAI chat-completions or responses format so that it points at the proxy. Headers name the real upstream, as the transport does. Models on other formats (Anthropic messages, Google) are left alone. `headroom wrap opencode` routes native Anthropic and OpenAI through the proxy separately, via their `baseURL`.
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`:
+120
View File
@@ -0,0 +1,120 @@
# OpenCode 2.x Anthropic Messages transport proof
This records the actual OpenCode runtime boundary requested in
[PR #4594's review](https://github.com/headroomlabs-ai/headroom/pull/4594#pullrequestreview-5745390972).
The OpenCode process, its Anthropic adapter, built plugin, and Headroom proxy are real.
Only the upstream API is a controlled local fixture. No live Copilot credentials are used.
## Environment
Recorded on **2026-11-04 at 04:23 UTC**, against Headroom source
`8766328a6c20909520b0a7ac7b5d487900316084`:
- Linux 6.18.57, x86_64; Python 3.12.14; Node 24.22.1; npm 11.9.0.
- Official OpenCode **2.2.5**, from `@opencode/cli-linux-x64-baseline@2.2.5`.
- `headroom-opencode` 0.42.0; Headroom 0.42.1-dev from this checkout.
- Built `dist-standalone/index.js`, byte-identical to the checked-in wheel bundle.
SHA-256: `de88ab2120df79ad67fad3f7a06f8618ea093707cfcf1180921b1ae42e7b1cea`.
- Real provider adapter: `@opencode/ai/providers/anthropic`, model `claude-sonnet-4-6`.
This is a configured Copilot-shaped provider, not OpenCode's live Copilot discovery flow.
- **Python-only degraded proxy mode**, explicitly observed in startup logs because
this environment has no `headroom._core`. `HEADROOM_REQUIRE_RUST_CORE=false`
permits that mode; `--no-optimize --no-cache` limits the experiment to transport.
## Exact commands / steps
From the repository root, prepare the source proxy and build the plugin:
```sh
uv sync --frozen --extra proxy --no-install-project
npm --prefix plugins/opencode ci
npm --prefix plugins/opencode test
npm --prefix plugins/opencode run typecheck
npm --prefix plugins/opencode run build
npm --prefix plugins/opencode run build:standalone
cmp plugins/opencode/dist-standalone/index.js headroom/providers/opencode/_dist/index.js
```
Use an official OpenCode 2.x executable. For the Linux x86_64 run above, the binary
was installed without executing a package install script:
```sh
npm install --prefix /tmp/opencode-runtime --omit=optional --ignore-scripts \
--no-save --no-audit --no-fund @opencode/cli-linux-x64-baseline@2.2.5
OPENCODE_BIN=/tmp/opencode-runtime/node_modules/@opencode/cli-linux-x64-baseline/bin/opencode
.venv/bin/python plugins/opencode/scripts/runtime-proof.py \
--opencode "$OPENCODE_BIN" --output /tmp/headroom-opencode-proof
```
The installation/output directories are selectable; `--output` must be new.
The script requires POSIX process groups and the `127.0.0.2` loopback alias.
It starts a new real proxy and a strict-path SSE fixture for each scenario, then runs:
```sh
opencode run --standalone --print-logs --log-level debug --format json \
'Reply with HEADROOM_RUNTIME_OK.'
```
Each run uses isolated HOME/XDG directories, a minimal environment, disabled model
metadata fetching, and synthetic bearer/API-key values. This isolates default
credential discovery, not filesystem access. The upstream binds only to `127.0.0.2`,
which exercises model rewriting without the plugin's `localhost`/`127.0.0.1`
exclusion. That address is explicitly allowlisted in the test proxy. Ports are
allocated dynamically. OpenCode loads the built standalone **directory**, whose
`index.js` is its plugin entrypoint. The script does not call `headroomSetup` itself,
replace the OpenCode context, or send the model request with a manual `fetch`.
## Observed result
All four scenarios exited successfully:
| Scenario | Plugin | Proxy POSTs | Upstream POSTs | 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` |
OpenCode made a title request and a user-turn request in each case. Every upstream
request retained the synthetic `Authorization` and `x-api-key`, the expected model,
`stream: true`, and `anthropic-version: 2023-06-01`. None contained `x-headroom-*`.
Each user turn received `HEADROOM_RUNTIME_OK` as an OpenCode text event, followed by
`step_finish`. The fixture flushes individual SSE events rather than returning a
JSON completion.
The proxied root-URL run logged these events (irrelevant fields omitted):
```text
04:23:10.316Z msg="loading plugin" entrypoint=file:///<checkout>/plugins/opencode/dist-standalone/index.js
04:23:10.975 event=proxy_inbound_request method=POST path=/v1/messages
user-agent=opencode/latest/2.2.5/cli
x-headroom-base-url=http://127.0.0.2:41341
x-headroom-original-path=/messages x-headroom-project=copilot-shaped
04:23:10.979 event=outbound_headers forwarder=anthropic_messages stripped_count=3
04:23:10.998 event=outbound_request forwarder=streaming method=POST
path=http://127.0.0.2:41341/v1/messages body_mutated=false source=passthrough
```
The script verifies proxy and upstream counts, exact upstream paths, preserved
synthetic auth, stripped internal headers, plugin loading, and a completed streamed
client reply. A fixture request to an unexpected endpoint receives 404. The root
URL case deliberately records the existing proxy contract of forwarding to
`/v1/messages`; it does not establish which endpoints a live Copilot account accepts.
The prefix exclusion is exercised by the real Anthropic adapter with the full
prefix intact and no model POST reaching Headroom.
Machine-readable results are in [runtime-proof-result.json](scripts/runtime-proof-result.json).
A rerun saves generated config, proxy/OpenCode logs, upstream observations and its
summary under the selected output directory. Plugin tests also passed **64/64**,
as did typecheck, both builds, bundle comparison, and Ruff checks for this script.
## Not tested
- Live `api.githubcopilot.com`, account discovery, subscription authentication,
token refresh, Copilot-specific headers, or actual model inference.
- A live z.ai gateway or its provider-specific adapter. The prefix control uses
the same real Anthropic adapter against a local path fixture.
- Rust-core behavior, compression/optimization, cache behavior, or production rollout.
- HTTPS/TLS, HTTP/2, rate limits, retries, or streaming latency/backpressure.
- OpenCode versions other than 2.2.5. The script rejects non-2.x versions and records
the actual Rust-core startup mode, which may differ on another machine.
@@ -0,0 +1,57 @@
{
"opencode": "opencode v2.2.5",
"python": "3.12.14",
"started_utc": "2026-11-04T04:23:01.378019+00:00",
"headroom_source": "8766328a6c20909520b0a7ac7b5d487900316084",
"plugin_sha256": "de88ab2120df79ad67fad3f7a06f8618ea093707cfcf1180921b1ae42e7b1cea",
"results": [
{
"case": "baseline",
"rust_core": "disabled",
"plugin": false,
"base_path": "",
"proxy_requests": 0,
"upstream_requests": 2,
"upstream_path": "/messages",
"auth_preserved": true,
"internal_headers_at_upstream": false,
"client_text": "HEADROOM_RUNTIME_OK"
},
{
"case": "copilot-shaped",
"rust_core": "disabled",
"plugin": true,
"base_path": "",
"proxy_requests": 2,
"upstream_requests": 2,
"upstream_path": "/v1/messages",
"auth_preserved": true,
"internal_headers_at_upstream": false,
"client_text": "HEADROOM_RUNTIME_OK"
},
{
"case": "v1-gateway",
"rust_core": "disabled",
"plugin": true,
"base_path": "/v1",
"proxy_requests": 2,
"upstream_requests": 2,
"upstream_path": "/v1/messages",
"auth_preserved": true,
"internal_headers_at_upstream": false,
"client_text": "HEADROOM_RUNTIME_OK"
},
{
"case": "prefixed-gateway",
"rust_core": "disabled",
"plugin": true,
"base_path": "/api/coding/paas/v4",
"proxy_requests": 0,
"upstream_requests": 2,
"upstream_path": "/api/coding/paas/v4/messages",
"auth_preserved": true,
"internal_headers_at_upstream": false,
"client_text": "HEADROOM_RUNTIME_OK"
}
]
}
+441
View File
@@ -0,0 +1,441 @@
#!/usr/bin/env python3
"""Exercise the built plugin with real OpenCode 2.x and Headroom processes.
Only the upstream is a fixture. No provider account or real API key is used.
Run with the repository's proxy dependencies installed in this Python environment.
"""
from __future__ import annotations
import argparse
import hashlib
import json
import os
import re
import shutil
import signal
import socket
import subprocess
import sys
import tempfile
import threading
import time
from datetime import datetime, timezone
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from pathlib import Path
from urllib.request import ProxyHandler, build_opener
REPO = Path(__file__).resolve().parents[3]
PLUGIN = REPO / "plugins/opencode/dist-standalone"
TEXT = "HEADROOM_RUNTIME_OK"
MODEL = "claude-sonnet-4-6"
AUTH = "Bearer proof-token-not-a-secret"
KEY = "test-key-not-a-secret"
def require(condition, message: str):
if not condition:
raise RuntimeError(message)
def stop_process_group(process):
# Both children are started in dedicated sessions; never target the caller's group.
try:
os.killpg(process.pid, signal.SIGTERM)
except ProcessLookupError:
pass
try:
process.wait(timeout=10)
except subprocess.TimeoutExpired:
pass
finally:
try:
os.killpg(process.pid, signal.SIGKILL)
except ProcessLookupError:
pass
process.wait(timeout=10)
def events(model: str):
yield (
"message_start",
{
"type": "message_start",
"message": {
"id": "msg_proof",
"type": "message",
"role": "assistant",
"model": model,
"content": [],
"stop_reason": None,
"stop_sequence": None,
"usage": {"input_tokens": 12, "output_tokens": 0},
},
},
)
yield (
"content_block_start",
{
"type": "content_block_start",
"index": 0,
"content_block": {"type": "text", "text": ""},
},
)
yield (
"content_block_delta",
{
"type": "content_block_delta",
"index": 0,
"delta": {"type": "text_delta", "text": TEXT},
},
)
yield "content_block_stop", {"type": "content_block_stop", "index": 0}
yield (
"message_delta",
{
"type": "message_delta",
"delta": {"stop_reason": "end_turn", "stop_sequence": None},
"usage": {"output_tokens": 4},
},
)
yield "message_stop", {"type": "message_stop"}
def run_case(opencode: str, output: Path, name: str, base_path: str, enabled: bool):
case = output / name
case.mkdir()
records: list[dict] = []
expected_path = (
"/v1/messages" if enabled and base_path in ("", "/v1") else base_path + "/messages"
)
expected_proxy = enabled and base_path in ("", "/v1")
class Upstream(BaseHTTPRequestHandler):
def log_message(self, *_):
pass
def do_POST(self):
body = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
headers = {key.lower(): value for key, value in self.headers.items()}
records.append(
{
"path": self.path,
"headers": headers,
"model": body.get("model"),
"stream": body.get("stream"),
}
)
# Do not let an unexpected endpoint pass just because this is a fixture.
if self.path != expected_path:
self.send_error(404, "Unexpected Messages path")
return
self.send_response(200)
self.send_header("Content-Type", "text/event-stream")
self.send_header("Connection", "close")
self.end_headers()
for event, data in events(body["model"]):
self.wfile.write(f"event: {event}\ndata: {json.dumps(data)}\n\n".encode())
self.wfile.flush()
time.sleep(0.01)
# 127.0.0.2 is local but differs from the plugin's deliberately excluded
# localhost/127.0.0.1 destinations, exercising remote-model routing safely.
upstream = ThreadingHTTPServer(("127.0.0.2", 0), Upstream)
upstream.daemon_threads = True
upstream_thread = threading.Thread(target=upstream.serve_forever, daemon=True)
upstream_thread.start()
with socket.socket() as sock:
sock.bind(("127.0.0.1", 0))
proxy_port = sock.getsockname()[1]
proxy_url = f"http://127.0.0.1:{proxy_port}"
upstream_url = f"http://127.0.0.2:{upstream.server_port}"
# Use isolated HOME/XDG directories and a minimal environment instead of
# inheriting provider credentials/config. This is not a filesystem sandbox.
env = {
"PATH": os.environ.get("PATH", ""),
"HOME": str(case / "proxy-home"),
"TMPDIR": str(case / "tmp"),
"TZ": "UTC",
"NO_PROXY": "*",
"no_proxy": "*",
"PYTHONPATH": str(REPO),
"HEADROOM_BEACON": "off",
"HEADROOM_TELEMETRY": "off",
"HEADROOM_UPDATE_CHECK": "off",
"HEADROOM_REQUIRE_RUST_CORE": "false",
"HEADROOM_ALLOWED_BASE_URLS": "127.0.0.2",
"LITELLM_LOCAL_MODEL_COST_MAP": "true",
}
for directory in (
"proxy-home",
"tmp",
"work",
"oc-home",
"oc-data",
"oc-config",
"oc-cache",
"oc-state",
):
(case / directory).mkdir()
cli_env = {
"PATH": env["PATH"],
"HOME": str(case / "oc-home"),
"TMPDIR": env["TMPDIR"],
"TZ": "UTC",
"NO_PROXY": "*",
"OPENCODE_DISABLE_MODELS_FETCH": "1",
}
for variable, directory in (
("DATA", "oc-data"),
("CONFIG", "oc-config"),
("CACHE", "oc-cache"),
("STATE", "oc-state"),
):
cli_env[f"XDG_{variable}_HOME"] = str(case / directory)
config = {
"update": "disable",
"share": "disabled",
"snapshots": False,
"model": f"proof-copilot/{MODEL}",
"providers": {
"proof-copilot": {
"name": "Controlled Copilot-shaped stand-in",
"package": "@opencode/ai/providers/anthropic",
"settings": {"baseURL": upstream_url + base_path, "apiKey": KEY},
"headers": {"Authorization": AUTH},
"models": {
MODEL: {
"name": "Claude proof",
"limit": {"context": 200000, "output": 512},
"capabilities": {"tools": False, "input": ["text"], "output": ["text"]},
}
},
}
},
# OpenCode 2.x local package entries point at a directory, not a file.
"plugins": [
{
"package": str(PLUGIN),
"options": {
"proxyUrl": proxy_url,
"project": name,
"debug": True,
},
}
]
if enabled
else [],
}
(case / "work/opencode.json").write_text(json.dumps(config, indent=2) + "\n")
proxy = None
try:
with (case / "proxy.log").open("w") as proxy_log:
proxy = subprocess.Popen(
[
sys.executable,
"-m",
"headroom.cli",
"proxy",
"--host",
"127.0.0.1",
"--port",
str(proxy_port),
"--no-optimize",
"--no-cache",
],
cwd=REPO,
env=env,
stdout=proxy_log,
stderr=subprocess.STDOUT,
start_new_session=True,
)
opener = build_opener(ProxyHandler({}))
for _ in range(60):
if proxy.poll() is not None:
raise RuntimeError(f"Proxy exited; see {case / 'proxy.log'}")
try:
with opener.open(proxy_url + "/livez", timeout=1) as response:
if response.status == 200:
break
except OSError:
pass
time.sleep(1)
else:
raise RuntimeError("Proxy did not become live")
with (case / "opencode.log").open("w") as cli_log:
cli = subprocess.Popen(
[
opencode,
"run",
"--standalone",
"--print-logs",
"--log-level",
"debug",
"--format",
"json",
f"Reply with {TEXT}.",
],
cwd=case / "work",
env=cli_env,
stdout=cli_log,
stderr=subprocess.STDOUT,
start_new_session=True,
)
try:
returncode = cli.wait(timeout=90)
finally:
stop_process_group(cli)
if returncode:
raise RuntimeError(f"OpenCode exited {returncode}; see {case / 'opencode.log'}")
finally:
if proxy is not None:
stop_process_group(proxy)
upstream.shutdown()
upstream.server_close()
upstream_thread.join()
(case / "upstream.json").write_text(json.dumps(records, indent=2) + "\n")
cli_log = (case / "opencode.log").read_text()
proxy_log = (case / "proxy.log").read_text()
client_events = [
json.loads(line) for line in cli_log.splitlines() if line.startswith('{"type":')
]
text = "".join(event["part"]["text"] for event in client_events if event.get("type") == "text")
require(text == TEXT, f"SSE text did not reach the client: {text!r}")
require(
any(event.get("type") == "step_finish" for event in client_events),
"No completed client turn",
)
require(records, "No upstream request observed")
require(
all(record["path"] == expected_path for record in records),
"Failed check: all((record['path'] == expected_path for record in records))",
)
for record in records:
headers = record["headers"]
require(headers.get("authorization") == AUTH, "Bearer auth changed")
require(headers.get("x-api-key") == KEY, "API key changed")
require(
headers.get("anthropic-version") == "2023-06-01",
"Failed check: headers.get('anthropic-version') == '2023-06-01'",
)
require(
"opencode/" in headers.get("user-agent", ""),
"Failed check: 'opencode/' in headers.get('user-agent', '')",
)
require(
not any(key.startswith("x-headroom-") for key in headers), "Internal headers leaked"
)
require(
record["model"] == MODEL and record["stream"] is True,
"Failed check: record['model'] == MODEL and record['stream'] is True",
)
inbound = [
line
for line in proxy_log.splitlines()
if "event=proxy_inbound_request" in line and "method=POST" in line
]
require(bool(inbound) == expected_proxy, "Unexpected proxy routing")
if expected_proxy:
require(len(inbound) == len(records), "Proxy/upstream request counts differ")
require(
all(
"path=/v1/messages" in line and '"x-headroom-base-url"' in line for line in inbound
),
"Failed check: all(('path=/v1/messages' in line and '\"x-headroom-base-url\"' in line for line in inbound))",
)
require(
f"path={upstream_url}/v1/messages" in proxy_log,
"Failed check: f'path={upstream_url}/v1/messages' in proxy_log",
)
require("stripped_count=3" in proxy_log, "Failed check: 'stripped_count=3' in proxy_log")
if enabled:
require(
'msg="loading plugin"' in cli_log and str(PLUGIN) in cli_log,
"Built plugin was not loaded",
)
core_mode = "disabled" if "event=rust_core_disabled" in proxy_log else "loaded"
require("event=rust_core_" + core_mode in proxy_log, "Rust core mode was not observed")
summary = {
"case": name,
"rust_core": core_mode,
"plugin": enabled,
"base_path": base_path,
"proxy_requests": len(inbound),
"upstream_requests": len(records),
"upstream_path": expected_path,
"auth_preserved": True,
"internal_headers_at_upstream": False,
"client_text": text,
}
print(json.dumps(summary), flush=True)
return summary
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument(
"--opencode", default=shutil.which("opencode"), help="OpenCode 2.x executable"
)
parser.add_argument(
"--output", type=Path, help="New directory for logs (default: temporary directory)"
)
args = parser.parse_args()
require(
os.name == "posix", "This local proof requires POSIX process groups and loopback aliases"
)
if not args.opencode or not (PLUGIN / "index.js").is_file():
parser.error("Install OpenCode 2.x and run npm run build:standalone first")
opencode = str(Path(args.opencode).resolve())
output = (
args.output.resolve()
if args.output
else Path(tempfile.mkdtemp(prefix="headroom-opencode-"))
)
if args.output:
output.mkdir(parents=True, exist_ok=False)
version_env = {
"PATH": os.environ.get("PATH", ""),
"HOME": str(output),
"XDG_DATA_HOME": str(output / "version-data"),
"XDG_CONFIG_HOME": str(output / "version-config"),
"XDG_CACHE_HOME": str(output / "version-cache"),
"XDG_STATE_HOME": str(output / "version-state"),
}
version = subprocess.check_output(
[opencode, "--version"], env=version_env, text=True, timeout=15
).strip()
require(re.search(r"(?:^|\s)v?2\.", version), "This proof requires OpenCode 2.x")
require(
(PLUGIN / "index.js").read_bytes()
== (REPO / "headroom/providers/opencode/_dist/index.js").read_bytes(),
"Rebuilt plugin differs from the checked-in wheel bundle",
)
metadata = {
"opencode": version,
"python": sys.version.split()[0],
"started_utc": datetime.now(timezone.utc).isoformat(),
"headroom_source": subprocess.check_output(
["git", "rev-parse", "HEAD"], cwd=REPO, text=True
).strip(),
"plugin_sha256": hashlib.sha256((PLUGIN / "index.js").read_bytes()).hexdigest(),
}
print(f"OpenCode: {version}\nEvidence: {output}", flush=True)
results = [
run_case(opencode, output, *case)
for case in (
("baseline", "", False),
("copilot-shaped", "", True),
("v1-gateway", "/v1", True),
("prefixed-gateway", "/api/coding/paas/v4", True),
)
]
(output / "summary.json").write_text(
json.dumps({**metadata, "results": results}, indent=2) + "\n"
)
print("PASS: all four real OpenCode / proxy transport scenarios", flush=True)
if __name__ == "__main__":
main()
+55 -13
View File
@@ -242,6 +242,60 @@ describe("headroomSetup (OpenCode 2.x)", () => {
});
});
it.each([
["@opencode/ai/providers/anthropic", "https://api.githubcopilot.com", "/messages"],
["@opencode/ai/providers/anthropic-compatible", "https://gateway.example/v1", "/v1/messages"],
])("routes Anthropic Messages models through the proxy (%s)", async (packageName, baseURL, originalPath) => {
// GitHub Copilot serves Claude models as @opencode/ai/providers/anthropic
// with a prefix-free Copilot baseURL; the OpenAI-only wire check used to
// skip them.
const models: FakeModel[] = [{ id: "claude-sonnet-5.5", providerID: "github-copilot" }];
const { context } = pluginContextV2(
{ proxyUrl: "http://127.0.0.1:8787" },
{
providers: [{ id: "github-copilot", package: packageName, settings: { baseURL } }],
models,
},
);
const cleanup = await headroomSetup(context);
await cleanup?.();
expect(models[0]).toMatchObject({
settings: { baseURL: "http://127.0.0.1:8787/v1" },
headers: {
"x-headroom-base-url": new URL(baseURL).origin,
"x-headroom-original-path": originalPath,
"x-headroom-project": "project-1",
},
});
});
it("leaves a prefixed Anthropic Messages gateway on its own base URL", async () => {
// The proxy's Anthropic route rebuilds the upstream path from its incoming
// /v1/messages and ignores x-headroom-original-path, so rewriting a
// prefixed gateway would drop that prefix. Keep those models direct.
const models: FakeModel[] = [{ id: "glm-5.2", providerID: "zai-coding-plan" }];
const { context } = pluginContextV2(
{ proxyUrl: "http://127.0.0.1:8787" },
{
providers: [
{
id: "zai-coding-plan",
package: "@opencode/ai/providers/zai-coding-plan/messages",
settings: { baseURL: "https://api.z.ai/api/coding/paas/v4" },
},
],
models,
},
);
const cleanup = await headroomSetup(context);
await cleanup?.();
expect(models[0]).toEqual({ id: "glm-5.2", providerID: "zai-coding-plan" });
});
it("prefers a model's own baseURL over its provider's", async () => {
const models: FakeModel[] = [
{
@@ -404,12 +458,10 @@ describe("headroomSetup (OpenCode 2.x)", () => {
});
});
it("leaves local, already-proxied, non-OpenAI-wire and URL-less models alone", async () => {
it("leaves local, already-proxied, URL-less and unsupported-protocol models alone", async () => {
const models: FakeModel[] = [
{ id: "llama", providerID: "ollama" },
{ id: "gpt-4o", providerID: "openai" },
{ id: "claude", providerID: "anthropic-gateway" },
{ id: "glm", providerID: "zai-coding-plan", package: "@opencode/ai/providers/zai-coding-plan/messages" },
{ id: "sonnet", providerID: "anthropic" },
{ id: "gemini", providerID: "google" },
];
@@ -428,16 +480,6 @@ describe("headroomSetup (OpenCode 2.x)", () => {
package: "@opencode/ai/providers/openai/responses",
settings: { baseURL: "http://127.0.0.1:8787/v1" },
},
{
id: "anthropic-gateway",
package: "@opencode/ai/providers/anthropic",
settings: { baseURL: "https://gateway.example/v1" },
},
{
id: "zai-coding-plan",
package: "@opencode/ai/providers/zai-coding-plan/chat",
settings: { baseURL: "https://api.z.ai/api/coding/paas/v4" },
},
{ id: "anthropic", package: "@opencode/ai/providers/anthropic" },
{
id: "google",
+30 -6
View File
@@ -70,22 +70,45 @@ function headroomShellEnv(
};
}
// The endpoint an OpenCode 2.x package calls under its baseURL, for packages
// on the OpenAI chat-completions or responses wire format; undefined otherwise.
// `.../messages` (Anthropic wire) and other protocols are left alone.
function openAiWireSuffix(pkg: string | undefined): string | undefined {
// The endpoint an OpenCode 2.x package calls under its baseURL, for packages on
// a wire format the proxy can route; undefined otherwise. GitHub Copilot's
// Claude models use the Anthropic Messages wire (`/messages`), so they must be
// rewritten like the OpenAI wires: skipping them let those requests bypass the
// proxy entirely (#4248).
function modelWireSuffix(pkg: string | undefined): string | undefined {
if (!pkg?.startsWith("@opencode/ai/providers/")) return undefined;
if (pkg === "@opencode/ai/providers/openai-compatible" || pkg.endsWith("/chat")) {
return "/chat/completions";
}
if (pkg.endsWith("-responses") || pkg.endsWith("/responses")) return "/responses";
if (
pkg === "@opencode/ai/providers/anthropic"
|| pkg === "@opencode/ai/providers/anthropic-compatible"
|| pkg.endsWith("/messages")
) {
return "/messages";
}
return undefined;
}
// The proxy's Anthropic route rebuilds the upstream path from its incoming
// `/v1/messages` and ignores `x-headroom-original-path`, so a rewritten model
// reaches the right endpoint only when its base URL has no path prefix beyond
// `/v1`. A prefixed gateway (for example `https://api.z.ai/api/coding/paas/v4`)
// would lose that prefix, so those models stay on their own base URL.
function anthropicBaseKeepsPath(baseURL: string): boolean {
try {
const pathname = trimTrailingSlashes(new URL(baseURL).pathname);
return pathname === "" || pathname === "/v1";
} catch {
return false;
}
}
// OpenCode 2.x sends model traffic through Effect's FetchHttpClient, which
// captures `globalThis.fetch` on the process's first HTTP request, before any
// plugin runs, so the transport's fetch patch never sees it. Point each
// remote OpenAI-wire model at the proxy instead, with the same routing headers
// remote model on a routable wire format at the proxy instead, with the same
// the transport sends: the upstream origin, and the real path the proxy
// appends to it.
type ModelEditor = Parameters<Parameters<PluginV2.Context["model"]["transform"]>[0]>[0];
@@ -102,10 +125,11 @@ function routeModelsThroughProxy(
const providerID = String(model.providerID);
const modelID = String(model.id);
const provider = models.provider.get(providerID)?.provider;
const suffix = openAiWireSuffix(model.package ?? provider?.package);
const suffix = modelWireSuffix(model.package ?? provider?.package);
const baseURL = model.settings?.baseURL ?? provider?.settings?.baseURL;
if (!suffix || typeof baseURL !== "string") continue;
if (!modelBaseRoutesThroughProxy(baseURL, proxyUrl, excludeHosts)) continue;
if (suffix === "/messages" && !anthropicBaseKeepsPath(baseURL)) continue;
const upstream = new URL(baseURL);
models.update(providerID, modelID, (draft) => {
draft.settings = { ...draft.settings, baseURL: `${proxyUrl}/v1` };