feat(wrap): add OpenCode support with headroom wrap opencode

[praffulomg]

Description

Adds headroom wrap opencode, extending Headroom's existing wrap family (claude, codex, copilot, aider, cursor, ...) to the OpenCode CLI so its LLM traffic is routed through Headroom's local compression proxy.

OpenCode does not honor the generic OPENAI_BASE_URL / ANTHROPIC_BASE_URL environment variables (it only uses env vars for API keys and ${VAR} substitution). Endpoint redirection must therefore be injected via OpenCode's own config mechanism. The wrapper sets the OPENCODE_CONFIG_CONTENT env var to an inline JSON config that points both the openai and anthropic providers' baseURL at the local proxy.

Both baseURLs are /v1-based (http://127.0.0.1:{port}/v1). This is deliberate and load-bearing: @ai-sdk/openai appends /chat/completions and @ai-sdk/anthropic appends only /messages to the configured base, so a /v1 base resolves to the proxy's existing /v1/chat/completions and /v1/messages routes. A base without /v1 would silently fall through the proxy's verbatim catch-all and forward uncompressed with no error.

Type of Change

• New feature (non-breaking change which adds functionality)
• Bug fix
• Breaking change
• Documentation
• Performance
• Refactor

Changes Made

• New package headroom/providers/opencode/
  • __init__.py — re-exports build_launch_env and proxy_base_url (mirrors providers/codex).
  • runtime.py — proxy_base_url(port) -> http://127.0.0.1:{port}/v1; build_launch_env(port, environ, project) emits OPENCODE_CONFIG_CONTENT JSON with both providers' baseURL set to the /v1 proxy base, an optional X-Headroom-Project header (via sanitize_project_name) for per-project savings attribution, and autoupdate: false to pin OpenCode under the wrapper.
• headroom/cli/wrap.py — added the _build_opencode_launch_env import and a new @wrap.command("opencode") (mirrors the additive Pattern A launch flow: resolve binary via shutil.which("opencode") → build env → _launch_tool(..., tool_label="OPENCODE", agent_type="opencode")); updated the wrap group docstring; removed an obsolete note stating the command did not exist.
• headroom/telemetry/context.py — added "opencode" to _KNOWN_WRAP_AGENTS (telemetry stack label only).
• README.md — added an OpenCode row to the agent compatibility matrix and the wrap synopsis.
• CHANGELOG.md — added an Unreleased > Features entry.
• tests/test_provider_opencode.py — new unit tests (5 assertions).

Additive only. No changes to the proxy, provider registry, or auth-mode classification — existing wraps are unaffected.

Testing

• Unit tests pass (pytest)
• Linting passes (ruff check)
• Type checking passes (mypy on the new package)
• New tests added
• Manual testing performed

Test Output

$ uv run --no-sync pytest tests/test_provider_opencode.py -q
5 passed in 0.08s

# Full provider + telemetry + test_providers/ regression (implementation pass):
231 passed, 0 failed, 0 skipped

$ uv run --no-sync ruff check headroom/cli/wrap.py headroom/telemetry/context.py headroom/providers/opencode/ tests/test_provider_opencode.py
All checks passed!

$ uv run --no-sync mypy headroom/providers/opencode/
Success: no issues found in 2 source files

$ uv run --no-sync python -c "import headroom.cli.wrap; print('wrap import OK')"
wrap import OK

Real Behavior Proof

• Environment: macOS (darwin), Python 3.11.15, pytest 9.0.3, repo chopratejas/headroom @ branch feat/wrap-opencode (commit 6b844ce). opencode binary NOT installed in this sandbox.
• Exact command / steps: uv run --no-sync ruff check headroom/cli/wrap.py headroom/telemetry/context.py headroom/providers/opencode/ tests/test_provider_opencode.py; uv run --no-sync mypy headroom/providers/opencode/; uv run --no-sync pytest tests/test_provider_opencode.py -q; uv run --no-sync python -c "from headroom.providers.opencode import build_launch_env, proxy_base_url; print(build_launch_env(8787, {}, 'Demo Proj'))"; and Click CliRunner invocations of wrap --help and wrap opencode --help.
• Observed result: both openai+anthropic provider baseURLs = http://127.0.0.1:8787/v1 (both end /v1); X-Headroom-Project header present when project set and absent when project=None; headroom wrap --help lists opencode with claude/codex/aider/copilot/cursor still intact; opencode subcommand --help exits 0; ruff "All checks passed!"; mypy "Success: no issues found in 2 source files"; pytest 5 passed (new) + 231 passed regression (0 failed/skipped).
• Not tested: live end-to-end run against a real installed opencode binary hitting a real upstream API (binary not available in sandbox); mypy was run only on the new headroom/providers/opencode package, not the full headroom tree.

Review Readiness

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

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code where necessary (the critical /v1 rationale is documented in runtime.py)
• I have made corresponding changes to the documentation (README + CHANGELOG)
• My changes generate no new warnings
• I have added tests that prove my fix is effective / feature works
• New and existing unit tests pass locally with my changes
• I have updated the CHANGELOG (Unreleased > Features)

Additional Notes

• The /v1 suffix on both provider baseURLs is intentional and the most important correctness detail — tests/test_provider_opencode.py explicitly asserts both end in /v1 to guard against a silent regression (a wrong path falls through the proxy catch-all uncompressed with no 404 in logs).
• Per-project savings attribution uses the X-Headroom-Project header (OpenCode supports custom per-provider headers via config), consistent with the proxy's existing header-based classify_project.
• Scope is intentionally minimal: no headroom install opencode, no Docker/scripts changes, and no auth-mode/UA classification (OpenCode is BYOK → PAYG, which is the correct aggressive-compression mode; classify_client already maps the opencode/ user agent). These are noted as possible follow-ups.
• mypy was run against the new headroom/providers/opencode/ package (clean), not the entire headroom tree.

[github-actions]

PR governance

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

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

[praffulomg]

Thanks @rudironsoni for the heads-up, and for the thorough work on #1105.

You're right that #1105 is the stronger direction. Intercepting at the runtime transport boundary cleanly handles what this PR's config-injection approach cannot — preserving user provider URLs, covering providers added mid-session, and propagating through subagents and child Node processes — and the Docker validation (6,605 passed) speaks for itself.

For context, #1173 took the lighter-weight route of injecting OPENCODE_CONFIG_CONTENT to point the openai/anthropic provider baseURLs at the local proxy. It's simpler, but only covers a static provider set and rewrites user config. Since #1105 supersedes it with a more complete, transparent wrap, I'm closing this in favor of #1105.

Thanks again for flagging the overlap.

[rudironsoni]

@praffulomg thank you for the work on this. It was genuinely useful while shaping #1105, especially for comparing where the OpenCode wrap should live and what edge cases we needed to cover.

I ended up taking a stricter route in #1105, with the wrapper sitting at the transport layer so provider changes during a session and subagents are covered too. Your PR helped make that direction clearer.

If you have time, I would really appreciate another set of eyes testing #1105. In particular, anything around OpenCode provider config, adding providers after startup, and subagent behavior would be valuable.