mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-08-27 14:17:10 -04:00
b4571cc346
## 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>
120 lines
5.6 KiB
Text
120 lines
5.6 KiB
Text
---
|
|
title: OpenCode Integration
|
|
description: Route OpenCode traffic through Headroom for token compression, MCP tools, and cached model access. One command to wrap, one to unwrap.
|
|
---
|
|
|
|
Use `headroom wrap opencode` to route all OpenCode LLM traffic through the Headroom proxy with a single command. The proxy compresses context, injects MCP tools, and routes API calls to your configured backend.
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
headroom wrap opencode
|
|
```
|
|
|
|
This starts the Headroom proxy, injects a `headroom` provider into OpenCode's config, registers Headroom MCP tools, sets up RTK context filtering, and launches OpenCode through the proxy.
|
|
|
|
When you're done:
|
|
|
|
```bash
|
|
headroom unwrap opencode
|
|
```
|
|
|
|
## What `wrap opencode` does
|
|
|
|
| Step | What happens |
|
|
|---|---|
|
|
| Provider injection | Writes a `headroom` provider using `@ai-sdk/openai-compatible` into `opencode.json`, pointing at `http://127.0.0.1:<port>/v1` |
|
|
| Runtime env | Sets `OPENCODE_CONFIG_CONTENT` with provider + model + MCP config so OpenCode picks up the proxy provider at launch |
|
|
| Provider compatibility | Leaves `OPENAI_BASE_URL` and `ANTHROPIC_BASE_URL` untouched so OpenCode `/connect` providers keep their own routing |
|
|
| Context tool | Injects RTK (or `lean-ctx`) instructions into `~/.config/opencode/AGENTS.md` and project `AGENTS.md` |
|
|
| MCP setup | Registers the Headroom MCP server (`headroom_compress`, `headroom_retrieve`, `headroom_stats`) |
|
|
| Serena MCP | Optionally registers Serena code graph tools (`--no-serena` to skip) |
|
|
| Backup | Snapshots `opencode.json` to `opencode.json.headroom-backup` before making any changes |
|
|
| Launch | Starts the `opencode` binary through the proxy |
|
|
|
|
## Options
|
|
|
|
```bash
|
|
headroom wrap opencode \
|
|
--port 8787 \ # Proxy port (default: random available port)
|
|
--no-rtk \ # Skip RTK context tool injection
|
|
--no-mcp \ # Skip headroom MCP registration
|
|
--no-serena \ # Skip Serena code graph MCP
|
|
--code-graph \ # Include code graph in context
|
|
--no-proxy \ # Use existing proxy instead of starting one
|
|
--learn \ # Enable memory and live learning
|
|
--memory \ # Enable persistent memory
|
|
--backend anthropic \ # Set backend: anthropic, openai, anyllm
|
|
--anyllm-provider ... \ # AnyLLM provider selection
|
|
--region ... \ # Provider region
|
|
-- <opencode args> # Arguments passed to opencode binary
|
|
```
|
|
|
|
## Provider model mapping
|
|
|
|
The `headroom` provider exposes these models, all routed through the proxy:
|
|
|
|
| Provider model | Upstream model |
|
|
|---|---|
|
|
| `headroom/claude-sonnet-4-6` | Claude Sonnet 4.6 (200K context, 16K output) |
|
|
| `headroom/claude-opus-4-6` | Claude Opus 4.6 (200K context, 16K output) |
|
|
| `headroom/claude-haiku-4-5-20251001` | Claude Haiku 4.5 (200K context, 8K output) |
|
|
| `headroom/gpt-4o` | GPT-4o (128K context, 16K output) |
|
|
| `headroom/gpt-4.1` | GPT-4.1 (1M context, 32K output) |
|
|
|
|
The default model is `headroom/claude-sonnet-4-6`. Change it in `opencode.json` or via `OPENCODE_CONFIG_CONTENT`.
|
|
|
|
## Environment variables
|
|
|
|
| Variable | Description |
|
|
|---|---|
|
|
| `OPENCODE_CONFIG_CONTENT` | JSON payload with provider, model, and MCP config injected by wrap |
|
|
| `HEADROOM_PROXY_URL` | Optional metadata used by the `headroom-opencode` plugin |
|
|
| `HEADROOM_CONTEXT_TOOL` | Set to `lean-ctx` to use lean-ctx instead of RTK |
|
|
|
|
## Persistent installs
|
|
|
|
`headroom install` supports opencode as a target for persistent provider wiring:
|
|
|
|
```bash
|
|
headroom install apply --preset persistent-service --providers manual --target opencode
|
|
```
|
|
|
|
This writes the Headroom provider into `~/.config/opencode/opencode.json` and keeps the proxy running on port 8787.
|
|
|
|
Provider scope is also supported:
|
|
|
|
```bash
|
|
headroom install apply --preset persistent-service --scope provider --providers manual --target opencode
|
|
```
|
|
|
|
## How it works under the hood
|
|
|
|
1. **Config injection** — The wrap command writes a `provider.headroom` block into `opencode.json`. The provider uses the `@ai-sdk/openai-compatible` npm package, which OpenCode already supports natively. Model mappings route requests through `http://127.0.0.1:<port>/v1`.
|
|
|
|
2. **Runtime config** — `OPENCODE_CONFIG_CONTENT` is set as an env var containing the full provider + model + MCP JSON. OpenCode reads this at startup and merges it with the on-disk config.
|
|
|
|
3. **MCP tools** — Three Headroom MCP tools are registered: `headroom_compress` (compress context), `headroom_retrieve` (fetch original from CCR store), `headroom_stats` (compression statistics).
|
|
|
|
4. **Unwrap** — Restores `opencode.json` from the pre-wrap backup. If no backup exists, strips Headroom marker blocks from the config. Also unregisters Headroom MCP servers.
|
|
|
|
## Optional OpenCode plugin
|
|
|
|
The `headroom-opencode` npm package also exports an OpenCode plugin. The plugin
|
|
is additive: it exposes the `headroom_retrieve` tool and Headroom metadata such
|
|
as `HEADROOM_PROXY_URL`, but it does not route provider traffic by itself.
|
|
|
|
Provider traffic is still routed by the injected `headroom` provider in
|
|
`OPENCODE_CONFIG_CONTENT` or `opencode.json`. This keeps providers configured
|
|
through OpenCode `/connect` in charge of their own credentials and base URLs.
|
|
|
|
## Troubleshooting
|
|
|
|
**OpenCode doesn't use the headroom provider.**
|
|
Check that `OPENCODE_CONFIG_CONTENT` is set and contains the correct provider block. The wrap command prints the env vars it sets.
|
|
|
|
**Provider not found after unwrap.**
|
|
If unwrap left the provider configured, run `headroom unwrap opencode` again, or manually restore from `~/.config/opencode/opencode.json.headroom-backup`.
|
|
|
|
**Proxy port conflict.**
|
|
Use `--port` to select a specific port, or let the proxy auto-select an available one.
|