Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix(opencode): route Copilot Claude models through the proxy (#4594)

Chen Yufeiyang3d9a6f2cf7fe
diff --git a/headroom/providers/opencode/_dist/index.js b/headroom/providers/opencode/_dist/index.js
index cc45f1d65..c69c5f0ac 100644
--- a/headroom/providers/opencode/_dist/index.js
+++ b/headroom/providers/opencode/_dist/index.js
@@ -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` };
diff --git a/plugins/opencode/README.md b/plugins/opencode/README.md
index 207e89bdc..058e35465 100644
--- a/plugins/opencode/README.md
+++ b/plugins/opencode/README.md
@@ -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`:
diff --git a/plugins/opencode/RUNTIME_PROOF.md b/plugins/opencode/RUNTIME_PROOF.md
new file mode 100644
index 000000000..14e5bd72c
--- /dev/null
+++ b/plugins/opencode/RUNTIME_PROOF.md
@@ -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/[email protected]`.
+- `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/[email protected]
+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.
diff --git a/plugins/opencode/scripts/runtime-proof-result.json b/plugins/opencode/scripts/runtime-proof-result.json
new file mode 100644
index 000000000..84ba30ccb
--- /dev/null
+++ b/plugins/opencode/scripts/runtime-proof-result.json
@@ -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"
+ }
+ ]
+}
diff --git a/plugins/opencode/scripts/runtime-proof.py b/plugins/opencode/scripts/runtime-proof.py
new file mode 100644
index 000000000..dc419fe9c
--- /dev/null
+++ b/plugins/opencode/scripts/runtime-proof.py
@@ -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()
diff --git a/plugins/opencode/src/plugin.test.ts b/plugins/opencode/src/plugin.test.ts
index 58be2500d..e455cc960 100644
--- a/plugins/opencode/src/plugin.test.ts
+++ b/plugins/opencode/src/plugin.test.ts
@@ -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",
diff --git a/plugins/opencode/src/plugin.ts b/plugins/opencode/src/plugin.ts
index 8abda4f5d..ab668232c 100644
--- a/plugins/opencode/src/plugin.ts
+++ b/plugins/opencode/src/plugin.ts
@@ -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` };