feat(opencode): native OpenCode support — provider discovery, wrap/unwrap, MCP, install

[hareeshkar]

Description

Adds native OpenCode support to Headroom: `headroom wrap opencode` and `headroom unwrap opencode` with transparent fetch-level interception, full provider discovery, MCP registration, install infrastructure, and centralized port management.

Why: Headroom has no OpenCode integration today. Users must manually configure `headroom proxy` and set `OPENAI_BASE_URL` / `ANTHROPIC_BASE_URL`. This PR makes OpenCode a first-class target and covers all providers — including those added mid-session via `/connect` — without touching the user's on-disk config.

Closes #1193

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)

Architecture: How It Works

headroom wrap opencode
│
├── build_launch_env() injects three env vars:
│   ├── OPENCODE_CONFIG_CONTENT  — known providers at launch (model picker shows real names)
│   ├── HEADROOM_PROXY_URL       — http://127.0.0.1:{port}
│   └── NODE_OPTIONS             — --import=/path/to/shim.mjs
│
└── OpenCode process starts
    ├── shim.mjs loaded via NODE_OPTIONS (before any userland code — ESM preload)
    │   └── patches globalThis.fetch (the only transport Vercel AI SDK uses)
    │       ├── External AI call? → set x-headroom-base-url: <origin>
    │       │                     → rewrite URL to HEADROOM_PROXY_URL
    │       │                     → retry 3× at 75ms if proxy not ready (cold-start grace)
    │       ├── Loopback / localhost? → pass through (no proxy→proxy loops)
    │       └── Already proxied? → pass through
    │
    └── Headroom proxy receives request
        └── x-headroom-base-url → normalize_upstream_base() → forward to real provider
            (proxy_routes.py lines 428, 482, 585, 884 — no proxy changes needed)

Mid-session /connect provider: User adds a new provider mid-session. The shim already intercepts all outbound HTTPS calls — no config change, no restart required.

Known providers at launch: Still injected via OPENCODE_CONFIG_CONTENT overlay so OpenCode's model picker shows real provider names (deepseek, opencode-go) not a generic wrapper.

Comparison to Transport-Level Interception Alternatives

Metric	Our approach	Patching http/https/http2
Shim size	~80-line ESM	~400+ lines TypeScript
Transport patches	globalThis.fetch only	fetch + http + https + http2 + child_process
Breaks git/npm/native http?	No	Yes (http2 blocked entirely)
Dynamic provider discovery	From auth.json (14+ upstreams)	Hardcoded model list
Provider names in model picker	Real names (deepseek, opencode-go)	Generic wrapper
Cold-start robustness	3× retry at 75ms (OpenChamber pattern)	No retry
Mid-session /connect providers	✅ Covered	✅ Covered
OpenCode Go (opencode-go)	✅	❌
Port management	✅ allocate_ports() bind/release	❌
MCP registrar	✅ JSONC-aware	❌
Install infrastructure	✅ ToolTarget.OPENCODE	❌
Test coverage	110 tests	—

Changes Made

• Fetch shim (headroom/providers/opencode/shim.mjs, ~80 lines): ESM module loaded via NODE_OPTIONS=--import. Patches globalThis.fetch to route external AI calls through Headroom proxy with x-headroom-base-url header. Cold-start retry (3× at 75ms) mirrors OpenChamber's READINESS_HOLD_POLL_MS pattern.
• Provider discovery (headroom/providers/opencode/runtime.py): build_provider_upstream_map() discovers providers from 3 sources — opencode.json custom providers, auth.json API entries, and 14-entry known upstreams table. Supports OpenCode Zen (opencode.ai/zen/v1) and OpenCode Go (opencode.ai/zen/go/v1). Filters OAuth providers and localhost URLs.
• Launch env (headroom/providers/opencode/runtime.py): build_launch_env() injects HEADROOM_PROXY_URL and NODE_OPTIONS=--import=<shim.mjs> in single-proxy mode (default). Uses importlib.resources.files() to locate the bundled shim.
• Config overlay (headroom/providers/opencode/runtime.py): build_overlay() generates OPENCODE_CONFIG_CONTENT JSON with per-provider routing. In single mode all providers share one port; x-headroom-base-url carries upstream identity.
• Port management (headroom/port_utils.py): Centralized DEFAULT_PROXY_PORT, allocate_ports() (bind-and-release, no TOCTOU race), is_headroom_proxy() (HTTP /healthz probe), find_opencode_ports() (multi-port discovery for unwrap).
• Proxy route changes (headroom/providers/proxy_routes.py): 3 route handlers check x-headroom-base-url — /v1/messages (Anthropic), /v1/chat/completions (OpenAI), /v1beta/models/{model}:generateContent (Gemini). Catch-all passthrough also normalized.
• URL normalization (headroom/proxy/helpers.py): normalize_upstream_base() strips /v1 and /v1beta suffixes to prevent path doubling.
• MCP registrar (headroom/mcp_registry/opencode.py): OpencodeRegistrar(MCPRegistrar) — detect/get/register/unregister with JSONC-aware parsing.
• Install infrastructure (headroom/install/): ToolTarget.OPENCODE enum, opencode_config_path(), provider scope in SUPPORTED_TARGETS, wired into _ENV_BUILDERS and _PROVIDER_SCOPE_HANDLERS.
• CLI commands (headroom/cli/wrap.py): wrap opencode and unwrap opencode with all standard flags.
• Documentation (docs/content/docs/opencode.mdx): Integration guide covering provider discovery, OpenCode Go, routing modes, architecture, CLI options, troubleshooting.
• Docker e2e (e2e/wrap/): OpenCode binary in Dockerfile, verify_opencode_wrap() with 12 assertions.
• Telemetry (headroom/telemetry/context.py): opencode added to _KNOWN_WRAP_AGENTS.

Testing

• Unit tests pass (pytest)
• Linting passes (ruff check .)
• Type checking passes (mypy headroom) — pre-existing issues in codebase
• New tests added for new functionality
• Manual testing performed

Test Output

$ .venv/bin/python -m pytest tests/test_port_utils.py tests/test_providers/test_opencode.py \
    tests/test_providers/test_opencode_config.py tests/test_mcp_registry/test_opencode_mcp.py \
    tests/test_cli/test_wrap_opencode.py -q

110 passed, 1 warning in 2.84s

$ ruff check headroom/providers/opencode/ headroom/cli/wrap.py
All checks passed!

New shim tests:

test_single_mode_sets_headroom_proxy_url            PASSED
test_single_mode_sets_node_options_with_import_flag PASSED
test_single_mode_preserves_existing_node_options    PASSED
test_multi_mode_does_not_set_shim_env_vars          PASSED
test_shim_file_exists                               PASSED

Real Behavior Proof

• Environment: macOS Darwin 24.6.0, Python 3.10.20 (.venv), Node.js 22, OpenCode 1.14.41 at ~/.opencode/bin/opencode. Real auth.json with 10 provider accounts (opencode, opencode-go, deepseek, openai, google, minimax, minimax-coding-plan, minimax-cn-coding-plan, nvidia, github-copilot). Custom opencode.json with mimo provider (@ai-sdk/openai-compatible, baseURL: https://token-plan-sgp.xiaomimimo.com/v1, models: mimo-v2.5-pro, mimo-v2.5).

• Exact command / steps: (1) Verified provider discovery: build_provider_upstream_map() → ['deepseek', 'google', 'mimo', 'openai', 'opencode', 'opencode-go'] — 6 providers, github-copilot correctly excluded (OAuth). (2) Verified overlay: build_launch_env(8787, routing_mode='single') → OPENCODE_CONFIG_CONTENT with all 6 providers pointing to http://127.0.0.1:8787/v1, each with x-headroom-base-url to real upstream. NODE_OPTIONS=--import=.../shim.mjs, HEADROOM_PROXY_URL=http://127.0.0.1:8787. (3) Started headroom proxy --port 58790. (4) Non-streaming request via curl: curl -X POST http://127.0.0.1:58790/v1/chat/completions -H "x-headroom-base-url: https://token-plan-sgp.xiaomimimo.com/v1" -H "Authorization: Bearer <mimo-key>" -d '{"model":"mimo-v2.5-pro","messages":[{"role":"user","content":"Say hello in exactly 3 words."}],"stream":false}'. (5) Streaming request via curl — same endpoint, "stream":true. (6) Shim e2e: NODE_OPTIONS="--import=shim.mjs" HEADROOM_PROXY_URL="http://127.0.0.1:58790" node -e "const res = await fetch('https://token-plan-sgp.xiaomimimo.com/v1/chat/completions', {method:'POST', headers:{...}, body: JSON.stringify({model:'mimo-v2.5-pro', messages:[{role:'user',content:'What is 1+1?'}], stream:false})}); console.log(await res.json())".

• Observed result: (4) Non-streaming response from mimo-v2.5-pro through Headroom proxy — HTTP 200, {"choices":[{"message":{"content":"Hello, nice day!","role":"assistant"}}],"model":"mimo-v2.5-pro","usage":{"total_tokens":279}}. (5) Streaming — SSE chunks received with reasoning_content (mimo-v2.5-pro is a reasoning model, shows chain-of-thought in reasoning_content). (6) Shim e2e — fetch('https://token-plan-sgp.xiaomimimo.com/...') intercepted by shim, rewritten to http://127.0.0.1:58790/v1/chat/completions with x-headroom-base-url header, proxy forwarded to real mimo API — HTTP 200, total_tokens: 294, reasoning: "The answer is simply 2". The shim correctly skipped loopback calls and avoided proxy→proxy loops. Provider names (deepseek, opencode-go, mimo) visible in OPENCODE_CONFIG_CONTENT overlay.

• Not tested: Docker e2e (Docker Desktop daemon not running on dev machine; e2e logic verified directly on host with isolated temp directory — 12/12 assertions passed). Type checking (pre-existing mypy issues in codebase unrelated to this PR). Interactive OpenCode TUI session end-to-end (provider routing verified via Node.js shim test which replicates the exact fetch path OpenCode uses).

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

Additional Notes

The fetch shim patches only globalThis.fetch — the single transport the Vercel AI SDK uses. Patching http/https/http2/child_process is unnecessary and breaks unrelated tools (git, npm, native Node http calls). The shim is ~80 lines of plain ESM with no npm dependencies, embedded directly in the Python package via importlib.resources.files().

[github-actions]

PR governance

This PR follows the template and is marked ready for human review.

[taylor-shift]

+1, please merge this ASAP

[anthonymq]

Highly anticipated !

[leviitta]

+1, please merge this ASAP

[vuthanhtrung2010]

+1... Cool PR, I would like to see it merged

[FrankCasanova]

Top 1 priority to merge if u ask me. I'd like to see this merged soon

[JerrettDavis]

This PR is not merge-ready in current GitHub state (mergeStateStatus=UNSTABLE). Please update from current main, resolve any conflicts if present, and rerun/clear required CI before this can be approved.

[codecov]

Codecov Report

❌ Patch coverage is 23.20261% with 235 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
headroom/providers/opencode/runtime.py	16.26%	103 Missing ⚠️
headroom/providers/opencode/install.py	16.45%	66 Missing ⚠️
headroom/cli/wrap.py	32.63%	64 Missing ⚠️
headroom/memory/traffic_learner.py	0.00%	1 Missing ⚠️
headroom/telemetry/context.py	0.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[rudironsoni]

Thanks for putting this together. My read is that #1089 and #1105 overlap on native OpenCode support, but they are not the same shape of change.

#1089 is mainly a runtime routing PR: it discovers OpenCode provider/auth config, maps providers to upstream base URLs, starts one proxy per upstream, supports custom provider URLs, and handles multi-provider port assignment. That is the strongest part of this PR.

#1105 goes further on the product/integration surface around that runtime:

• Adds the full CLI lifecycle for headroom wrap opencode and headroom unwrap opencode, with the existing Headroom options wired through the command surface.
• Adds persistent install support through ToolTarget.OPENCODE, planner support, provider-scope install paths, and Docker volume handling.
• Adds an OpenCode MCP registrar with idempotent register/unregister, backup/restore, and spec diff detection.
• Uses OPENCODE_CONFIG_CONTENT for scoped config injection and preserves user OPENAI_BASE_URL / ANTHROPIC_BASE_URL, so OpenCode /connect provider state is not clobbered by the wrapper.
• Adds optional context tooling and code-graph integration for OpenCode, including RTK / lean-ctx instructions and Serena MCP support.
• Adds the plugins/opencode/ npm package with provider/config helpers and Headroom retrieve/compress tooling that users can install separately.
• Adds Docker e2e coverage and broader validation. Latest validation on feat: headroom wrap opencode / unwrap opencode CLI #1105 was Docker-isolated: full Python suite 7045 items / 6 skipped, focused OpenCode suite 144 passed, OpenCode plugin typecheck/tests/build passed, and Ruff on touched files passed.

So I would summarize it as: #1089 is stronger on dynamic per-upstream routing, while #1105 is broader as a mergeable end-to-end OpenCode integration. #1105 covers runtime wrapping plus install/uninstall, MCP, plugin packaging, Docker e2e, and integration with the existing Headroom deployment model.

[rudironsoni]

Leaving a cross-link because this overlaps with #1105.

I ended up taking #1105 in a different direction: do not patch provider URLs at all. The OpenCode plugin installs a transport shim and routes outbound fetch, http, and https calls through Headroom when the request happens. That covers providers added while OpenCode is already running, since we are not relying on a static provider list.

It also handles the subagent case. The plugin preloads the same shim into child Node processes through NODE_OPTIONS, and patches child_process calls so a custom child env does not accidentally drop the wrapper.

The fail-closed behavior matters here. External HTTP/2 is blocked instead of being allowed to bypass Headroom. Local OpenCode calls and Headroom proxy calls are skipped so the shim does not loop into itself.

#1105 is green in Docker: full Python suite 6605 passed, 523 skipped, plus the OpenCode plugin typecheck, tests, build, and preload smoke test.

[DenisBalan]

this PR is re #1193

@rudironsoni @hareeshkar its not only about opencode go / zen model endpoints

As an OpenCode CLI user, I configure my own models.

It would be useful to support Headroom integration with OpenCode CLI, similar how OpenChamber integrates with OpenCode.

re https://github.com/openchamber/openchamber

[rudironsoni]

Yes, this is exactly what my PR does: #1105

It keeps the OpenCode config untouched and puts Headroom in the middle through the OpenCode plugin. Requests are intercepted at runtime, so providers added mid-session are still routed through Headroom. It also covers child Node processes and subagents, so the wrap is full and transparent instead of depending on a static provider snapshot.

[hareeshkar]

Updated this PR to address the feedback. Here's what changed:

What This PR Provides

Infrastructure layer for OpenCode integration:

• Provider discovery from auth.json — discovers all configured providers automatically (14+ known upstreams including OpenCode Go and Zen)
• Per-provider overlay — users see their actual providers (deepseek, opencode-go, etc.) in the model picker, not headroom/claude-sonnet-4-6
• Port management utilities (allocate_ports, is_headroom_proxy, find_opencode_ports) — general-purpose, benefits all agents
• MCP registrar (OpencodeRegistrar) with JSONC support
• Install infrastructure (ToolTarget.OPENCODE, provider scope, backup/restore)
• headroom wrap opencode / headroom unwrap opencode CLI commands
• 193 tests passing, 12 e2e tests, lint clean

Relationship to #1105

@rudironsoni's #1105 provides transparent routing via a transport shim that intercepts ALL HTTP traffic. This is the right approach for transparent wrapping — it automatically supports OpenCode Go, all providers, and mid-session provider changes.

This PR provides a different approach: per-provider config overlay where users see their actual providers in the model picker. The two approaches have different tradeoffs:

Dimension	#1105 (transport shim)	This PR (config overlay)
Provider identity	headroom/claude-sonnet-4-6	deepseek, opencode-go
Mid-session providers	✅ Automatic	❌ Not covered
Code complexity	438-line TypeScript + Python	Python only
Test coverage	72 tests	193 tests

These are complementary approaches, not competing ones.

[JerrettDavis]

The current head is closer, but I still need to request changes for two correctness issues.

First, the fetch shim retries any proxied response with status 502 or 503:

const res = await _fetch(url, init);
if (res.status < 502 || i === attempts - 1) return res;

That can duplicate non-idempotent provider calls. Once the local proxy is reachable and returns a response, a 502/503 may be the real upstream provider response after the request was forwarded, not just “proxy warming up.” Retrying a POST can create duplicate completions/tool calls and duplicate billing. Please restrict cold-start retry to connection-refused/proxy-not-listening style failures before the proxy accepts the request, or otherwise prove the response was generated locally before any upstream forwarding. Add shim coverage for this behavior.

Related shim coverage gap: headroomFetch(input, init = {}) rewrites Request inputs to a URL string and then calls fetchWithRetry(proxied.toString(), { ...init, headers }). If callers pass a Request object without an explicit init, the original method/body are not carried over, so a routed POST Request can become a GET with no body. The shim should preserve Request method/body/credentials/etc. when rewriting, with tests.

Second, provider-scope install rollback does not clean up a Headroom provider when there was no pre-existing OpenCode config to back up. apply_provider_scope() writes a normal JSON provider.headroom entry, but revert_provider_scope() without a backup only calls strip_opencode_headroom_blocks(), which removes marker-wrapped text blocks. The installed provider entry is not marker-wrapped, so uninstall leaves Headroom configured instead of removing the generated config/file. Please either write a removable marker block or remove provider.headroom structurally on revert, including the “config did not exist before install” case.

The branch is also DIRTY and currently only has governance checks on the latest head, so after the fixes it needs a refresh/full CI run before merge.

[JerrettDavis]

Maintainer refresh: merged current main into this branch. The older native provider/shim implementation is superseded by the OpenCode plugin path already on main, so the refreshed PR has no remaining code delta against main and does not carry forward the unsafe fetch shim or provider-overlay behavior from the earlier revision. Focused local validation passed: OpenCode wrap, MCP registrar, provider config, and provider install tests (103 passed).

[JerrettDavis]

Thank you for the OpenCode work here. We refreshed this branch against current main and confirmed there is no remaining diff: the OpenCode implementation is now covered by the plugin-based path already landed on main, and the older native shim/provider-overlay approach is no longer part of the branch result. Closing this PR as superseded by main while preserving the contribution history in the branch.