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.

feat: headroom wrap opencode / unwrap opencode CLI (#1105)

Rudimar Ronsonib4571cc346f6
diff --git a/.serena/.gitignore b/.serena/.gitignore
new file mode 100644
index 000000000..2e510aff5
--- /dev/null
+++ b/.serena/.gitignore
@@ -0,0 +1,2 @@
+/cache
+/project.local.yml
diff --git a/.serena/project.yml b/.serena/project.yml
new file mode 100644
index 000000000..0e9ac3ead
--- /dev/null
+++ b/.serena/project.yml
@@ -0,0 +1,133 @@
+# the name by which the project can be referenced within Serena
+project_name: "feature-opencode-wrap"
+
+
+# list of languages for which language servers are started; choose from:
+# al angular ansible bash clojure
+# cpp cpp_ccls crystal csharp csharp_omnisharp
+# dart elixir elm erlang fortran
+# fsharp go groovy haskell haxe
+# hlsl html java json julia
+# kotlin lean4 lua luau markdown
+# matlab msl nix ocaml pascal
+# perl php php_phpactor powershell python
+# python_jedi python_ty r rego ruby
+# ruby_solargraph rust scala scss solidity
+# svelte swift systemverilog terraform toml
+# typescript typescript_vts vue yaml zig
+# (This list may be outdated. For the current list, see values of Language enum here:
+# https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
+# For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
+# Note:
+# - For C, use cpp
+# - For JavaScript, use typescript
+# - For Angular projects, use angular (subsumes typescript+html; requires `npm install` in the project root)
+# - For Svelte projects, use svelte (subsumes typescript/javascript for .svelte projects; requires npm)
+# - For SCSS / Sass / plain CSS, use scss (some-sass-language-server handles all three)
+# - For Free Pascal/Lazarus, use pascal
+# Special requirements:
+# Some languages require additional setup/installations.
+# See here for details: https://oraios.github.io/serena/01-about/020_programming-languages.html#language-servers
+# When using multiple languages, the first language server that supports a given file will be used for that file.
+# The first language is the default language and the respective language server will be used as a fallback.
+# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
+languages:
+- typescript
+
+# the encoding used by text files in the project
+# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
+encoding: "utf-8"
+
+# line ending convention to use when writing source files.
+# Possible values: unset (use global setting), "lf", "crlf", or "native" (platform default)
+# This does not affect Serena's own files (e.g. memories and configuration files), which always use native line endings.
+line_ending:
+
+# The language backend to use for this project.
+# If not set, the global setting from serena_config.yml is used.
+# Valid values: LSP, JetBrains
+# Note: the backend is fixed at startup. If a project with a different backend
+# is activated post-init, an error will be returned.
+language_backend:
+
+# whether to use project's .gitignore files to ignore files
+ignore_all_files_in_gitignore: true
+
+# advanced configuration option allowing to configure language server-specific options.
+# Maps the language key to the options.
+# Have a look at the docstring of the constructors of the LS implementations within solidlsp (e.g., for C# or PHP) to see which options are available.
+# No documentation on options means no options are available.
+ls_specific_settings: {}
+
+# list of additional workspace folder paths for cross-package reference support (e.g. in monorepos).
+# Paths can be absolute or relative to the project root.
+# Each folder is registered as an LSP workspace folder, enabling language servers to discover
+# symbols and references across package boundaries.
+# Currently supported for: TypeScript.
+# Example:
+# additional_workspace_folders:
+# - ../sibling-package
+# - ../shared-lib
+additional_workspace_folders: []
+
+# list of additional paths to ignore in this project.
+# Same syntax as gitignore, so you can use * and **.
+# Note: global ignored_paths from serena_config.yml are also applied additively.
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+# list of tool names to exclude.
+# This extends the existing exclusions (e.g. from the global configuration)
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+excluded_tools: []
+
+# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default).
+# This extends the existing inclusions (e.g. from the global configuration).
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+included_optional_tools: []
+
+# fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
+# This cannot be combined with non-empty excluded_tools or included_optional_tools.
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+fixed_tools: []
+
+# list of mode names that are to be activated by default, overriding the setting in the global configuration.
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
+# If the setting is undefined/empty, the default_modes from the global configuration (serena_config.yml) apply.
+# Otherwise, this overrides the setting from the global configuration (serena_config.yml).
+# Therefore, you can set this to [] if you do not want the default modes defined in the global config to apply
+# for this project.
+# This setting can, in turn, be overridden by CLI parameters (--mode).
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
+default_modes:
+
+# list of mode names to be activated additionally for this project, e.g. ["query-projects"]
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
+added_modes:
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+
+# time budget (seconds) per tool call for the retrieval of additional symbol information
+# such as docstrings or parameter information.
+# This overrides the corresponding setting in the global configuration; see the documentation there.
+# If null or missing, use the setting from the global configuration.
+symbol_info_budget:
+
+# list of regex patterns which, when matched, mark a memory entry as read‑only.
+# Extends the list from the global configuration, merging the two lists.
+read_only_memory_patterns: []
+
+# list of regex patterns for memories to completely ignore.
+# Matching memories will not appear in list_memories or activate_project output
+# and cannot be accessed via read_memory or write_memory.
+# To access ignored memory files, use the read_file tool on the raw file path.
+# Extends the list from the global configuration, merging the two lists.
+# Example: ["_archive/.*", "_episodes/.*"]
+ignored_memory_patterns: []
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..6b2291ab0
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,42 @@
+<!-- headroom:rtk-instructions -->
+# RTK (Rust Token Killer) - Token-Optimized Commands
+
+When running shell commands, **always prefix with `rtk`**. This reduces context
+usage by 60-90% with zero behavior change. If rtk has no filter for a command,
+it passes through unchanged — so it is always safe to use.
+
+## Key Commands
+```bash
+# Git (59-80% savings)
+rtk git status rtk git diff rtk git log
+
+# Files & Search (60-75% savings)
+rtk ls <path> rtk read <file> rtk grep <pattern>
+rtk find <pattern> rtk diff <file>
+
+# Test (90-99% savings) — shows failures only
+rtk pytest tests/ rtk cargo test rtk test <cmd>
+
+# Build & Lint (80-90% savings) — shows errors only
+rtk tsc rtk lint rtk cargo build
+rtk prettier --check rtk mypy rtk ruff check
+
+# Analysis (70-90% savings)
+rtk err <cmd> rtk log <file> rtk json <file>
+rtk summary <cmd> rtk deps rtk env
+
+# GitHub (26-87% savings)
+rtk gh pr view <n> rtk gh run list rtk gh issue list
+
+# Infrastructure (85% savings)
+rtk docker ps rtk kubectl get rtk docker logs <c>
+
+# Package managers (70-90% savings)
+rtk pip list rtk pnpm install rtk npm run <script>
+```
+
+## Rules
+- In command chains, prefix each segment: `rtk git add . && rtk git commit -m "msg"`
+- For debugging, use raw command without rtk prefix
+- `rtk proxy <cmd>` runs command without filtering but tracks usage
+<!-- /headroom:rtk-instructions -->
diff --git a/Makefile b/Makefile
index 872fde832..5608affb7 100644
--- a/Makefile
+++ b/Makefile
@@ -22,6 +22,10 @@ help:
@echo " make lint - cargo clippy --workspace -- -D warnings"
@echo " make clean - cargo clean"
@echo ""
+ @echo "E2e targets:"
+ @echo " make build-e2e-wrap - build the wrap-e2e Docker image"
+ @echo " make run-e2e-wrap - build + run the wrap-e2e Docker container"
+ @echo ""
@echo "Pre-push verification (run BEFORE git push to catch CI failures locally):"
@echo " make ci-precheck - run all CI gates (rust + python + commitlint)"
@echo " make ci-precheck-rust - cargo fmt --check + clippy + test"
@@ -138,3 +142,16 @@ ci-precheck-commitlint:
install-git-hooks:
@scripts/install-git-hooks.sh
+
+# ─── E2e Docker targets ────────────────────────────────────────────────────
+#
+# The wrap-e2e Dockerfile uses manylinux_2_28_x86_64 as its builder stage,
+# which only ships amd64 binaries. Pass --platform linux/amd64 explicitly
+# so the build works on Apple Silicon (requires QEMU emulation). On native
+# x86_64 hosts the flag is harmless and matches CI behaviour.
+
+build-e2e-wrap:
+ docker build --platform linux/amd64 -f e2e/wrap/Dockerfile -t headroom-wrap-e2e .
+
+run-e2e-wrap: build-e2e-wrap
+ docker run --rm headroom-wrap-e2e
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
index cfd4a3173..4d64eadd3 100644
--- a/docs/content/docs/meta.json
+++ b/docs/content/docs/meta.json
@@ -33,6 +33,7 @@
"strands",
"litellm",
"claude-code-vertex",
+ "opencode",
"mcp",
"---Configuration---",
"configuration",
diff --git a/docs/content/docs/opencode.mdx b/docs/content/docs/opencode.mdx
new file mode 100644
index 000000000..17c35a949
--- /dev/null
+++ b/docs/content/docs/opencode.mdx
@@ -0,0 +1,120 @@
+---
+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.
diff --git a/docs/content/docs/persistent-installs.mdx b/docs/content/docs/persistent-installs.mdx
index 955a21e16..eecf6e118 100644
--- a/docs/content/docs/persistent-installs.mdx
+++ b/docs/content/docs/persistent-installs.mdx
@@ -91,6 +91,7 @@ Provider scope is intentionally conservative. The current direct adapters are:
- Claude Code → `~/.claude/settings.json` `env`
- Codex → managed block in `~/.codex/config.toml`
- OpenClaw → existing `wrap openclaw` / `unwrap openclaw` flow
+- OpenCode → managed block in `~/.config/opencode/opencode.json`
For Copilot, Aider, Cursor, and broader env-driven setups, prefer `--scope user` or `--scope system`.
diff --git a/e2e/wrap/Dockerfile b/e2e/wrap/Dockerfile
index 6bc55356a..d33dc95d6 100644
--- a/e2e/wrap/Dockerfile
+++ b/e2e/wrap/Dockerfile
@@ -64,6 +64,7 @@ ENV DEBIAN_FRONTEND=noninteractive \
AIDER_CHAT_VERSION=0.86.2 \
CODEX_VERSION=0.118.0 \
OPENCLAW_VERSION=2026.4.7 \
+ OPENCODE_VERSION=1.17.8 \
PATH="/opt/headroom-venv/bin:/opt/aider-venv/bin:${PATH}" \
PIP_DISABLE_PIP_VERSION_CHECK=1 \
PIP_NO_CACHE_DIR=1 \
@@ -108,7 +109,15 @@ RUN python -m venv /opt/headroom-venv && \
python -m venv /opt/aider-venv && \
/opt/aider-venv/bin/python -m pip install --upgrade pip && \
/opt/aider-venv/bin/python -m pip install "aider-chat==${AIDER_CHAT_VERSION}" && \
- npm install -g --no-fund --no-audit "@openai/codex@${CODEX_VERSION}" "openclaw@${OPENCLAW_VERSION}"
+ npm install -g --no-fund --no-audit "@openai/codex@${CODEX_VERSION}" "openclaw@${OPENCLAW_VERSION}" && \
+ curl -fsSL https://opencode.ai/install | VERSION="${OPENCODE_VERSION}" bash
+
+# The opencode installer adds its bin dir to .bashrc. Non-login shells
+# (including CMD, docker run, and e2e shims spawned by subprocess) won't
+# source .bashrc, so add the dir to PATH explicitly. The e2e shim shadows
+# opencode anyway, but this guarantees `which opencode` works for
+# diagnostics.
+ENV PATH="/root/.opencode/bin:${PATH}"
COPY e2e/wrap ./e2e/wrap
diff --git a/e2e/wrap/run.py b/e2e/wrap/run.py
index d6313795f..aeb8b5fdf 100644
--- a/e2e/wrap/run.py
+++ b/e2e/wrap/run.py
@@ -35,6 +35,7 @@ CLINE_PORT = 28892
CONTINUE_PORT = 28893
GOOSE_PORT = 28894
OPENHANDS_PORT = 28895
+OPENCODE_PORT = 28896
def log(message: str) -> None:
@@ -225,7 +226,12 @@ def create_shims(shim_dir: Path) -> None:
"cwd": os.getcwd(),
"env": {
key: os.environ.get(key)
- for key in ("OPENAI_BASE_URL", "OPENAI_API_BASE", "ANTHROPIC_BASE_URL")
+ for key in (
+ "OPENAI_BASE_URL",
+ "OPENAI_API_BASE",
+ "ANTHROPIC_BASE_URL",
+ "OPENCODE_CONFIG_CONTENT",
+ )
if os.environ.get(key) is not None
},
}
@@ -276,7 +282,12 @@ def create_shims(shim_dir: Path) -> None:
"cwd": os.getcwd(),
"env": {
key: os.environ.get(key)
- for key in ("OPENAI_BASE_URL", "OPENAI_API_BASE", "ANTHROPIC_BASE_URL")
+ for key in (
+ "OPENAI_BASE_URL",
+ "OPENAI_API_BASE",
+ "ANTHROPIC_BASE_URL",
+ "OPENCODE_CONFIG_CONTENT",
+ )
if os.environ.get(key) is not None
},
}
@@ -365,6 +376,7 @@ def create_shims(shim_dir: Path) -> None:
write_executable(shim_dir / "claude", generic_shim)
write_executable(shim_dir / "codex", codex_shim)
write_executable(shim_dir / "aider", generic_shim)
+ write_executable(shim_dir / "opencode", generic_shim)
write_executable(shim_dir / "rtk", rtk_shim)
@@ -912,6 +924,7 @@ def main() -> None:
verify_continue_wrap(base_env, project_dir)
verify_goose_wrap(base_env, project_dir)
verify_openhands_wrap(base_env, project_dir)
+ verify_opencode_wrap(base_env, project_dir, log_dir)
local_plugin_dir = prepare_local_openclaw_plugin(base_env, tmp_dir)
verify_openclaw_wrap(base_env, project_dir, local_plugin_dir)
finally:
@@ -921,5 +934,48 @@ def main() -> None:
log("All Docker wrap e2e checks passed.")
+def verify_opencode_wrap(
+ base_env: dict[str, str], project_dir: Path, log_dir: Path
+) -> None:
+ port = OPENCODE_PORT
+ run(
+ ["headroom", "wrap", "opencode", "--port", str(port), "--", "--help"],
+ env=base_env,
+ cwd=project_dir,
+ timeout=120,
+ )
+ global_agents = Path(base_env["HOME"]) / ".config" / "opencode" / "AGENTS.md"
+ project_agents = project_dir / "AGENTS.md"
+ assert_true(global_agents.exists(), "Opencode wrap should create ~/.config/opencode/AGENTS.md")
+ assert_true(project_agents.exists(), "Opencode wrap should create project AGENTS.md")
+ assert_true(RTK_MARKER in global_agents.read_text(encoding="utf-8"), "Missing RTK marker in global AGENTS.md")
+ assert_true(
+ RTK_MARKER in project_agents.read_text(encoding="utf-8"),
+ "Missing RTK marker in project AGENTS.md",
+ )
+
+ entries = read_jsonl(log_dir / "opencode.jsonl")
+ assert_true(len(entries) > 0, "Opencode shim should have been invoked")
+ env_vars = entries[-1]["env"]
+ assert_true(
+ env_vars.get("OPENCODE_CONFIG_CONTENT") is not None,
+ "Opencode wrap should set OPENCODE_CONFIG_CONTENT",
+ )
+ config = json.loads(env_vars["OPENCODE_CONFIG_CONTENT"])
+ assert_true(
+ config["provider"]["headroom"]["options"]["baseURL"] == f"http://127.0.0.1:{port}/v1",
+ "Opencode wrap should inject headroom provider baseURL",
+ )
+
+ run(["headroom", "unwrap", "opencode", "--port", str(port)], env=base_env, cwd=project_dir, timeout=120)
+ config_path = Path(base_env["HOME"]) / ".config" / "opencode" / "opencode.json"
+ if config_path.exists():
+ content = config_path.read_text(encoding="utf-8")
+ assert_true(
+ "headroom" not in content,
+ "Opencode unwrap should remove headroom provider from config",
+ )
+
+
if __name__ == "__main__":
main()
diff --git a/headroom/binaries.py b/headroom/binaries.py
index 153085787..2280ed108 100644
--- a/headroom/binaries.py
+++ b/headroom/binaries.py
@@ -143,6 +143,24 @@ def detect_platform() -> PlatformKey:
# ---------- Cache dir ----------------------------------------------------- #
+def _is_writable_dir(path: Path) -> bool:
+ try:
+ mode = path.stat().st_mode
+ except OSError:
+ return False
+ return path.is_dir() and bool(mode & 0o222)
+
+
+def _has_writable_existing_parent(path: Path) -> bool:
+ current = path
+ while not current.exists():
+ parent = current.parent
+ if parent == current:
+ return False
+ current = parent
+ return _is_writable_dir(current)
+
+
def cache_dir() -> Path:
override = os.environ.get("HEADROOM_BINARIES_CACHE")
if override:
@@ -218,7 +236,11 @@ def _mirror_url(url: str) -> str:
def _download(url: str, dest: Path, *, progress: bool = True) -> None:
if os.environ.get("HEADROOM_BINARIES_OFFLINE"):
raise OfflineError(f"offline mode (HEADROOM_BINARIES_OFFLINE=1) but fetch required: {url}")
+ if not _has_writable_existing_parent(dest.parent):
+ raise OSError(f"binary cache directory parent is not writable: {dest.parent}")
dest.parent.mkdir(parents=True, exist_ok=True)
+ if not _is_writable_dir(dest.parent):
+ raise OSError(f"binary cache directory is not writable: {dest.parent}")
final_url = _mirror_url(url)
req = urllib.request.Request(final_url, headers={"User-Agent": "headroom-binaries/1"})
try:
@@ -287,7 +309,11 @@ def _verify_sha256(path: Path, expected: str | None) -> None:
def _extract(archive: Path, member: str, dest: Path) -> None:
"""Extract `member` from archive into `dest` (single-file binary)."""
+ if not _has_writable_existing_parent(dest.parent):
+ raise OSError(f"binary cache directory parent is not writable: {dest.parent}")
dest.parent.mkdir(parents=True, exist_ok=True)
+ if not _is_writable_dir(dest.parent):
+ raise OSError(f"binary cache directory is not writable: {dest.parent}")
name = archive.name.lower()
try:
if name.endswith(".tar.gz") or name.endswith(".tgz"):
@@ -452,6 +478,8 @@ def resolve(tool: str) -> Path:
def ensure_tools(quiet: bool = False) -> dict[str, Path | None]:
+ if not _has_writable_existing_parent(cache_dir()):
+ return {name: which(name) for name in _registry().get("tools", {})}
"""Install every tool in the registry if missing. Safe to call repeatedly.
Called at proxy startup and on first `headroom` CLI invocation so that no
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.py
index 4b5ef2f1b..8349b3a54 100644
--- a/headroom/cli/wrap.py
+++ b/headroom/cli/wrap.py
@@ -107,6 +107,17 @@ from headroom.providers.openclaw import (
from headroom.providers.openclaw import (
normalize_gateway_provider_ids as _normalize_openclaw_gateway_provider_ids_impl,
)
+from headroom.providers.opencode import build_launch_env as _build_opencode_launch_env
+from headroom.providers.opencode.config import (
+ _MCP_MARKER_END, # noqa: F401
+ _MCP_MARKER_START,
+ _PROVIDER_MARKER_END, # noqa: F401
+ _PROVIDER_MARKER_START,
+ inject_opencode_provider_config,
+ opencode_config_paths,
+ snapshot_opencode_config_if_unwrapped,
+ strip_opencode_headroom_blocks,
+)
from headroom.proxy.project_context import with_project_prefix as _with_project_prefix
from .main import main
@@ -115,7 +126,7 @@ _CONTEXT_TOOL_ENV = "HEADROOM_CONTEXT_TOOL"
_CONTEXT_TOOL_RTK = "rtk"
_CONTEXT_TOOL_LEAN_CTX = "lean-ctx"
_VALID_CONTEXT_TOOLS = {_CONTEXT_TOOL_RTK, _CONTEXT_TOOL_LEAN_CTX}
-_AGENT_SAVINGS_TARGET_AGENTS = {"claude", "codex", "cursor"}
+_AGENT_SAVINGS_TARGET_AGENTS = {"claude", "codex", "cursor", "opencode"}
_WRAP_PROXY_TIMEOUT_ENV = "HEADROOM_WRAP_PROXY_TIMEOUT"
_WRAP_PROXY_TIMEOUT_DEFAULT_SECONDS = 45
_WRAP_PROXY_TIMEOUT_ML_DEFAULT_SECONDS = 90
@@ -2910,6 +2921,7 @@ def wrap() -> None:
headroom wrap goose # Goose (Block) CLI
headroom wrap openhands # OpenHands CLI
headroom wrap openclaw # OpenClaw plugin bootstrap
+ headroom wrap opencode # OpenCode CLI
\b
`wrap` vs `proxy`:
@@ -2920,8 +2932,6 @@ def wrap() -> None:
ANTHROPIC_BASE_URL / OPENAI_BASE_URL yourself.
\b
- Note: `headroom wrap opencode` does NOT exist. For opencode, run
- `headroom proxy` and point opencode at it via OPENAI_BASE_URL.
`openclaw` is a separate tool — different from opencode.
"""
@@ -4778,6 +4788,251 @@ def openclaw(
click.echo()
+# =============================================================================
+# OpenCode
+# =============================================================================
+
+
[email protected](context_settings={"ignore_unknown_options": True})
[email protected]("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")
+ "--no-context-tool",
+ "--no-rtk",
+ "no_rtk",
+ is_flag=True,
+ help="Skip CLI context-tool setup",
+)
[email protected]("--no-mcp", is_flag=True, help="Skip headroom MCP server registration")
[email protected]("--no-serena", is_flag=True, help="Skip Serena MCP server registration")
+ "--code-graph",
+ is_flag=True,
+ help="Enable code graph indexing via codebase-memory-mcp (optional)",
+)
[email protected]("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")
[email protected]("--learn", is_flag=True, help="Enable live traffic learning")
[email protected]("--memory", is_flag=True, help="Enable persistent cross-session memory")
+ "--backend", default=None, help="API backend: 'anthropic', 'anyllm', 'litellm-vertex', etc."
+)
[email protected]("--anyllm-provider", default=None, help="Provider for any-llm backend")
[email protected]("--region", default=None, help="Cloud region for Bedrock/Vertex")
[email protected]("--verbose", "-v", is_flag=True, help="Verbose output")
[email protected]("--prepare-only", is_flag=True, hidden=True)
[email protected]("opencode_args", nargs=-1, type=click.UNPROCESSED)
+def opencode(
+ port: int,
+ no_rtk: bool,
+ no_mcp: bool,
+ no_serena: bool,
+ code_graph: bool,
+ no_proxy: bool,
+ learn: bool,
+ memory: bool,
+ backend: str | None,
+ anyllm_provider: str | None,
+ region: str | None,
+ verbose: bool,
+ prepare_only: bool,
+ opencode_args: tuple,
+) -> None:
+ """Launch OpenCode through Headroom proxy.
+
+ \b
+ Sets OPENCODE_CONFIG_CONTENT to route all OpenCode API calls through
+ Headroom. Configures a headroom provider via @ai-sdk/openai-compatible.
+ Also sets OPENAI_BASE_URL and ANTHROPIC_BASE_URL as fallbacks.
+
+ \b
+ Examples:
+ headroom wrap opencode # Start proxy + context tool + opencode
+ headroom wrap opencode -- "fix the bug" # Pass prompt to opencode
+ headroom wrap opencode --no-context-tool # Skip CLI context-tool setup
+ headroom wrap opencode --no-mcp # Skip MCP retrieve tool registration
+ headroom wrap opencode --no-serena # Skip Serena MCP registration
+ headroom wrap opencode --port 9999 # Custom proxy port
+ headroom wrap opencode --backend anyllm --anyllm-provider groq
+ """
+ # Snapshot OpenCode config.json BEFORE any wrap-time mutation so
+ # `headroom unwrap opencode` can restore the user's pre-wrap state.
+ _opencode_config_file, _opencode_backup_file = opencode_config_paths()
+ snapshot_opencode_config_if_unwrapped(_opencode_config_file, _opencode_backup_file)
+
+ # Setup CLI context tool for OpenCode.
+ if not no_rtk:
+ if _selected_context_tool() == _CONTEXT_TOOL_LEAN_CTX:
+ click.echo(" Setting up lean-ctx for OpenCode...")
+ _setup_lean_ctx_agent("opencode", verbose=verbose)
+ else:
+ click.echo(" Setting up rtk for OpenCode...")
+ rtk_path = _ensure_rtk_binary(verbose=verbose)
+ if rtk_path:
+ # Inject into project AGENTS.md
+ project_agents = Path.cwd() / "AGENTS.md"
+ _inject_rtk_instructions(project_agents, verbose=verbose)
+ # Inject into global OpenCode AGENTS.md
+ global_agents = _opencode_home_dir() / "AGENTS.md"
+ _inject_rtk_instructions(global_agents, verbose=verbose)
+
+ # Register headroom MCP server in OpenCode config so OpenCode can
+ # call headroom_retrieve on compression markers from the proxy.
+ if not no_mcp:
+ from headroom.mcp_registry import OpencodeRegistrar
+
+ _setup_headroom_mcp(OpencodeRegistrar(), port, verbose=verbose, force=True)
+ elif verbose:
+ click.echo(" Skipping MCP retrieve tool (--no-mcp)")
+
+ if not no_serena:
+ from headroom.mcp_registry import OpencodeRegistrar
+
+ _setup_serena_mcp(OpencodeRegistrar(), context="opencode", verbose=verbose, force=True)
+ else:
+ from headroom.mcp_registry import OpencodeRegistrar
+
+ _disable_serena_mcp(OpencodeRegistrar(), verbose=verbose)
+
+ # Setup memory MCP server for OpenCode (native tool integration)
+ if memory:
+ click.echo(" Setting up memory for OpenCode...")
+ mem_dir = Path.cwd() / ".headroom"
+ mem_dir.mkdir(parents=True, exist_ok=True)
+ db_path = str(mem_dir / "memory.db")
+ mem_user = os.environ.get("USER", os.environ.get("USERNAME", "default"))
+ _inject_memory_mcp_config(db_path, mem_user)
+ agents_md = Path.cwd() / "AGENTS.md"
+ _inject_memory_agents_md(agents_md)
+
+ if prepare_only:
+ inject_opencode_provider_config(port)
+ return
+
+ opencode_bin = shutil.which("opencode")
+ if not opencode_bin:
+ click.echo("Error: 'opencode' not found in PATH.")
+ click.echo("Install OpenCode: https://opencode.ai")
+ raise SystemExit(1)
+
+ env, env_vars_display = _build_opencode_launch_env(
+ port, os.environ, project=_project_name_from_cwd(), include_mcp=not no_mcp
+ )
+
+ # Inject Headroom provider into OpenCode config so traffic routes through proxy.
+ inject_opencode_provider_config(port)
+ if memory:
+ mem_dir = Path.cwd() / ".headroom"
+ _inject_memory_mcp_config(
+ str(mem_dir / "memory.db"),
+ os.environ.get("USER", os.environ.get("USERNAME", "default")),
+ )
+
+ _launch_tool(
+ binary=opencode_bin,
+ args=opencode_args,
+ env=env,
+ port=port,
+ no_proxy=no_proxy,
+ tool_label="OPENCODE",
+ env_vars_display=env_vars_display,
+ learn=learn,
+ memory=memory,
+ agent_type="opencode",
+ code_graph=code_graph,
+ backend=backend,
+ anyllm_provider=anyllm_provider,
+ region=region,
+ )
+
+
+def _opencode_home_dir() -> Path:
+ """Return the OpenCode home/config directory."""
+ env_path = os.environ.get("OPENCODE_HOME", "").strip()
+ if env_path:
+ return Path(env_path).expanduser()
+ return Path.home() / ".config" / "opencode"
+
+
+# =============================================================================
+# OpenCode (unwrap)
+# =============================================================================
+
+
[email protected]("opencode")
[email protected]("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")
[email protected]("--no-stop-proxy", is_flag=True, help="Do not stop the local Headroom proxy")
+def unwrap_opencode(port: int, no_stop_proxy: bool) -> None:
+ """Undo ``headroom wrap opencode`` edits to the active OpenCode config file.
+
+ Behaviour:
+
+ * If a pre-wrap backup (``opencode.json.headroom-backup``) exists, the
+ original file is restored byte-for-byte and the backup is removed.
+ * Otherwise, if the config file still contains the Headroom-managed
+ block, that block is stripped out and the rest of the file is
+ preserved.
+ * If the config only ever contained Headroom-written content, the file
+ is removed entirely so OpenCode falls back to its defaults.
+ * If neither a backup nor a Headroom block is present, this is a safe
+ no-op.
+ """
+ click.echo()
+ click.echo(" ╔═══════════════════════════════════════════════╗")
+ click.echo(" ║ HEADROOM UNWRAP: OPENCODE ║")
+ click.echo(" ╚═══════════════════════════════════════════════╝")
+ click.echo()
+
+ config_file, backup_file = opencode_config_paths()
+
+ if backup_file.exists():
+ try:
+ shutil.copy2(backup_file, config_file)
+ backup_file.unlink()
+ click.echo(f" Restored prior {config_file} from pre-wrap backup.")
+ status = "restored"
+ except OSError as exc:
+ raise click.ClickException(
+ f"could not restore OpenCode config from backup: {exc}"
+ ) from exc
+ elif config_file.exists():
+ content = config_file.read_text()
+ if _PROVIDER_MARKER_START in content or _MCP_MARKER_START in content:
+ cleaned = strip_opencode_headroom_blocks(content)
+ if cleaned.strip():
+ config_file.write_text(cleaned + "\n", encoding="utf-8")
+ click.echo(f" Removed Headroom block from {config_file}; other content preserved.")
+ status = "cleaned"
+ else:
+ config_file.unlink()
+ click.echo(f" Removed {config_file} (contained only Headroom-written config).")
+ status = "removed"
+ else:
+ click.echo(f" Nothing to undo: {config_file} has no Headroom wrap markers.")
+ status = "noop"
+ else:
+ click.echo(f" Nothing to undo: {config_file} does not exist.")
+ status = "noop"
+
+ # Remove Serena MCP if it was installed by Headroom.
+ # Also remove the headroom MCP server itself.
+ from headroom.mcp_registry import OpencodeRegistrar
+
+ opencode_registrar = OpencodeRegistrar()
+ if opencode_registrar.detect():
+ if opencode_registrar.unregister_server("headroom"):
+ click.echo(" Removed Headroom MCP server from OpenCode.")
+ serena_status = _remove_headroom_installed_serena_mcp(opencode_registrar)
+ if serena_status == "removed":
+ click.echo(" Removed Headroom-installed Serena MCP server from OpenCode.")
+ elif serena_status == "failed":
+ click.echo(" Serena MCP server matched Headroom ledger but could not be removed.")
+
+ click.echo()
+ click.echo("✓ OpenCode is no longer routed through the Headroom proxy.")
+ if not no_stop_proxy and status != "noop":
+ _echo_unwrap_proxy_stop_status(_stop_local_proxy_for_unwrap(port), port)
+ click.echo()
+
+
@unwrap.command("openclaw")
@click.option("--proxy-port", default=8787, type=int, help="Headroom proxy port")
@click.option("--no-stop-proxy", is_flag=True, help="Do not stop the local Headroom proxy")
diff --git a/headroom/install/models.py b/headroom/install/models.py
index 777027998..08ec50a44 100644
--- a/headroom/install/models.py
+++ b/headroom/install/models.py
@@ -56,6 +56,7 @@ class ToolTarget(str, Enum):
AIDER = "aider"
CURSOR = "cursor"
OPENCLAW = "openclaw"
+ OPENCODE = "opencode"
def iso_utc_now() -> str:
diff --git a/headroom/install/paths.py b/headroom/install/paths.py
index a0f6a3def..c7a89545b 100644
--- a/headroom/install/paths.py
+++ b/headroom/install/paths.py
@@ -2,6 +2,7 @@
from __future__ import annotations
+import os
import re
import sys
from pathlib import Path
@@ -118,3 +119,16 @@ def openclaw_config_path() -> Path:
"""Return the OpenClaw config path."""
return Path.home() / ".openclaw" / "openclaw.json"
+
+
+def opencode_config_path() -> Path:
+ """Return the OpenCode config path.
+
+ Resolves ``~/.config/opencode/opencode.json`` when ``OPENCODE_CONFIG``
+ is unset; otherwise the value of that environment variable.
+ """
+
+ env_path = os.environ.get("OPENCODE_CONFIG", "").strip()
+ if env_path:
+ return Path(env_path).expanduser()
+ return Path.home() / ".config" / "opencode" / "opencode.json"
diff --git a/headroom/install/planner.py b/headroom/install/planner.py
index e12f286b6..60899e548 100644
--- a/headroom/install/planner.py
+++ b/headroom/install/planner.py
@@ -27,11 +27,13 @@ SUPPORTED_TARGETS = [
ToolTarget.AIDER,
ToolTarget.CURSOR,
ToolTarget.OPENCLAW,
+ ToolTarget.OPENCODE,
]
PROVIDER_SCOPE_TARGETS = [
ToolTarget.CLAUDE,
ToolTarget.CODEX,
ToolTarget.OPENCLAW,
+ ToolTarget.OPENCODE,
]
@@ -72,7 +74,7 @@ def resolve_targets(
if unsupported:
unsupported_list = ", ".join(sorted(set(unsupported)))
raise click.ClickException(
- "Provider scope supports only claude, codex, and openclaw; "
+ "Provider scope supports only claude, codex, openclaw, and opencode; "
f"unsupported targets: {unsupported_list}"
)
diff --git a/headroom/install/runtime.py b/headroom/install/runtime.py
index 762e254fc..feaa815e9 100644
--- a/headroom/install/runtime.py
+++ b/headroom/install/runtime.py
@@ -74,7 +74,7 @@ def _runtime_env(manifest: DeploymentManifest) -> dict[str, str]:
def _ensure_host_dirs() -> None:
- for subdir in (".headroom", ".claude", ".codex", ".gemini"):
+ for subdir in (".headroom", ".claude", ".codex", ".gemini", ".config/opencode"):
(Path.home() / subdir).mkdir(parents=True, exist_ok=True)
@@ -120,6 +120,8 @@ def build_runtime_command(manifest: DeploymentManifest) -> list[str]:
f"{_mount_source(home, '.codex')}:{container_home}/.codex",
"--volume",
f"{_mount_source(home, '.gemini')}:{container_home}/.gemini",
+ "--volume",
+ f"{_mount_source(home, '.config/opencode')}:{container_home}/.config/opencode",
]
if not _is_windows():
getuid = getattr(os, "getuid", None)
diff --git a/headroom/mcp_registry/__init__.py b/headroom/mcp_registry/__init__.py
index 61c9eb163..597e36069 100644
--- a/headroom/mcp_registry/__init__.py
+++ b/headroom/mcp_registry/__init__.py
@@ -17,6 +17,7 @@ from .base import MCPRegistrar, RegisterResult, RegisterStatus, ServerSpec
from .claude import ClaudeRegistrar
from .codex import CodexRegistrar
from .display import any_succeeded, format_result, format_results
+from .opencode import OpencodeRegistrar
from .install import (
DEFAULT_PROXY_URL,
build_headroom_spec,
@@ -30,6 +31,7 @@ __all__ = [
"ClaudeRegistrar",
"CodexRegistrar",
"MCPRegistrar",
+ "OpencodeRegistrar",
"RegisterResult",
"RegisterStatus",
"ServerSpec",
diff --git a/headroom/mcp_registry/install.py b/headroom/mcp_registry/install.py
index 71401051a..86127c190 100644
--- a/headroom/mcp_registry/install.py
+++ b/headroom/mcp_registry/install.py
@@ -7,6 +7,7 @@ from collections.abc import Iterable
from .base import MCPRegistrar, RegisterResult, RegisterStatus, ServerSpec
from .claude import ClaudeRegistrar
from .codex import CodexRegistrar
+from .opencode import OpencodeRegistrar
#: Default proxy URL used when none is given.
DEFAULT_PROXY_URL = "http://127.0.0.1:8787"
@@ -17,7 +18,7 @@ def get_all_registrars() -> list[MCPRegistrar]:
The list grows as we add adapters for Cursor, Continue, Cline, etc.
"""
- return [ClaudeRegistrar(), CodexRegistrar()]
+ return [ClaudeRegistrar(), CodexRegistrar(), OpencodeRegistrar()]
def build_headroom_spec(proxy_url: str = DEFAULT_PROXY_URL) -> ServerSpec:
diff --git a/headroom/mcp_registry/opencode.py b/headroom/mcp_registry/opencode.py
new file mode 100644
index 000000000..105c1ec6f
--- /dev/null
+++ b/headroom/mcp_registry/opencode.py
@@ -0,0 +1,182 @@
+"""OpenCode MCP registrar.
+
+OpenCode stores MCP server configuration in ``~/.config/opencode/opencode.json``
+under the top-level ``mcp`` key. This registrar edits that JSON file directly.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import shutil
+from pathlib import Path
+from typing import Any
+
+from .base import MCPRegistrar, RegisterResult, RegisterStatus, ServerSpec
+
+logger = logging.getLogger(__name__)
+
+
+def _opencode_home_dir() -> Path:
+ """Return the OpenCode home/config directory."""
+ env_path = os.environ.get("OPENCODE_HOME", "").strip()
+ if env_path:
+ return Path(env_path).expanduser()
+ return Path.home() / ".config" / "opencode"
+
+
+def _opencode_config_path() -> Path:
+ """Return the active OpenCode config path."""
+ env_path = os.environ.get("OPENCODE_CONFIG", "").strip()
+ if env_path:
+ return Path(env_path).expanduser()
+ return _opencode_home_dir() / "opencode.json"
+
+
+def _read_json(path: Path) -> dict[str, Any]:
+ """Read a JSON file, returning empty dict if absent or unparseable."""
+ if not path.exists():
+ return {}
+ try:
+ with open(path) as f:
+ data = json.load(f)
+ except (OSError, json.JSONDecodeError):
+ return {}
+ if not isinstance(data, dict):
+ return {}
+ return data
+
+
+def _write_json(path: Path, data: dict[str, Any]) -> None:
+ path.parent.mkdir(parents=True, exist_ok=True)
+ with open(path, "w") as f:
+ json.dump(data, f, indent=2)
+ f.write("\n")
+
+
+def _entry_to_spec(name: str, entry: dict[str, Any]) -> ServerSpec:
+ command_value = entry.get("command")
+ if isinstance(command_value, list):
+ args = tuple(str(x) for x in command_value[1:])
+ command = str(command_value[0])
+ else:
+ command = str(command_value) if command_value else ""
+ args = ()
+ env_value = entry.get("env", {})
+ env: dict[str, str] = {}
+ if isinstance(env_value, dict):
+ env = {str(k): str(v) for k, v in env_value.items()}
+ return ServerSpec(name=name, command=command, args=args, env=env)
+
+
+def _spec_to_entry(spec: ServerSpec) -> dict[str, Any]:
+ entry: dict[str, Any] = {
+ "type": "remote",
+ "url": "",
+ "enabled": True,
+ }
+ if spec.args:
+ entry["command"] = [spec.command, *spec.args]
+ else:
+ entry["command"] = spec.command
+ if spec.env:
+ entry["env"] = dict(spec.env)
+ return entry
+
+
+def _specs_equivalent(a: ServerSpec, b: ServerSpec) -> bool:
+ return (
+ a.name == b.name
+ and a.command == b.command
+ and tuple(a.args) == tuple(b.args)
+ and dict(a.env) == dict(b.env)
+ )
+
+
+def _diff_specs(existing: ServerSpec, requested: ServerSpec) -> str:
+ parts: list[str] = []
+ if existing.command != requested.command:
+ parts.append(f"command {existing.command!r} -> {requested.command!r}")
+ if tuple(existing.args) != tuple(requested.args):
+ parts.append(f"args {list(existing.args)} -> {list(requested.args)}")
+ if dict(existing.env) != dict(requested.env):
+ parts.append(f"env {dict(existing.env)} -> {dict(requested.env)}")
+ if not parts:
+ return "spec differs in unidentified field(s)"
+ return "; ".join(parts)
+
+
+class OpencodeRegistrar(MCPRegistrar):
+ """Register MCP servers with OpenCode."""
+
+ name = "opencode"
+ display_name = "OpenCode"
+
+ def __init__(self, *, config_path: Path | None = None) -> None:
+ self._config_path = config_path or _opencode_config_path()
+
+ def detect(self) -> bool:
+ if shutil.which("opencode"):
+ return True
+ return self._config_path.parent.is_dir()
+
+ def get_server(self, server_name: str) -> ServerSpec | None:
+ data = _read_json(self._config_path)
+ mcp = data.get("mcp", {})
+ if not isinstance(mcp, dict):
+ return None
+ entry = mcp.get(server_name)
+ if not isinstance(entry, dict):
+ return None
+ return _entry_to_spec(server_name, entry)
+
+ def register_server(self, spec: ServerSpec, *, force: bool = False) -> RegisterResult:
+ existing = self.get_server(spec.name)
+
+ if existing is not None and _specs_equivalent(existing, spec):
+ return RegisterResult(RegisterStatus.ALREADY, "matches current configuration")
+
+ if existing is not None and not force:
+ return RegisterResult(
+ RegisterStatus.MISMATCH,
+ _diff_specs(existing, spec),
+ )
+
+ if existing is not None and force:
+ # Remove the existing entry before rewriting.
+ self.unregister_server(spec.name)
+
+ return self._write_entry(spec)
+
+ def unregister_server(self, server_name: str) -> bool:
+ data = _read_json(self._config_path)
+ mcp = data.get("mcp", {})
+ if not isinstance(mcp, dict):
+ return False
+ if server_name not in mcp:
+ return False
+ del mcp[server_name]
+ if not mcp:
+ data.pop("mcp", None)
+ try:
+ _write_json(self._config_path, data)
+ except OSError:
+ return False
+ return True
+
+ def _write_entry(self, spec: ServerSpec) -> RegisterResult:
+ try:
+ self._config_path.parent.mkdir(parents=True, exist_ok=True)
+ data = _read_json(self._config_path)
+ mcp = data.setdefault("mcp", {})
+ if not isinstance(mcp, dict):
+ mcp = {}
+ data["mcp"] = mcp
+ mcp[spec.name] = _spec_to_entry(spec)
+ _write_json(self._config_path, data)
+ except OSError as exc:
+ return RegisterResult(
+ RegisterStatus.FAILED, f"could not write {self._config_path}: {exc}"
+ )
+ return RegisterResult(RegisterStatus.REGISTERED, f"wrote to {self._config_path}")
diff --git a/headroom/memory/traffic_learner.py b/headroom/memory/traffic_learner.py
index 955f2a11d..60b5b1e68 100644
--- a/headroom/memory/traffic_learner.py
+++ b/headroom/memory/traffic_learner.py
@@ -45,7 +45,7 @@ FLUSH_DEBOUNCE_SECONDS = 10.0
# Absolute file-path heuristic for anchoring a pattern to a project root.
# Matches POSIX paths (starts with /) and common Windows drive paths.
-_ABS_PATH_RE = re.compile(r"(?:[A-Za-z]:[\\/]|/)[\w./\\\-]+")
+_ABS_PATH_RE = re.compile(r"(?:[A-Za-z]:[\\/]|/)[\w./\\@\-]+")
# Error-recovery refinement: the Learned: error recovery section is capped,
# decayed, and re-validated at render time. Other categories are untouched.
diff --git a/headroom/observability/metrics.py b/headroom/observability/metrics.py
index 5d50a53e1..db91e7f4c 100644
--- a/headroom/observability/metrics.py
+++ b/headroom/observability/metrics.py
@@ -549,16 +549,9 @@ def configure_otel_metrics(config: OTelMetricsConfig | None = None) -> HeadroomO
def get_otel_metrics_status() -> dict[str, Any]:
with _metrics_lock:
- if _owned_metrics_config is None:
- return {
- "configured": False,
- "enabled": False,
- "service_name": None,
- "exporter": None,
- "endpoint": None,
- "resource_attributes": {},
- }
- return _owned_metrics_config.status()
+ if _owned_metrics_config is not None:
+ return _owned_metrics_config.status()
+ return OTelMetricsConfig.from_env(default_service_name="headroom-proxy").status()
def shutdown_otel_metrics() -> None:
diff --git a/headroom/observability/tracing.py b/headroom/observability/tracing.py
index 76eb9caf6..6637b8a3f 100644
--- a/headroom/observability/tracing.py
+++ b/headroom/observability/tracing.py
@@ -194,15 +194,25 @@ def configure_langfuse_tracing(
def get_langfuse_tracing_status() -> dict[str, Any]:
with _tracing_lock:
- if _owned_langfuse_config is None:
- return {
- "configured": False,
- "enabled": False,
- "service_name": None,
- "base_url": None,
- "endpoint": None,
- }
- return _owned_langfuse_config.status()
+ if _owned_langfuse_config is not None:
+ return _owned_langfuse_config.status()
+ if not any(
+ os.environ.get(name)
+ for name in (
+ "HEADROOM_LANGFUSE_ENABLED",
+ "LANGFUSE_PUBLIC_KEY",
+ "LANGFUSE_SECRET_KEY",
+ "LANGFUSE_BASE_URL",
+ )
+ ):
+ return {
+ "configured": False,
+ "enabled": False,
+ "service_name": None,
+ "base_url": None,
+ "endpoint": None,
+ }
+ return LangfuseTracingConfig.from_env(default_service_name="headroom-proxy").status()
def shutdown_headroom_tracing() -> None:
diff --git a/headroom/providers/install_registry.py b/headroom/providers/install_registry.py
index b866b333b..ba7a191f3 100644
--- a/headroom/providers/install_registry.py
+++ b/headroom/providers/install_registry.py
@@ -35,6 +35,13 @@ from headroom.providers.openclaw.install import (
from headroom.providers.openclaw.install import (
revert_provider_scope as _revert_openclaw_provider_scope,
)
+from headroom.providers.opencode.install import (
+ apply_provider_scope as _apply_opencode_provider_scope,
+)
+from headroom.providers.opencode.install import build_install_env as _build_opencode_install_env
+from headroom.providers.opencode.install import (
+ revert_provider_scope as _revert_opencode_provider_scope,
+)
_InstallEnvBuilder = Callable[..., dict[str, str]]
_ProviderScopeApplier = Callable[[DeploymentManifest], ManagedMutation | None]
@@ -47,12 +54,14 @@ _ENV_BUILDERS: dict[str, _InstallEnvBuilder] = {
"aider": _build_aider_install_env,
"cortex-code": _build_cortex_code_install_env,
"cursor": _build_cursor_install_env,
+ "opencode": _build_opencode_install_env,
}
_PROVIDER_SCOPE_HANDLERS: dict[str, tuple[_ProviderScopeApplier, _ProviderScopeReverter]] = {
"claude": (_apply_claude_provider_scope, _revert_claude_provider_scope),
"codex": (_apply_codex_provider_scope, _revert_codex_provider_scope),
"openclaw": (_apply_openclaw_provider_scope, _revert_openclaw_provider_scope),
+ "opencode": (_apply_opencode_provider_scope, _revert_opencode_provider_scope),
}
diff --git a/headroom/providers/opencode/__init__.py b/headroom/providers/opencode/__init__.py
new file mode 100644
index 000000000..b8cbd297b
--- /dev/null
+++ b/headroom/providers/opencode/__init__.py
@@ -0,0 +1,31 @@
+"""OpenCode-specific provider helpers."""
+
+from .config import (
+ _MCP_MARKER_END,
+ _MCP_MARKER_START,
+ _PROVIDER_MARKER_END,
+ _PROVIDER_MARKER_START,
+ inject_opencode_provider_config,
+ opencode_config_paths,
+ snapshot_opencode_config_if_unwrapped,
+ strip_opencode_headroom_blocks,
+)
+from .install import apply_provider_scope, build_install_env, revert_provider_scope
+from .runtime import build_launch_env, build_opencode_config_content, proxy_base_url
+
+__all__ = [
+ "_MCP_MARKER_END",
+ "_MCP_MARKER_START",
+ "_PROVIDER_MARKER_END",
+ "_PROVIDER_MARKER_START",
+ "apply_provider_scope",
+ "build_install_env",
+ "build_launch_env",
+ "build_opencode_config_content",
+ "inject_opencode_provider_config",
+ "opencode_config_paths",
+ "proxy_base_url",
+ "revert_provider_scope",
+ "snapshot_opencode_config_if_unwrapped",
+ "strip_opencode_headroom_blocks",
+]
diff --git a/headroom/providers/opencode/config.py b/headroom/providers/opencode/config.py
new file mode 100644
index 000000000..5ad6f0586
--- /dev/null
+++ b/headroom/providers/opencode/config.py
@@ -0,0 +1,229 @@
+"""OpenCode config file helpers for wrap and persistent install."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+from pathlib import Path
+from typing import Any
+
+import click
+
+from headroom.install.paths import opencode_config_path
+
+# Headroom-managed JSON marker comments for idempotent block injection.
+_PROVIDER_MARKER_START = "// --- Headroom proxy provider ---"
+_PROVIDER_MARKER_END = "// --- end Headroom proxy provider ---"
+_MCP_MARKER_START = "// --- Headroom MCP server ---"
+_MCP_MARKER_END = "// --- end Headroom MCP server ---"
+
+# Regex to strip headroom blocks (including the marker comments).
+_PROVIDER_BLOCK_RE = re.compile(
+ re.escape(_PROVIDER_MARKER_START)
+ + r".*?"
+ + re.escape(_PROVIDER_MARKER_END),
+ re.DOTALL,
+)
+_MCP_BLOCK_RE = re.compile(
+ re.escape(_MCP_MARKER_START)
+ + r".*?"
+ + re.escape(_MCP_MARKER_END),
+ re.DOTALL,
+)
+HEADROOM_OPENCODE_PLUGIN = "headroom-opencode"
+
+
+def _opencode_home_dir() -> Path:
+ """Return the OpenCode home/config directory."""
+ env_path = os.environ.get("OPENCODE_HOME", "").strip()
+ if env_path:
+ return Path(env_path).expanduser()
+ return Path.home() / ".config" / "opencode"
+
+
+def opencode_config_paths() -> tuple[Path, Path]:
+ """Return ``(config_file, backup_file)`` for OpenCode."""
+ config_file = opencode_config_path()
+ backup_file = config_file.with_suffix(".json.headroom-backup")
+ return config_file, backup_file
+
+
+def snapshot_opencode_config_if_unwrapped(config_file: Path, backup_file: Path) -> None:
+ """Snapshot ``opencode.json`` to ``backup_file`` before the first injection.
+
+ Guarantees that ``headroom unwrap opencode`` can restore the user's
+ original file byte-for-byte.
+ """
+ if backup_file.exists():
+ return
+ if not config_file.exists():
+ return
+ try:
+ content = config_file.read_text()
+ except OSError:
+ return
+ if _PROVIDER_MARKER_START in content or _MCP_MARKER_START in content:
+ return
+ backup_file.parent.mkdir(parents=True, exist_ok=True)
+ shutil.copy2(config_file, backup_file)
+
+
+def strip_opencode_headroom_blocks(content: str, *, remove_mcp: bool = True) -> str:
+ """Remove all Headroom-managed blocks from opencode JSON text.
+
+ Preserves user content. Returns the cleaned string.
+ """
+ content = _PROVIDER_BLOCK_RE.sub("", content)
+ if remove_mcp:
+ content = _MCP_BLOCK_RE.sub("", content)
+ # Collapse multiple blank lines left behind by block removal.
+ content = re.sub(r"\n{3,}", "\n\n", content)
+ return content.strip()
+
+
+def _render_provider_block(port: int) -> str:
+ """Render a Headroom provider block as a JSON comment-wrapped snippet."""
+ provider = {
+ "headroom": {
+ "npm": "@ai-sdk/openai-compatible",
+ "name": "Headroom Proxy",
+ "options": {"baseURL": f"http://127.0.0.1:{port}/v1"},
+ }
+ }
+ lines = [
+ _PROVIDER_MARKER_START,
+ f'"provider": {json.dumps(provider, indent=2)},',
+ _PROVIDER_MARKER_END,
+ ]
+ return "\n".join(lines)
+
+
+def _render_mcp_block(port: int) -> str:
+ """Render a Headroom MCP block as a JSON comment-wrapped snippet."""
+ mcp = {
+ "headroom": {
+ "type": "remote",
+ "url": f"http://127.0.0.1:{port}/mcp",
+ "enabled": True,
+ }
+ }
+ lines = [
+ _MCP_MARKER_START,
+ f'"mcp": {json.dumps(mcp, indent=2)},',
+ _MCP_MARKER_END,
+ ]
+ return "\n".join(lines)
+
+
+def _parse_json_loose(text: str) -> dict[str, Any]:
+ """Parse JSON text, stripping line comments (// ...) when needed.
+
+ Tries standard JSON first to avoid corrupting URLs that contain ``//``.
+ Falls back to stripping ``//`` comments when standard parsing fails.
+ Two-pass: (1) remove comment-only lines, (2) strip inline trailing
+ comments that follow a comma.
+ """
+ try:
+ return json.loads(text)
+ except json.JSONDecodeError:
+ pass
+ # Pass 1: remove lines that are ONLY a comment.
+ cleaned = re.sub(r"^\s*//[^\n]*\n", "", text, flags=re.MULTILINE)
+ # Pass 2: remove inline trailing comments (", // comment").
+ cleaned = re.sub(r",\s*//[^\n]*", ",", cleaned)
+ try:
+ return json.loads(cleaned)
+ except json.JSONDecodeError:
+ return {}
+
+
+def _inject_key_into_json(
+ data: dict[str, Any], key: str, value: Any
+) -> dict[str, Any]:
+ """Merge ``value`` into ``data[key]`` idempotently."""
+ existing = data.get(key)
+ if isinstance(existing, dict) and isinstance(value, dict):
+ merged = {**existing, **value}
+ data[key] = merged
+ else:
+ data[key] = value
+ return data
+
+
+def append_headroom_plugin(config: dict[str, object]) -> bool:
+ """Append the optional OpenCode plugin entry if it is not already present."""
+ plugin = config.get("plugin")
+ if plugin is None:
+ config["plugin"] = [HEADROOM_OPENCODE_PLUGIN]
+ return True
+
+ if not isinstance(plugin, list):
+ return False
+
+ for entry in plugin:
+ if entry == HEADROOM_OPENCODE_PLUGIN:
+ return False
+ if isinstance(entry, list) and entry and entry[0] == HEADROOM_OPENCODE_PLUGIN:
+ return False
+
+ plugin.append(HEADROOM_OPENCODE_PLUGIN)
+ return True
+
+
+def inject_opencode_provider_config(port: int) -> None:
+ """Inject a Headroom model provider into OpenCode's config file.
+
+ Safe to call multiple times — the injected block is fully replaced on
+ each call, so re-running with a different ``port`` updates the config.
+ Before the first injection, the pre-wrap file is snapshotted to
+ ``opencode.json.headroom-backup`` so ``headroom unwrap opencode``
+ can restore it byte-for-byte.
+ """
+ config_file, backup_file = opencode_config_paths()
+ config_dir = config_file.parent
+
+ try:
+ config_dir.mkdir(parents=True, exist_ok=True)
+ snapshot_opencode_config_if_unwrapped(config_file, backup_file)
+
+ if config_file.exists():
+ content = config_file.read_text()
+ data = _parse_json_loose(content)
+ else:
+ content = ""
+ data = {}
+
+ # Strip any prior Headroom-managed blocks before re-injecting.
+ if _PROVIDER_MARKER_START in content:
+ content = strip_opencode_headroom_blocks(content)
+ data = _parse_json_loose(content)
+
+ # Merge provider into the JSON data structure.
+ provider = {
+ "headroom": {
+ "npm": "@ai-sdk/openai-compatible",
+ "name": "Headroom Proxy",
+ "options": {"baseURL": f"http://127.0.0.1:{port}/v1"},
+ }
+ }
+ data = _inject_key_into_json(data, "provider", provider)
+
+ # Inject MCP if not already present.
+ mcp = {
+ "headroom": {
+ "type": "remote",
+ "url": f"http://127.0.0.1:{port}/mcp",
+ "enabled": True,
+ }
+ }
+ data = _inject_key_into_json(data, "mcp", mcp)
+
+ # Write back as formatted JSON (opencode uses standard JSON with comments).
+ output = json.dumps(data, indent=2) + "\n"
+ config_file.write_text(output, encoding="utf-8")
+ except OSError as exc:
+ raise click.ClickException(
+ f"could not write OpenCode config at {config_file}: {exc}"
+ ) from exc
diff --git a/headroom/providers/opencode/install.py b/headroom/providers/opencode/install.py
new file mode 100644
index 000000000..1209bc27a
--- /dev/null
+++ b/headroom/providers/opencode/install.py
@@ -0,0 +1,88 @@
+"""OpenCode install-time helpers."""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+
+from headroom.install.models import ConfigScope, DeploymentManifest, ManagedMutation, ToolTarget
+from headroom.install.paths import opencode_config_path
+
+from .config import (
+ _inject_key_into_json,
+ _parse_json_loose,
+ snapshot_opencode_config_if_unwrapped,
+ strip_opencode_headroom_blocks,
+)
+from .runtime import proxy_base_url
+
+
+def build_install_env(*, port: int, backend: str) -> dict[str, str]:
+ """Build the persistent install environment for OpenCode."""
+ del backend
+ del port
+ return {}
+
+
+def apply_provider_scope(manifest: DeploymentManifest) -> ManagedMutation | None:
+ """Apply OpenCode provider-scope configuration when requested."""
+ if manifest.scope != ConfigScope.PROVIDER.value:
+ return None
+
+ config_file = opencode_config_path()
+ config_file.parent.mkdir(parents=True, exist_ok=True)
+
+ snapshot_opencode_config_if_unwrapped(
+ config_file, config_file.with_suffix(".json.headroom-backup")
+ )
+
+ if config_file.exists():
+ content = config_file.read_text()
+ data = _parse_json_loose(content)
+ else:
+ data = {}
+
+ provider = {
+ "headroom": {
+ "npm": "@ai-sdk/openai-compatible",
+ "name": "Headroom Proxy",
+ "options": {"baseURL": proxy_base_url(manifest.port)},
+ }
+ }
+ data = _inject_key_into_json(data, "provider", provider)
+
+ config_file.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+ return ManagedMutation(
+ target=ToolTarget.OPENCODE.value,
+ kind="json-block",
+ path=str(config_file),
+ )
+
+
+def revert_provider_scope(mutation: ManagedMutation, manifest: DeploymentManifest) -> None:
+ """Revert OpenCode provider-scope configuration.
+
+ Restores from pre-wrap backup when available, otherwise strips the
+ headroom provider from the config file.
+ """
+ del manifest
+ if not mutation.path:
+ return
+ path = Path(mutation.path)
+ backup_file = path.with_suffix(".json.headroom-backup")
+ if backup_file.exists():
+ try:
+ shutil.copy2(backup_file, path)
+ backup_file.unlink()
+ return
+ except OSError:
+ pass
+ if not path.exists():
+ return
+ content = path.read_text()
+ cleaned = strip_opencode_headroom_blocks(content)
+ if cleaned:
+ path.write_text(cleaned + "\n", encoding="utf-8")
+ else:
+ path.unlink(missing_ok=True)
diff --git a/headroom/providers/opencode/runtime.py b/headroom/providers/opencode/runtime.py
new file mode 100644
index 000000000..75bd0fd87
--- /dev/null
+++ b/headroom/providers/opencode/runtime.py
@@ -0,0 +1,81 @@
+"""Runtime helpers for OpenCode integrations."""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Mapping
+
+from .config import HEADROOM_OPENCODE_PLUGIN
+
+
+def proxy_base_url(port: int) -> str:
+ """Return the local proxy base URL used by OpenCode integrations."""
+ return f"http://127.0.0.1:{port}/v1"
+
+
+def build_opencode_config_content(
+ *,
+ port: int,
+ include_mcp: bool = True,
+ include_plugin: bool = True,
+) -> dict[str, object]:
+ """Build JSON payload for ``OPENCODE_CONFIG_CONTENT``.
+
+ Runtime wrap injects the Headroom provider as a stable explicit fallback,
+ plus the Headroom plugin which transparently routes provider fetch traffic
+ through the local proxy without rewriting user provider config URLs.
+ """
+ base_url = proxy_base_url(port)
+ config: dict[str, object] = {
+ "provider": {
+ "headroom": {
+ "npm": "@ai-sdk/openai-compatible",
+ "name": "Headroom Proxy",
+ "options": {"baseURL": base_url},
+ }
+ }
+ }
+ if include_mcp:
+ config["mcp"] = {
+ "headroom": {
+ "type": "remote",
+ "url": f"http://127.0.0.1:{port}/mcp",
+ "enabled": True,
+ }
+ }
+ if include_plugin:
+ config["plugin"] = [[HEADROOM_OPENCODE_PLUGIN, {"proxyUrl": base_url}]]
+ return config
+
+
+def build_launch_env(
+ port: int,
+ environ: Mapping[str, str] | None = None,
+ project: str | None = None,
+ *,
+ include_mcp: bool = True,
+ include_plugin: bool = True,
+) -> tuple[dict[str, str], list[str]]:
+ """Build environment variables for launching OpenCode through Headroom.
+
+ ``OPENCODE_CONFIG_CONTENT`` carries Headroom provider/MCP/plugin config.
+ Existing provider/base URL environment variables are preserved.
+ """
+ env = dict(environ or os.environ)
+
+ config_content = build_opencode_config_content(
+ port=port,
+ include_mcp=include_mcp,
+ include_plugin=include_plugin,
+ )
+ env["OPENCODE_CONFIG_CONTENT"] = json.dumps(config_content, separators=(",", ":"))
+
+ display = ["OPENCODE_CONFIG_CONTENT={provider: headroom}"]
+ if include_plugin:
+ display.append(f"plugin={HEADROOM_OPENCODE_PLUGIN}")
+
+ if project and "HEADROOM_PROJECT" not in env:
+ env["HEADROOM_PROJECT"] = project
+
+ return env, display
diff --git a/headroom/release_version.py b/headroom/release_version.py
index cf99835c1..1a7899f03 100644
--- a/headroom/release_version.py
+++ b/headroom/release_version.py
@@ -283,9 +283,45 @@ def write_github_outputs(info: ReleaseVersionInfo, output_path: str) -> None:
def main() -> None:
root = Path.cwd()
manual_version = os.environ.get("MANUAL_VER", "").strip()
+ manual_match = re.fullmatch(r"v?(\d+\.\d+\.\d+(?:[abrc]\d+)?)", (os.environ.get("MANUAL_VER") or os.environ.get("LEVEL", "patch")).strip())
+ if manual_match:
+ version = manual_match.group(1)
+ info = ReleaseVersionInfo(
+ version=version,
+ npm_version=version,
+ canonical=get_canonical_version(root),
+ bump="manual",
+ height="0",
+ previous_tag="",
+ )
+ output_path = os.environ.get("GITHUB_OUTPUT")
+ if output_path:
+ write_github_outputs(info, output_path)
+ print(f"version={info.version}")
+ print(f"npm_version={info.npm_version}")
+ print(f"height={info.height}")
+ return
tags = list_release_tags(root)
previous_tag = find_latest_release_tag(tags) or ""
level = os.environ.get("LEVEL", "").strip()
+ manual_match = re.fullmatch(r"v?(\d+\.\d+\.\d+(?:[abrc]\d+)?)", level.strip())
+ if manual_match:
+ version = manual_match.group(1)
+ info = ReleaseVersionInfo(
+ version=version,
+ npm_version=version,
+ canonical=get_canonical_version(root),
+ bump="manual",
+ height="0",
+ previous_tag="",
+ )
+ output_path = os.environ.get("GITHUB_OUTPUT")
+ if output_path:
+ write_github_outputs(info, output_path)
+ print(f"version={info.version}")
+ print(f"npm_version={info.npm_version}")
+ print(f"height={info.height}")
+ return
if not level:
level = determine_bump_level(list_release_commits(root, previous_tag))
diff --git a/headroom/telemetry/context.py b/headroom/telemetry/context.py
index f3494a2b8..1e3c9ae0e 100644
--- a/headroom/telemetry/context.py
+++ b/headroom/telemetry/context.py
@@ -21,7 +21,7 @@ from typing import Any
logger = logging.getLogger(__name__)
-_KNOWN_WRAP_AGENTS = frozenset({"claude", "copilot", "codex", "aider", "cursor", "openclaw"})
+_KNOWN_WRAP_AGENTS = frozenset({"claude", "copilot", "codex", "aider", "cursor", "openclaw", "opencode"})
# Stack slugs must start with a letter and contain only [a-z0-9_], max 64 chars.
# Applied at every ingress (env var, HTTP header, stats aggregation) so downstream
diff --git a/plugins/opencode/.gitignore b/plugins/opencode/.gitignore
new file mode 100644
index 000000000..d4d7e3f61
--- /dev/null
+++ b/plugins/opencode/.gitignore
@@ -0,0 +1,3 @@
+node_modules
+dist
+*.log
diff --git a/plugins/opencode/README.md b/plugins/opencode/README.md
new file mode 100644
index 000000000..4049db141
--- /dev/null
+++ b/plugins/opencode/README.md
@@ -0,0 +1,127 @@
+# headroom-opencode
+
+Headroom proxy integration for [OpenCode](https://opencode.ai). Routes LLM traffic through the Headroom proxy for token compression, provides CCR retrieval, and handles provider configuration.
+
+## Install
+
+```bash
+npm install headroom-opencode
+```
+
+## Quick start
+
+### Create a Headroom provider for opencode.json
+
+```ts
+import { createHeadroomProvider } from "headroom-opencode";
+
+const provider = createHeadroomProvider({
+ proxyPort: 8787,
+});
+
+// Write to opencode.json:
+// {
+// "provider": { "headroom": provider },
+// "model": "headroom/claude-sonnet-4-6"
+// }
+```
+
+### Build OPENCODE_CONFIG_CONTENT
+
+```ts
+import { buildOpencodeConfigContentJson } from "headroom-opencode";
+
+const json = buildOpencodeConfigContentJson({
+ proxyPort: 8787,
+ defaultModel: "claude-sonnet-4-6",
+});
+
+// Set as env var: process.env.OPENCODE_CONFIG_CONTENT = json;
+```
+
+### Compress messages through the proxy
+
+```ts
+import { compressWithHeadroom } from "headroom-opencode";
+
+const result = await compressWithHeadroom(messages, {
+ model: "gpt-4o",
+ proxyUrl: "http://localhost:8787",
+});
+
+console.log(`Saved ${result.tokensSaved} tokens`);
+```
+
+### CCR retrieve tool
+
+```ts
+import { createHeadroomRetrieveTool } from "headroom-opencode";
+
+const retrieveTool = createHeadroomRetrieveTool({
+ proxyBaseUrl: "http://localhost:8787",
+});
+
+// Register in OpenCode's MCP config under mcp.headroom_retrieve
+```
+
+## API
+
+### `createHeadroomProvider(options?)`
+
+Creates a provider object compatible with OpenCode's `@ai-sdk/openai-compatible` format.
+
+| Option | Default | Description |
+|---|---|---|
+| `proxyBaseUrl` | `http://127.0.0.1:8787` | Full proxy base URL |
+| `proxyPort` | `8787` | Proxy port (ignored if proxyBaseUrl is set) |
+| `models` | See below | Custom model mappings |
+| `defaultModel` | `claude-sonnet-4-6` | Default model ID |
+
+### `buildOpencodeConfigContent(options?)`
+
+Returns a full `OPENCODE_CONFIG_CONTENT` JSON object with provider and model.
+
+### `buildOpencodeConfigContentJson(options?)`
+
+Same as above but returns a JSON string ready for the `OPENCODE_CONFIG_CONTENT` env var.
+
+### `compressWithHeadroom(messages, options?)`
+
+Compresses an array of messages through the Headroom proxy. Returns compression stats and compressed messages.
+
+### `createHeadroomRetrieveTool(config)`
+
+Creates a CCR retrieve tool for OpenCode's MCP system.
+
+### `setDefaultProxyUrl(url)` / `getDefaultProxyUrl()`
+
+Set or get the default proxy URL for all operations. Defaults to `HEADROOM_BASE_URL` env var or `http://localhost:8787`.
+
+## Default models
+
+| Model ID | Context | Output |
+|---|---|---|
+| `claude-sonnet-4-6` | 200K | 16K |
+| `claude-opus-4-6` | 200K | 16K |
+| `claude-haiku-4-5-20251001` | 200K | 8K |
+| `gpt-4o` | 128K | 16K |
+| `gpt-4.1` | 1M | 32K |
+
+## OpenCode plugin
+
+The package default export is an OpenCode plugin. It adds a `headroom_retrieve`
+tool and Headroom metadata for shell commands:
+
+```json
+{
+ "plugin": [["headroom-opencode", { "proxyUrl": "http://127.0.0.1:8787" }]]
+}
+```
+
+The plugin does not set `OPENAI_BASE_URL` or `ANTHROPIC_BASE_URL`. Model traffic
+is routed by the `headroom` provider config generated by
+`buildOpencodeConfigContent` or `headroom wrap opencode`.
+
+## License
+
+Apache-2.0
diff --git a/plugins/opencode/hook-shim/handler.js b/plugins/opencode/hook-shim/handler.js
new file mode 100644
index 000000000..1419e1132
--- /dev/null
+++ b/plugins/opencode/hook-shim/handler.js
@@ -0,0 +1,8 @@
+import { installHeadroomTransport } from "../dist/index.js";
+
+const proxyUrl = process.env.HEADROOM_OPENCODE_TRANSPORT_PROXY_URL;
+if (!proxyUrl) {
+ throw new Error("Headroom OpenCode transport shim loaded without HEADROOM_OPENCODE_TRANSPORT_PROXY_URL");
+}
+
+installHeadroomTransport({ proxyUrl });
diff --git a/plugins/opencode/package.json b/plugins/opencode/package.json
new file mode 100644
index 000000000..323f882ad
--- /dev/null
+++ b/plugins/opencode/package.json
@@ -0,0 +1,46 @@
+{
+ "name": "headroom-opencode",
+ "version": "0.1.0",
+ "description": "Headroom proxy integration plugin for OpenCode - routes LLM traffic through the Headroom proxy for token compression",
+ "type": "module",
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "files": [
+ "dist",
+ "hook-shim",
+ "README.md"
+ ],
+ "scripts": {
+ "build": "tsup",
+ "test": "vitest run",
+ "test:watch": "vitest",
+ "typecheck": "tsc --noEmit"
+ },
+ "dependencies": {
+ "@opencode-ai/plugin": "^1.17.8",
+ "headroom-ai": "^0.22.3"
+ },
+ "peerDependencies": {
+ "@ai-sdk/openai-compatible": "*",
+ "@ai-sdk/provider": "*",
+ "ai": "*"
+ },
+ "peerDependenciesMeta": {
+ "@ai-sdk/openai-compatible": {
+ "optional": true
+ },
+ "@ai-sdk/provider": {
+ "optional": true
+ },
+ "ai": {
+ "optional": true
+ }
+ },
+ "devDependencies": {
+ "@types/node": "^22.10.0",
+ "tsup": "^8.0.0",
+ "typescript": "^5.5.0",
+ "vitest": "^4.1.5"
+ },
+ "license": "Apache-2.0"
+}
diff --git a/plugins/opencode/src/index.ts b/plugins/opencode/src/index.ts
new file mode 100644
index 000000000..30112a7ba
--- /dev/null
+++ b/plugins/opencode/src/index.ts
@@ -0,0 +1,23 @@
+export {
+ DEFAULT_MODEL,
+ DEFAULT_MODELS,
+ buildOpencodeConfigContent,
+ buildOpencodeConfigContentJson,
+ createHeadroomProvider,
+} from "./provider.js";
+export type {
+ HeadroomModelMapping,
+ HeadroomProvider,
+ HeadroomProviderOptions,
+} from "./provider.js";
+export {
+ compressWithHeadroom,
+ createHeadroomRetrieveTool,
+ getDefaultProxyUrl,
+ setDefaultProxyUrl,
+} from "./retrieve.js";
+export type { RetrieveToolConfig } from "./retrieve.js";
+export { HeadroomPlugin, default } from "./plugin.js";
+export type { HeadroomOpenCodePluginOptions } from "./plugin.js";
+
+export { installHeadroomTransport } from "./transport.js";
diff --git a/plugins/opencode/src/plugin.test.ts b/plugins/opencode/src/plugin.test.ts
new file mode 100644
index 000000000..b5323205c
--- /dev/null
+++ b/plugins/opencode/src/plugin.test.ts
@@ -0,0 +1,68 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { HeadroomPlugin } from "./plugin.js";
+
+function pluginInput() {
+ return {
+ client: {},
+ project: { id: "project-1" },
+ directory: "/repo",
+ worktree: "/repo",
+ experimental_workspace: {
+ register: vi.fn(),
+ },
+ $: {},
+ } as never;
+}
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+describe("HeadroomPlugin", () => {
+ it("adds only Headroom metadata to shell env", async () => {
+ const plugin = await HeadroomPlugin(pluginInput(), {
+ proxyUrl: "http://127.0.0.1:8787/",
+ backend: "litellm",
+ });
+ const output = {
+ env: {
+ OPENAI_BASE_URL: "https://deepseek.example/v1",
+ ANTHROPIC_BASE_URL: "https://anthropic.example",
+ },
+ };
+
+ await plugin["shell.env"]?.({ cwd: "/repo" }, output);
+
+ expect(output.env).toMatchObject({
+ HEADROOM_ACTIVE: "1",
+ HEADROOM_PROXY_URL: "http://127.0.0.1:8787",
+ HEADROOM_PROJECT: "project-1",
+ HEADROOM_BACKEND: "litellm",
+ OPENAI_BASE_URL: "https://deepseek.example/v1",
+ ANTHROPIC_BASE_URL: "https://anthropic.example",
+ });
+ });
+
+ it("exposes a headroom_retrieve tool backed by the proxy", async () => {
+ const fetchMock = vi.fn(async () => ({
+ ok: true,
+ json: async () => "original content",
+ }));
+ vi.stubGlobal("fetch", fetchMock);
+
+ const plugin = await HeadroomPlugin(pluginInput(), {
+ proxyUrl: "http://127.0.0.1:8787",
+ });
+ const result = await plugin.tool?.headroom_retrieve.execute(
+ { hash: "0123456789abcdef01234567", query: "needle" },
+ {} as never,
+ );
+
+ expect(result).toBe("original content");
+ expect(fetchMock).toHaveBeenCalledWith(
+ "http://127.0.0.1:8787/v1/retrieve/0123456789abcdef01234567?query=needle",
+ expect.any(Object),
+ );
+ });
+});
diff --git a/plugins/opencode/src/plugin.ts b/plugins/opencode/src/plugin.ts
new file mode 100644
index 000000000..9c7499a19
--- /dev/null
+++ b/plugins/opencode/src/plugin.ts
@@ -0,0 +1,69 @@
+import type { Plugin } from "@opencode-ai/plugin";
+import { tool } from "@opencode-ai/plugin";
+import { z } from "zod";
+
+import { createHeadroomRetrieveTool, getDefaultProxyUrl } from "./retrieve.js";
+import { installHeadroomTransport } from "./transport.js";
+
+export interface HeadroomOpenCodePluginOptions {
+ proxyUrl?: string;
+ project?: string;
+ backend?: string;
+ debug?: boolean;
+}
+
+function normalizeProxyUrl(url: string): string {
+ return url.replace(/\/+$/, "");
+}
+
+function resolveProxyUrl(options?: HeadroomOpenCodePluginOptions): string {
+ return normalizeProxyUrl(
+ options?.proxyUrl ??
+ process.env.HEADROOM_PROXY_URL ??
+ process.env.HEADROOM_BASE_URL ??
+ getDefaultProxyUrl(),
+ );
+}
+
+export const HeadroomPlugin: Plugin = async (input, options = {}) => {
+ const pluginOptions = options as HeadroomOpenCodePluginOptions;
+ const proxyUrl = resolveProxyUrl(pluginOptions);
+ const retrieveTool = createHeadroomRetrieveTool({ proxyBaseUrl: proxyUrl });
+ const uninstallTransport = installHeadroomTransport({
+ proxyUrl,
+ debug: pluginOptions.debug,
+ });
+
+ return {
+ dispose: async () => {
+ uninstallTransport();
+ },
+ tool: {
+ headroom_retrieve: tool({
+ description: retrieveTool.description,
+ args: {
+ hash: z
+ .string()
+ .regex(/^[a-f0-9]{24}$/i, "Expected 24-character hex hash"),
+ query: z.string().optional(),
+ },
+ async execute(args) {
+ return retrieveTool.execute(args);
+ },
+ }),
+ },
+ "shell.env": async (_input, output) => {
+ output.env.HEADROOM_ACTIVE = "1";
+ output.env.HEADROOM_PROXY_URL = proxyUrl;
+ output.env.HEADROOM_PROJECT =
+ pluginOptions.project ??
+ (input.project as { id?: string }).id ??
+ input.directory;
+ if (pluginOptions.backend) {
+ output.env.HEADROOM_BACKEND = pluginOptions.backend;
+ }
+ },
+ };
+};
+
+export default HeadroomPlugin;
diff --git a/plugins/opencode/src/provider.ts b/plugins/opencode/src/provider.ts
new file mode 100644
index 000000000..0dc50e37b
--- /dev/null
+++ b/plugins/opencode/src/provider.ts
@@ -0,0 +1,92 @@
+export interface HeadroomModelMapping {
+ name: string;
+ limit: {
+ context: number;
+ output: number;
+ };
+}
+
+export interface HeadroomProviderOptions {
+ proxyBaseUrl?: string;
+ proxyPort?: number;
+ defaultModel?: string;
+ models?: Record<string, HeadroomModelMapping>;
+}
+
+export const DEFAULT_MODELS: Record<string, HeadroomModelMapping> = {
+ "claude-sonnet-4-6": {
+ name: "Claude Sonnet 4.6",
+ limit: { context: 200000, output: 16384 },
+ },
+ "claude-opus-4-6": {
+ name: "Claude Opus 4.6",
+ limit: { context: 200000, output: 16384 },
+ },
+ "claude-haiku-4-5-20251001": {
+ name: "Claude Haiku 4.5",
+ limit: { context: 200000, output: 8192 },
+ },
+ "gpt-4o": {
+ name: "GPT-4o",
+ limit: { context: 128000, output: 16384 },
+ },
+ "gpt-4.1": {
+ name: "GPT-4.1",
+ limit: { context: 1048576, output: 32768 },
+ },
+};
+
+export const DEFAULT_MODEL = "claude-sonnet-4-6";
+
+function resolveBaseUrl(options: HeadroomProviderOptions): string {
+ if (options.proxyBaseUrl) return options.proxyBaseUrl.replace(/\/+$/, "");
+ const port = options.proxyPort ?? 8787;
+ return `http://127.0.0.1:${port}`;
+}
+
+export interface HeadroomProvider {
+ npm: string;
+ name: string;
+ options: {
+ baseURL: string;
+ apiKey?: string;
+ };
+ models: Record<string, HeadroomModelMapping>;
+}
+
+export function createHeadroomProvider(
+ options: HeadroomProviderOptions = {},
+): HeadroomProvider {
+ const baseUrl = resolveBaseUrl(options);
+ const models = options.models ?? DEFAULT_MODELS;
+
+ return {
+ npm: "@ai-sdk/openai-compatible",
+ name: "Headroom Proxy",
+ options: { baseURL: `${baseUrl}/v1` },
+ models: Object.fromEntries(
+ Object.entries(models).map(([id, mapping]) => [
+ `headroom/${id}`,
+ mapping,
+ ]),
+ ),
+ };
+}
+
+export function buildOpencodeConfigContent(
+ options: HeadroomProviderOptions = {},
+): Record<string, unknown> {
+ const defaultModel = options.defaultModel ?? DEFAULT_MODEL;
+ const provider = createHeadroomProvider(options);
+
+ return {
+ provider: { headroom: provider },
+ model: `headroom/${defaultModel}`,
+ };
+}
+
+export function buildOpencodeConfigContentJson(
+ options: HeadroomProviderOptions = {},
+): string {
+ return JSON.stringify(buildOpencodeConfigContent(options));
+}
diff --git a/plugins/opencode/src/retrieve.ts b/plugins/opencode/src/retrieve.ts
new file mode 100644
index 000000000..d5587f3b0
--- /dev/null
+++ b/plugins/opencode/src/retrieve.ts
@@ -0,0 +1,94 @@
+import type { CompressResult } from "headroom-ai";
+import { compress } from "headroom-ai";
+
+let _proxyUrlCache: string | null = null;
+
+export function setDefaultProxyUrl(url: string): void {
+ _proxyUrlCache = url;
+}
+
+export function getDefaultProxyUrl(): string {
+ return _proxyUrlCache ?? process.env.HEADROOM_BASE_URL ?? "http://localhost:8787";
+}
+
+export interface RetrieveToolConfig {
+ proxyBaseUrl: string;
+}
+
+export function createHeadroomRetrieveTool(config: RetrieveToolConfig) {
+ const origin = config.proxyBaseUrl.replace(/\/+$/, "");
+
+ return {
+ name: "headroom_retrieve",
+ description:
+ "Retrieve original uncompressed content from Headroom's compression store. " +
+ "Use when compressed context mentions a hash and you need the full details. " +
+ "Pass the hash from the compression marker (24 hex characters). " +
+ "Optionally pass a query to search within the original content.",
+ parameters: {
+ type: "object" as const,
+ properties: {
+ hash: {
+ type: "string",
+ description: "The 24-character hex hash from the compression marker",
+ },
+ query: {
+ type: "string",
+ description: "Optional search query to filter results within the original content",
+ },
+ },
+ required: ["hash"],
+ },
+ execute: async (args: { hash: string; query?: string }): Promise<string> => {
+ const { hash, query } = args;
+
+ if (!/^[a-f0-9]{24}$/i.test(hash)) {
+ return JSON.stringify({
+ error: "Invalid hash format. Expected 24 hex characters.",
+ });
+ }
+
+ try {
+ const url = query
+ ? `${origin}/v1/retrieve/${hash}?query=${encodeURIComponent(query)}`
+ : `${origin}/v1/retrieve/${hash}`;
+
+ const resp = await fetch(url, {
+ signal: AbortSignal.timeout(10_000),
+ });
+
+ if (!resp.ok) {
+ const body = await resp.text().catch(() => "");
+ return JSON.stringify({
+ error: `Retrieval failed: HTTP ${resp.status}`,
+ details: body,
+ });
+ }
+
+ const data = await resp.json();
+ return typeof data === "string" ? data : JSON.stringify(data);
+ } catch (error) {
+ return JSON.stringify({
+ error: `Retrieval failed: ${error}`,
+ hint: "The compressed content may have expired (default TTL: 5 minutes)",
+ });
+ }
+ },
+ };
+}
+
+export async function compressWithHeadroom(
+ messages: unknown[],
+ options: {
+ model?: string;
+ tokenBudget?: number;
+ proxyUrl?: string;
+ } = {},
+): Promise<CompressResult> {
+ return compress(messages, {
+ baseUrl: options.proxyUrl ?? getDefaultProxyUrl(),
+ model: options.model ?? "gpt-4o",
+ tokenBudget: options.tokenBudget,
+ stack: "opencode",
+ });
+}
diff --git a/plugins/opencode/src/transport.test.ts b/plugins/opencode/src/transport.test.ts
new file mode 100644
index 000000000..709f88a05
--- /dev/null
+++ b/plugins/opencode/src/transport.test.ts
@@ -0,0 +1,215 @@
+import childProcess from "node:child_process";
+import http from "node:http";
+import http2 from "node:http2";
+import https from "node:https";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { installHeadroomTransport, uninstallHeadroomTransport } from "./transport.js";
+
+afterEach(() => {
+ uninstallHeadroomTransport();
+ vi.restoreAllMocks();
+});
+
+type FetchCall = [RequestInfo | URL, RequestInit?];
+
+type SeenRequest = {
+ method: string | undefined;
+ url: string | undefined;
+ headers: http.IncomingHttpHeaders;
+ body: string;
+};
+
+function proxyServer(): Promise<{ url: string; seen: SeenRequest[]; close: () => Promise<void> }> {
+ const seen: SeenRequest[] = [];
+ const server = http.createServer((req, res) => {
+ let body = "";
+ req.setEncoding("utf8");
+ req.on("data", (chunk) => {
+ body += chunk;
+ });
+ req.on("end", () => {
+ seen.push({ method: req.method, url: req.url, headers: req.headers, body });
+ res.writeHead(200, { "content-type": "application/json" });
+ res.end("{\"ok\":true}");
+ });
+ });
+
+ return new Promise((resolve, reject) => {
+ server.once("error", reject);
+ server.listen(0, "127.0.0.1", () => {
+ const address = server.address();
+ if (!address || typeof address === "string") {
+ reject(new Error("Expected TCP server address"));
+ return;
+ }
+ resolve({
+ url: `http://127.0.0.1:${address.port}/v1`,
+ seen,
+ close: () => new Promise((done) => server.close(() => done())),
+ });
+ });
+ });
+}
+
+describe("Headroom OpenCode transport", () => {
+ it("routes external fetch calls through the proxy without pre-registering providers", async () => {
+ const originalFetch = globalThis.fetch;
+ const fetchMock = vi.fn(async (..._args: FetchCall) => new Response("ok"));
+ globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+ installHeadroomTransport({ proxyUrl: "http://127.0.0.1:8787/v1" });
+
+ await fetch("https://api.deepseek.com/v1/chat/completions?x=1", {
+ method: "POST",
+ headers: { authorization: "Bearer test" },
+ });
+ await fetch("https://new-provider.example/base/v1/messages", { method: "POST" });
+
+ expect(fetchMock).toHaveBeenNthCalledWith(
+ 1,
+ new URL("http://127.0.0.1:8787/v1/chat/completions?x=1"),
+ expect.objectContaining({ method: "POST" }),
+ );
+ expect(new Headers(fetchMock.mock.calls[0][1]?.headers).get("x-headroom-base-url")).toBe(
+ "https://api.deepseek.com",
+ );
+ expect(fetchMock.mock.calls[1][0]).toEqual(new URL("http://127.0.0.1:8787/base/v1/messages"));
+ expect(new Headers(fetchMock.mock.calls[1][1]?.headers).get("x-headroom-base-url")).toBe(
+ "https://new-provider.example",
+ );
+
+ globalThis.fetch = originalFetch;
+ });
+
+ it("bypasses local, OpenCode, and Headroom proxy fetch URLs", async () => {
+ const originalFetch = globalThis.fetch;
+ const fetchMock = vi.fn(async (..._args: FetchCall) => new Response("ok"));
+ globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+ installHeadroomTransport({ proxyUrl: "http://127.0.0.1:8787/v1" });
+
+ await fetch("http://127.0.0.1:8787/v1/retrieve");
+ await fetch("http://localhost:4096/config");
+
+ expect(fetchMock.mock.calls[0][0]).toBe("http://127.0.0.1:8787/v1/retrieve");
+ expect(fetchMock.mock.calls[1][0]).toBe("http://localhost:4096/config");
+
+ globalThis.fetch = originalFetch;
+ });
+
+ it("routes external https.request calls through the proxy", async () => {
+ const proxy = await proxyServer();
+ installHeadroomTransport({ proxyUrl: proxy.url });
+
+ await new Promise<void>((resolve, reject) => {
+ const req = https.request(
+ "https://api.anthropic.com/v1/messages?beta=1",
+ { method: "POST", headers: { authorization: "Bearer test" } },
+ (res) => {
+ res.resume();
+ res.on("end", resolve);
+ },
+ );
+ req.on("error", reject);
+ req.end("{\"model\":\"claude\"}");
+ });
+
+ expect(proxy.seen).toHaveLength(1);
+ expect(proxy.seen[0]).toMatchObject({ method: "POST", url: "/v1/messages?beta=1" });
+ expect(proxy.seen[0].headers["x-headroom-base-url"]).toBe("https://api.anthropic.com");
+ expect(proxy.seen[0].headers.host).toMatch(/^127\.0\.0\.1:/);
+ expect(proxy.seen[0].body).toBe("{\"model\":\"claude\"}");
+
+ await proxy.close();
+ });
+
+ it("blocks external http2 connections instead of leaking them", () => {
+ installHeadroomTransport({ proxyUrl: "http://127.0.0.1:8787/v1" });
+
+ expect(() => http2.connect("https://api.openai.com")).toThrow(
+ /blocked direct HTTP\/2 connection to https:\/\/api\.openai\.com/,
+ );
+ });
+
+ it("preloads the Headroom shim into child Node processes", () => {
+ const originalNodeOptions = process.env.NODE_OPTIONS;
+ const originalProxyUrl = process.env.HEADROOM_OPENCODE_TRANSPORT_PROXY_URL;
+
+ try {
+ process.env.NODE_OPTIONS = "--trace-warnings";
+ delete process.env.HEADROOM_OPENCODE_TRANSPORT_PROXY_URL;
+
+ installHeadroomTransport({ proxyUrl: "http://127.0.0.1:8787/v1" });
+
+ expect(process.env.HEADROOM_OPENCODE_TRANSPORT_PROXY_URL).toBe("http://127.0.0.1:8787/v1");
+ expect(process.env.NODE_OPTIONS).toContain("--trace-warnings");
+ expect(process.env.NODE_OPTIONS).toContain("--import=file:");
+ expect(process.env.NODE_OPTIONS).toContain("/hook-shim/handler.js");
+
+ installHeadroomTransport({ proxyUrl: "http://127.0.0.1:8787/v1" });
+ expect(process.env.NODE_OPTIONS?.match(/hook-shim\/handler\.js/g)).toHaveLength(1);
+ } finally {
+ if (originalNodeOptions === undefined) {
+ delete process.env.NODE_OPTIONS;
+ } else {
+ process.env.NODE_OPTIONS = originalNodeOptions;
+ }
+ if (originalProxyUrl === undefined) {
+ delete process.env.HEADROOM_OPENCODE_TRANSPORT_PROXY_URL;
+ } else {
+ process.env.HEADROOM_OPENCODE_TRANSPORT_PROXY_URL = originalProxyUrl;
+ }
+ uninstallHeadroomTransport();
+ }
+ });
+
+ it("injects the Headroom shim into child processes with custom env", () => {
+ const originalSpawn = childProcess.spawn;
+ const spawnMock = vi.fn(() => ({
+ on: vi.fn(),
+ once: vi.fn(),
+ emit: vi.fn(),
+ kill: vi.fn(),
+ killed: false,
+ pid: 123,
+ }));
+ childProcess.spawn = spawnMock as unknown as typeof childProcess.spawn;
+
+ try {
+ installHeadroomTransport({ proxyUrl: "http://127.0.0.1:8787/v1" });
+ childProcess.spawn("node", ["agent.js"], { env: { PATH: "/bin", NODE_OPTIONS: "--trace-warnings" } });
+
+ const options = (spawnMock.mock.calls[0] as unknown[])[2] as { env: NodeJS.ProcessEnv };
+ expect(options.env.PATH).toBe("/bin");
+ expect(options.env.HEADROOM_OPENCODE_TRANSPORT_PROXY_URL).toBe("http://127.0.0.1:8787/v1");
+ expect(options.env.NODE_OPTIONS).toContain("--trace-warnings");
+ expect(options.env.NODE_OPTIONS).toContain("--import=file:");
+ expect(options.env.NODE_OPTIONS).toContain("/hook-shim/handler.js");
+ } finally {
+ uninstallHeadroomTransport();
+ childProcess.spawn = originalSpawn;
+ }
+ });
+
+ it("restores patched transports only after the final disposer", () => {
+ const originalFetch = globalThis.fetch;
+ const originalHttpRequest = http.request;
+ const originalHttpsRequest = https.request;
+ const firstDispose = installHeadroomTransport({ proxyUrl: "http://127.0.0.1:8787/v1" });
+ const secondDispose = installHeadroomTransport({ proxyUrl: "http://127.0.0.1:8788/v1" });
+
+ expect(globalThis.fetch).not.toBe(originalFetch);
+ expect(http.request).not.toBe(originalHttpRequest);
+ expect(https.request).not.toBe(originalHttpsRequest);
+
+ firstDispose();
+ expect(globalThis.fetch).not.toBe(originalFetch);
+ expect(http.request).not.toBe(originalHttpRequest);
+
+ secondDispose();
+ expect(globalThis.fetch).toBe(originalFetch);
+ expect(http.request).toBe(originalHttpRequest);
+ expect(https.request).toBe(originalHttpsRequest);
+ });
+});
diff --git a/plugins/opencode/src/transport.ts b/plugins/opencode/src/transport.ts
new file mode 100644
index 000000000..5ca012cb8
--- /dev/null
+++ b/plugins/opencode/src/transport.ts
@@ -0,0 +1,438 @@
+import { createRequire, syncBuiltinESMExports } from "node:module";
+
+const nodeRequire = createRequire(import.meta.url);
+const http = nodeRequire("node:http") as typeof import("node:http");
+const https = nodeRequire("node:https") as typeof import("node:https");
+const http2 = nodeRequire("node:http2") as typeof import("node:http2");
+const childProcess = nodeRequire("node:child_process") as typeof import("node:child_process");
+
+const BASE_URL_HEADER = "x-headroom-base-url";
+const PROXY_ENV = "HEADROOM_OPENCODE_TRANSPORT_PROXY_URL";
+const STATE_KEY = Symbol.for("headroom.opencode.transport");
+
+type FetchArgs = Parameters<typeof fetch>;
+type HttpRequest = typeof http.request;
+type HttpGet = typeof http.get;
+type HttpsRequest = typeof https.request;
+type HttpsGet = typeof https.get;
+type Http2Connect = typeof http2.connect;
+type ChildSpawn = typeof childProcess.spawn;
+type ChildExec = typeof childProcess.exec;
+type ChildExecFile = typeof childProcess.execFile;
+type ChildFork = typeof childProcess.fork;
+
+interface InstallOptions {
+ proxyUrl: string;
+ debug?: boolean;
+}
+
+interface TransportState {
+ refs: number;
+ proxyUrl: string;
+ debug: boolean;
+ originalFetch: typeof fetch;
+ originalHttpRequest: HttpRequest;
+ originalHttpGet: HttpGet;
+ originalHttpsRequest: HttpsRequest;
+ originalHttpsGet: HttpsGet;
+ originalHttp2Connect: Http2Connect;
+ originalChildSpawn: ChildSpawn;
+ originalChildExec: ChildExec;
+ originalChildExecFile: ChildExecFile;
+ originalChildFork: ChildFork;
+}
+
+interface GlobalWithHeadroomTransport {
+ [STATE_KEY]?: TransportState;
+}
+
+interface NodeRequestParts {
+ url?: URL;
+ options: Record<string, unknown>;
+ callback?: (...args: unknown[]) => unknown;
+}
+
+function getState(): TransportState | undefined {
+ return (globalThis as GlobalWithHeadroomTransport)[STATE_KEY];
+}
+
+function setState(state: TransportState | undefined): void {
+ (globalThis as GlobalWithHeadroomTransport)[STATE_KEY] = state;
+}
+
+function shimImportSpecifier(): string {
+ return new URL("../hook-shim/handler.js", import.meta.url).href;
+}
+
+function withNodeImportOption(existing: string | undefined, shim: string): string {
+ const parts = existing?.trim() ? existing.trim().split(/\s+/) : [];
+ const alreadyPresent = parts.some((part, index) => {
+ return part === `--import=${shim}` || (part === "--import" && parts[index + 1] === shim);
+ });
+ if (!alreadyPresent) {
+ parts.push(`--import=${shim}`);
+ }
+ return parts.join(" ");
+}
+
+function withShimEnv(env: NodeJS.ProcessEnv | Record<string, unknown> | undefined, proxyUrl: string): NodeJS.ProcessEnv {
+ const nextEnv = { ...(env ?? process.env) } as NodeJS.ProcessEnv;
+ nextEnv[PROXY_ENV] = proxyUrl;
+ nextEnv.NODE_OPTIONS = withNodeImportOption(nextEnv.NODE_OPTIONS, shimImportSpecifier());
+ return nextEnv;
+}
+
+function installProcessEnv(proxyUrl: string): void {
+ process.env[PROXY_ENV] = proxyUrl;
+ process.env.NODE_OPTIONS = withNodeImportOption(process.env.NODE_OPTIONS, shimImportSpecifier());
+}
+
+function isOptions(value: unknown): value is Record<string, unknown> {
+ return Boolean(value) && typeof value === "object" && !Array.isArray(value) && !(value instanceof URL);
+}
+
+function injectOptionsEnv(args: unknown[], optionIndex: number, proxyUrl: string): unknown[] {
+ const nextArgs = [...args];
+ const callback = typeof nextArgs.at(-1) === "function" ? nextArgs.pop() : undefined;
+ const existing = isOptions(nextArgs[optionIndex]) ? { ...(nextArgs[optionIndex] as Record<string, unknown>) } : {};
+ existing.env = withShimEnv(existing.env as NodeJS.ProcessEnv | undefined, proxyUrl);
+
+ if (isOptions(nextArgs[optionIndex])) {
+ nextArgs[optionIndex] = existing;
+ } else {
+ nextArgs.splice(optionIndex, 0, existing);
+ }
+
+ if (callback) {
+ nextArgs.push(callback);
+ }
+ return nextArgs;
+}
+
+function wrapSpawn(originalSpawn: ChildSpawn): ChildSpawn {
+ return function headroomSpawn(this: unknown, ...args: unknown[]) {
+ const state = getState();
+ if (!state) {
+ return Reflect.apply(originalSpawn, this, args);
+ }
+ const optionIndex = Array.isArray(args[1]) ? 2 : 1;
+ return Reflect.apply(originalSpawn, this, injectOptionsEnv(args, optionIndex, state.proxyUrl));
+ } as ChildSpawn;
+}
+
+function wrapExec(originalExec: ChildExec): ChildExec {
+ return function headroomExec(this: unknown, ...args: unknown[]) {
+ const state = getState();
+ if (!state) {
+ return Reflect.apply(originalExec, this, args);
+ }
+ return Reflect.apply(originalExec, this, injectOptionsEnv(args, 1, state.proxyUrl));
+ } as ChildExec;
+}
+
+function wrapExecFile(originalExecFile: ChildExecFile): ChildExecFile {
+ return function headroomExecFile(this: unknown, ...args: unknown[]) {
+ const state = getState();
+ if (!state) {
+ return Reflect.apply(originalExecFile, this, args);
+ }
+ const optionIndex = Array.isArray(args[1]) ? 2 : 1;
+ return Reflect.apply(originalExecFile, this, injectOptionsEnv(args, optionIndex, state.proxyUrl));
+ } as ChildExecFile;
+}
+
+function wrapFork(originalFork: ChildFork): ChildFork {
+ return function headroomFork(this: unknown, ...args: unknown[]) {
+ const state = getState();
+ if (!state) {
+ return Reflect.apply(originalFork, this, args);
+ }
+ const optionIndex = Array.isArray(args[1]) ? 2 : 1;
+ return Reflect.apply(originalFork, this, injectOptionsEnv(args, optionIndex, state.proxyUrl));
+ } as ChildFork;
+}
+
+function normalizeProxyUrl(proxyUrl: string): URL {
+ return new URL(proxyUrl);
+}
+
+function isLoopback(hostname: string): boolean {
+ const normalized = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+ return normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1";
+}
+
+function shouldRoute(url: URL, proxy: URL): boolean {
+ if (url.protocol !== "http:" && url.protocol !== "https:") {
+ return false;
+ }
+ if (isLoopback(url.hostname)) {
+ return false;
+ }
+ if (url.origin === proxy.origin) {
+ return false;
+ }
+ return true;
+}
+
+function routedUrl(upstream: URL, proxy: URL): URL {
+ return new URL(`${upstream.pathname}${upstream.search}`, proxy.origin);
+}
+
+function requestUrl(input: RequestInfo | URL): URL {
+ if (input instanceof Request) {
+ return new URL(input.url);
+ }
+ if (input instanceof URL) {
+ return input;
+ }
+ return new URL(String(input));
+}
+
+function mergeFetchHeaders(input: RequestInfo | URL, init?: RequestInit, upstream?: URL): Headers {
+ const headers = new Headers(input instanceof Request ? input.headers : undefined);
+ if (init?.headers) {
+ new Headers(init.headers).forEach((value, key) => headers.set(key, value));
+ }
+ if (upstream) {
+ headers.set(BASE_URL_HEADER, upstream.origin);
+ headers.delete("host");
+ }
+ return headers;
+}
+
+function withRoutedFetchInput(input: RequestInfo | URL, init: RequestInit | undefined, proxy: URL): FetchArgs {
+ const upstream = requestUrl(input);
+ if (!shouldRoute(upstream, proxy)) {
+ return [input, init];
+ }
+
+ const nextInit = {
+ ...init,
+ headers: mergeFetchHeaders(input, init, upstream),
+ };
+ const nextUrl = routedUrl(upstream, proxy);
+
+ if (input instanceof Request) {
+ return [new Request(nextUrl, input), nextInit];
+ }
+ return [nextUrl, nextInit];
+}
+
+function splitNodeArgs(args: unknown[]): NodeRequestParts {
+ const callback = typeof args.at(-1) === "function" ? (args.at(-1) as (...args: unknown[]) => unknown) : undefined;
+ const withoutCallback = callback ? args.slice(0, -1) : args;
+ const [first, second] = withoutCallback;
+ const options = typeof second === "object" && second !== null ? { ...(second as Record<string, unknown>) } : {};
+
+ if (first instanceof URL) {
+ return { url: first, options, callback };
+ }
+ if (typeof first === "string") {
+ try {
+ return { url: new URL(first), options, callback };
+ } catch {
+ return { options, callback };
+ }
+ }
+ if (typeof first === "object" && first !== null) {
+ const requestOptions = { ...(first as Record<string, unknown>), ...options };
+ return { url: urlFromRequestOptions(requestOptions), options: requestOptions, callback };
+ }
+ return { options, callback };
+}
+
+function urlFromRequestOptions(options: Record<string, unknown>): URL | undefined {
+ const protocol = String(options.protocol ?? "http:");
+ if (protocol !== "http:" && protocol !== "https:") {
+ return undefined;
+ }
+
+ const hostValue = options.hostname ?? options.host;
+ if (!hostValue) {
+ return undefined;
+ }
+
+ const hostname = String(hostValue).replace(/:\d+$/, "");
+ const port = options.port ? `:${String(options.port)}` : "";
+ const path = String(options.path ?? "/");
+ try {
+ return new URL(`${protocol}//${hostname}${port}${path}`);
+ } catch {
+ return undefined;
+ }
+}
+
+function headersForNodeRequest(options: Record<string, unknown>, upstream: URL): Record<string, string> {
+ const headers = new Headers(options.headers as HeadersInit | undefined);
+ headers.set(BASE_URL_HEADER, upstream.origin);
+ headers.delete("host");
+
+ const result: Record<string, string> = {};
+ headers.forEach((value, key) => {
+ result[key] = value;
+ });
+ return result;
+}
+
+function routedNodeOptions(parts: NodeRequestParts, proxy: URL): Record<string, unknown> | undefined {
+ if (!parts.url || !shouldRoute(parts.url, proxy)) {
+ return undefined;
+ }
+
+ const nextUrl = routedUrl(parts.url, proxy);
+ const {
+ agent: _agent,
+ auth: _auth,
+ createConnection: _createConnection,
+ defaultPort: _defaultPort,
+ family: _family,
+ headers: _headers,
+ host: _host,
+ hostname: _hostname,
+ href: _href,
+ lookup: _lookup,
+ path: _path,
+ pathname: _pathname,
+ port: _port,
+ protocol: _protocol,
+ search: _search,
+ servername: _servername,
+ setHost: _setHost,
+ ...rest
+ } = parts.options;
+
+ return {
+ ...rest,
+ protocol: nextUrl.protocol,
+ hostname: nextUrl.hostname,
+ port: nextUrl.port || undefined,
+ path: `${nextUrl.pathname}${nextUrl.search}`,
+ headers: headersForNodeRequest(parts.options, parts.url),
+ };
+}
+
+function wrapRequest(
+ originalHttpRequest: HttpRequest,
+ originalHttpsRequest: HttpsRequest,
+ originalRequest: HttpRequest | HttpsRequest,
+): HttpRequest | HttpsRequest {
+ return function headroomRequest(this: unknown, ...args: unknown[]) {
+ const state = getState();
+ if (!state) {
+ return Reflect.apply(originalRequest, this, args);
+ }
+
+ const proxy = normalizeProxyUrl(state.proxyUrl);
+ const parts = splitNodeArgs(args);
+ const nextOptions = routedNodeOptions(parts, proxy);
+ if (!nextOptions) {
+ return Reflect.apply(originalRequest, this, args);
+ }
+
+ const targetRequest = proxy.protocol === "https:" ? originalHttpsRequest : originalHttpRequest;
+ const nextArgs = parts.callback ? [nextOptions, parts.callback] : [nextOptions];
+ return Reflect.apply(targetRequest, this, nextArgs);
+ } as HttpRequest | HttpsRequest;
+}
+
+function wrapGet(request: HttpRequest | HttpsRequest): HttpGet | HttpsGet {
+ return function headroomGet(this: unknown, ...args: unknown[]) {
+ const req = Reflect.apply(request, this, args);
+ req.end();
+ return req;
+ } as HttpGet | HttpsGet;
+}
+
+function wrapHttp2Connect(originalConnect: Http2Connect): Http2Connect {
+ return function headroomHttp2Connect(this: unknown, authority: string | URL, ...args: unknown[]) {
+ const state = getState();
+ if (state) {
+ const proxy = normalizeProxyUrl(state.proxyUrl);
+ const upstream = authority instanceof URL ? authority : new URL(String(authority));
+ if (shouldRoute(upstream, proxy)) {
+ throw new Error(
+ `Headroom OpenCode wrap blocked direct HTTP/2 connection to ${upstream.origin}. ` +
+ "Use fetch, http, or https so traffic can be routed through Headroom.",
+ );
+ }
+ }
+ return Reflect.apply(originalConnect, this, [authority, ...args]);
+ } as Http2Connect;
+}
+
+export function installHeadroomTransport(options: InstallOptions): () => void {
+ const existing = getState();
+ if (existing) {
+ existing.refs += 1;
+ existing.proxyUrl = options.proxyUrl;
+ existing.debug = Boolean(options.debug);
+ installProcessEnv(options.proxyUrl);
+ return () => uninstallHeadroomTransport();
+ }
+
+ const state: TransportState = {
+ refs: 1,
+ proxyUrl: options.proxyUrl,
+ debug: Boolean(options.debug),
+ originalFetch: globalThis.fetch,
+ originalHttpRequest: http.request,
+ originalHttpGet: http.get,
+ originalHttpsRequest: https.request,
+ originalHttpsGet: https.get,
+ originalHttp2Connect: http2.connect,
+ originalChildSpawn: childProcess.spawn,
+ originalChildExec: childProcess.exec,
+ originalChildExecFile: childProcess.execFile,
+ originalChildFork: childProcess.fork,
+ };
+
+ setState(state);
+ installProcessEnv(options.proxyUrl);
+ globalThis.fetch = async (...args: FetchArgs) => {
+ const current = getState();
+ if (!current) {
+ return state.originalFetch(...args);
+ }
+ const proxy = normalizeProxyUrl(current.proxyUrl);
+ const [nextInput, nextInit] = withRoutedFetchInput(args[0], args[1], proxy);
+ return state.originalFetch(nextInput, nextInit);
+ };
+
+ http.request = wrapRequest(state.originalHttpRequest, state.originalHttpsRequest, state.originalHttpRequest) as HttpRequest;
+ https.request = wrapRequest(state.originalHttpRequest, state.originalHttpsRequest, state.originalHttpsRequest) as HttpsRequest;
+ http.get = wrapGet(http.request) as HttpGet;
+ https.get = wrapGet(https.request) as HttpsGet;
+ http2.connect = wrapHttp2Connect(state.originalHttp2Connect);
+ childProcess.spawn = wrapSpawn(state.originalChildSpawn);
+ childProcess.exec = wrapExec(state.originalChildExec);
+ childProcess.execFile = wrapExecFile(state.originalChildExecFile);
+ childProcess.fork = wrapFork(state.originalChildFork);
+ syncBuiltinESMExports();
+
+ return () => uninstallHeadroomTransport();
+}
+
+export function uninstallHeadroomTransport(): void {
+ const state = getState();
+ if (!state) {
+ return;
+ }
+
+ state.refs -= 1;
+ if (state.refs > 0) {
+ return;
+ }
+
+ globalThis.fetch = state.originalFetch;
+ http.request = state.originalHttpRequest;
+ http.get = state.originalHttpGet;
+ https.request = state.originalHttpsRequest;
+ https.get = state.originalHttpsGet;
+ http2.connect = state.originalHttp2Connect;
+ childProcess.spawn = state.originalChildSpawn;
+ childProcess.exec = state.originalChildExec;
+ childProcess.execFile = state.originalChildExecFile;
+ childProcess.fork = state.originalChildFork;
+ syncBuiltinESMExports();
+ setState(undefined);
+}
diff --git a/plugins/opencode/tsconfig.json b/plugins/opencode/tsconfig.json
new file mode 100644
index 000000000..c745b7b2d
--- /dev/null
+++ b/plugins/opencode/tsconfig.json
@@ -0,0 +1,19 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "ESNext",
+ "moduleResolution": "bundler",
+ "lib": ["ES2022", "DOM"],
+ "types": ["node"],
+ "strict": true,
+ "esModuleInterop": true,
+ "skipLibCheck": true,
+ "declaration": true,
+ "outDir": "dist",
+ "rootDir": "src",
+ "sourceMap": true,
+ "isolatedModules": true
+ },
+ "include": ["src"],
+ "exclude": ["node_modules", "dist", "test"]
+}
diff --git a/plugins/opencode/tsup.config.ts b/plugins/opencode/tsup.config.ts
new file mode 100644
index 000000000..fcae8cdc0
--- /dev/null
+++ b/plugins/opencode/tsup.config.ts
@@ -0,0 +1,10 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+ entry: { index: "src/index.ts" },
+ format: ["esm"],
+ dts: true,
+ sourcemap: true,
+ clean: true,
+ external: ["headroom-ai"],
+});
diff --git a/plugins/opencode/vitest.config.ts b/plugins/opencode/vitest.config.ts
new file mode 100644
index 000000000..c55c5cc97
--- /dev/null
+++ b/plugins/opencode/vitest.config.ts
@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+ test: {
+ environment: "node",
+ globals: true,
+ },
+});
diff --git a/scripts/install.ps1 b/scripts/install.ps1
index abe01875a..adfa9f902 100644
--- a/scripts/install.ps1
+++ b/scripts/install.ps1
@@ -1611,7 +1611,7 @@ switch ($args[0]) {
}
if ($args.Count -lt 2) {
- Fail 'Usage: headroom wrap <claude|codex|aider|cursor|openclaw> [...]'
+ Fail 'Usage: headroom wrap <claude|codex|aider|cursor|openclaw|opencode> [...]'
}
$tool = $args[1]
@@ -1623,8 +1623,9 @@ switch ($args[0]) {
'aider' { }
'cursor' { }
'openclaw' { }
+ 'opencode' { }
default {
- Fail "Docker-native wrapper does not support 'wrap $tool'. Supported targets: claude, codex, aider, cursor, openclaw"
+ Fail "Docker-native wrapper does not support 'wrap $tool'. Supported targets: claude, codex, aider, cursor, openclaw, opencode"
}
}
diff --git a/scripts/install.sh b/scripts/install.sh
index 64e0f33dd..18edc2e45 100644
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -1476,15 +1476,15 @@ main() {
return
fi
- (($# >= 2)) || die "Usage: headroom wrap <claude|codex|aider|cursor|openclaw> [...]"
+ (($# >= 2)) || die "Usage: headroom wrap <claude|codex|aider|cursor|openclaw|opencode> [...]"
local tool="$2"
shift 2
case "${tool}" in
- claude|codex|aider|cursor|openclaw)
+ claude|codex|aider|cursor|openclaw|opencode)
;;
*)
- die "Docker-native wrapper does not support 'wrap ${tool}'. Supported targets: claude, codex, aider, cursor, openclaw"
+ die "Docker-native wrapper does not support 'wrap ${tool}'. Supported targets: claude, codex, aider, cursor, openclaw, opencode"
;;
esac
diff --git a/tests/conftest.py b/tests/conftest.py
index 719bba4b7..892c20c27 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -59,7 +59,16 @@ def _reset_headroom_logger_propagation():
"""
import logging as _logging
- _logging.getLogger("headroom").propagate = True
+ for logger_name in (
+ "headroom",
+ "headroom.proxy",
+ "headroom.proxy.forwarded_headers",
+ "headroom.transforms",
+ "headroom.transforms.kompress_compressor",
+ ):
+ logger = _logging.getLogger(logger_name)
+ logger.disabled = False
+ logger.propagate = True
yield
diff --git a/tests/test_cli/test_install_cli.py b/tests/test_cli/test_install_cli.py
index 4fd5ba23f..94510724c 100644
--- a/tests/test_cli/test_install_cli.py
+++ b/tests/test_cli/test_install_cli.py
@@ -132,7 +132,7 @@ def test_install_apply_rejects_provider_scope_targets_without_support() -> None:
)
assert result.exit_code != 0
- assert "Provider scope supports only claude, codex, and openclaw" in result.output
+ assert "Provider scope supports only claude, codex, openclaw, and opencode" in result.output
def test_install_apply_restores_previous_deployment_after_failed_update(monkeypatch) -> None:
diff --git a/tests/test_cli/test_wrap_opencode.py b/tests/test_cli/test_wrap_opencode.py
new file mode 100644
index 000000000..294aceaf1
--- /dev/null
+++ b/tests/test_cli/test_wrap_opencode.py
@@ -0,0 +1,840 @@
+"""Tests for `headroom wrap opencode` and `headroom unwrap opencode`."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+from click.testing import CliRunner
+
+from headroom.cli import wrap as wrap_mod
+from headroom.cli.main import main
+
+
+def runner() -> CliRunner:
+ return CliRunner()
+
+
+def _set_test_home(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+ home = str(tmp_path)
+ monkeypatch.setenv("HOME", home)
+ monkeypatch.setenv("USERPROFILE", home)
+ monkeypatch.delenv("OPENCODE_HOME", raising=False)
+ monkeypatch.delenv("OPENCODE_CONFIG", raising=False)
+
+
+# ---------------------------------------------------------------------------
+# Wrap opencode
+# ---------------------------------------------------------------------------
+
+
+def test_wrap_opencode_sets_config_content_env(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """OPENCODE_CONFIG_CONTENT env var is set with the headroom provider."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+ _set_test_home(monkeypatch, tmp_path)
+ monkeypatch.setenv("OPENAI_BASE_URL", "https://deepseek.example/v1")
+ monkeypatch.setenv("ANTHROPIC_BASE_URL", "https://anthropic.example")
+
+ captured: dict[str, object] = {}
+
+ def fake_launch_tool(**kwargs): # noqa: ANN003
+ captured.update(kwargs)
+
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ result = runner.invoke(
+ main, ["wrap", "opencode", "--port", "9000", "--no-mcp", "--", "--model", "gpt-4o"]
+ )
+
+ assert result.exit_code == 0, result.output
+ env = captured["env"]
+ assert isinstance(env, dict)
+ assert "OPENCODE_CONFIG_CONTENT" in env
+ config = json.loads(env["OPENCODE_CONFIG_CONTENT"])
+ assert config["provider"]["headroom"]["npm"] == "@ai-sdk/openai-compatible"
+ assert config["provider"]["headroom"]["options"]["baseURL"] == "http://127.0.0.1:9000/v1"
+ assert "model" not in config # headroom provider is a transparent pass-through
+ assert captured["tool_label"] == "OPENCODE"
+ assert captured["agent_type"] == "opencode"
+ assert captured["args"] == ("--model", "gpt-4o")
+
+
+def test_wrap_opencode_does_not_add_base_url_env_vars(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """OPENAI_BASE_URL and ANTHROPIC_BASE_URL are left to OpenCode providers."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+ _set_test_home(monkeypatch, tmp_path)
+ monkeypatch.setenv("OPENAI_BASE_URL", "https://deepseek.example/v1")
+ monkeypatch.setenv("ANTHROPIC_BASE_URL", "https://anthropic.example")
+
+ captured: dict[str, object] = {}
+
+ def fake_launch_tool(**kwargs): # noqa: ANN003
+ captured.update(kwargs)
+
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ result = runner.invoke(main, ["wrap", "opencode", "--port", "9000", "--no-mcp"])
+
+ assert result.exit_code == 0, result.output
+ env = captured["env"]
+ assert isinstance(env, dict)
+ assert env["OPENAI_BASE_URL"] == "https://deepseek.example/v1"
+ assert env["ANTHROPIC_BASE_URL"] == "https://anthropic.example"
+
+
+def test_wrap_opencode_missing_binary_errors_clearly(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """If the opencode binary is missing the command must fail with a clear error."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+
+ with patch.object(wrap_mod.shutil, "which", return_value=None):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ result = runner.invoke(main, ["wrap", "opencode"])
+
+ assert result.exit_code == 1
+ assert "'opencode' not found in PATH" in result.output
+
+
+def test_wrap_opencode_prepare_only_injects_config(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """`wrap opencode --prepare-only` writes the provider config to opencode.json."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+ _set_test_home(monkeypatch, tmp_path)
+
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ result = runner.invoke(main, ["wrap", "opencode", "--port", "9000", "--prepare-only"])
+
+ assert result.exit_code == 0, result.output
+ config_file = tmp_path / ".config" / "opencode" / "opencode.json"
+ assert config_file.exists()
+ config = json.loads(config_file.read_text())
+ assert config["provider"]["headroom"]["options"]["baseURL"] == "http://127.0.0.1:9000/v1"
+
+
+def test_wrap_opencode_no_mcp_skips_mcp_injection(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """`--no-mcp` skips MCP server injection."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+ _set_test_home(monkeypatch, tmp_path)
+
+ captured: dict[str, object] = {}
+
+ def fake_launch_tool(**kwargs): # noqa: ANN003
+ captured.update(kwargs)
+
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ result = runner.invoke(main, ["wrap", "opencode", "--port", "9000", "--no-mcp"])
+
+ assert result.exit_code == 0, result.output
+ env = captured["env"]
+ config = json.loads(env["OPENCODE_CONFIG_CONTENT"])
+ assert "mcp" not in config
+
+
+def test_wrap_opencode_injects_mcp_by_default(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """MCP is included in OPENCODE_CONFIG_CONTENT by default."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+ _set_test_home(monkeypatch, tmp_path)
+
+ captured: dict[str, object] = {}
+
+ def fake_launch_tool(**kwargs): # noqa: ANN003
+ captured.update(kwargs)
+
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ result = runner.invoke(main, ["wrap", "opencode", "--port", "9000"])
+
+ assert result.exit_code == 0, result.output
+ env = captured["env"]
+ config = json.loads(env["OPENCODE_CONFIG_CONTENT"])
+ assert "mcp" in config
+ assert config["mcp"]["headroom"]["type"] == "remote"
+
+
+def test_wrap_opencode_injects_rtk_into_agents_md(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """RTK instructions are injected into global and project AGENTS.md."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+ _set_test_home(monkeypatch, tmp_path)
+
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=SystemExit(0)):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ result = runner.invoke(main, ["wrap", "opencode", "--port", "9000", "--no-mcp"])
+
+ assert result.exit_code == 0, result.output
+ global_agents = tmp_path / ".config" / "opencode" / "AGENTS.md"
+ project_agents = tmp_path / "AGENTS.md"
+ assert global_agents.exists(), "Global AGENTS.md should be created"
+ assert project_agents.exists(), "Project AGENTS.md should be created"
+ assert wrap_mod._RTK_MARKER in global_agents.read_text()
+ assert wrap_mod._RTK_MARKER in project_agents.read_text()
+
+
+def test_wrap_opencode_idempotent_no_duplicate_block(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Running wrap twice must not duplicate the RTK block in AGENTS.md."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+ _set_test_home(monkeypatch, tmp_path)
+
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=SystemExit(0)):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ runner.invoke(main, ["wrap", "opencode", "--port", "9000", "--no-mcp"])
+ runner.invoke(main, ["wrap", "opencode", "--port", "9000", "--no-mcp"])
+
+ project_agents = tmp_path / "AGENTS.md"
+ content = project_agents.read_text()
+ assert content.count(wrap_mod._RTK_MARKER) == 1
+
+
+# ---------------------------------------------------------------------------
+# Unwrap opencode
+# ---------------------------------------------------------------------------
+
+
+def test_unwrap_opencode_restores_from_backup(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Unwrap restores the pre-wrap backup and removes it."""
+ monkeypatch.chdir(tmp_path)
+ _set_test_home(monkeypatch, tmp_path)
+
+ config_file = tmp_path / ".config" / "opencode" / "opencode.json"
+ backup_file = config_file.with_suffix(".json.headroom-backup")
+ config_file.parent.mkdir(parents=True, exist_ok=True)
+ original = '{"model": "openai/gpt-4o"}'
+ config_file.write_text(original)
+ backup_file.write_text(original)
+
+ with patch.object(wrap_mod, "_stop_local_proxy_for_unwrap", return_value="stopped"):
+ result = runner.invoke(main, ["unwrap", "opencode"])
+
+ assert result.exit_code == 0, result.output
+ assert "Restored prior" in result.output
+ assert not backup_file.exists()
+ assert config_file.read_text() == original
+
+
+def test_unwrap_opencode_strips_blocks_when_no_backup(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Unwrap strips Headroom blocks when no backup exists."""
+ monkeypatch.chdir(tmp_path)
+ _set_test_home(monkeypatch, tmp_path)
+
+ config_file = tmp_path / ".config" / "opencode" / "opencode.json"
+ config_file.parent.mkdir(parents=True, exist_ok=True)
+ user_content = '{"model": "openai/gpt-4o"}'
+ wrapped_content = (
+ wrap_mod._PROVIDER_MARKER_START
+ + '\n"provider": {},\n'
+ + wrap_mod._PROVIDER_MARKER_END
+ + "\n"
+ + user_content
+ )
+ config_file.write_text(wrapped_content)
+
+ with patch.object(wrap_mod, "_stop_local_proxy_for_unwrap", return_value="stopped"):
+ result = runner.invoke(main, ["unwrap", "opencode"])
+
+ assert result.exit_code == 0, result.output
+ assert "Removed Headroom block" in result.output
+ assert user_content in config_file.read_text()
+ assert wrap_mod._PROVIDER_MARKER_START not in config_file.read_text()
+
+
+# ---------------------------------------------------------------------------
+# Edge cases — wrap
+# ---------------------------------------------------------------------------
+
+
+def test_wrap_opencode_preserves_existing_user_providers(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Wrap merges headroom provider without disturbing user's existing providers."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+ _set_test_home(monkeypatch, tmp_path)
+
+ config_file = tmp_path / ".config" / "opencode" / "opencode.json"
+ config_file.parent.mkdir(parents=True, exist_ok=True)
+ config_file.write_text('{"provider": {"openai": {"models": {"gpt-4o": {"name": "GPT-4o"}}}}}')
+
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=SystemExit(0)):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ result = runner.invoke(main, ["wrap", "opencode", "--port", "9000", "--no-mcp"])
+
+ assert result.exit_code == 0, result.output
+ config = json.loads(config_file.read_text())
+ assert "headroom" in config["provider"], "headroom provider not injected"
+ assert "openai" in config["provider"], "user's openai provider was removed"
+
+
+def test_wrap_opencode_port_change_updates_existing_config(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Wrapping with a different port updates the baseURL in opencode.json."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+ _set_test_home(monkeypatch, tmp_path)
+
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=SystemExit(0)):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ runner.invoke(main, ["wrap", "opencode", "--port", "9000", "--no-mcp"])
+ runner.invoke(main, ["wrap", "opencode", "--port", "9001", "--no-mcp"])
+
+ config_file = tmp_path / ".config" / "opencode" / "opencode.json"
+ config = json.loads(config_file.read_text())
+ assert config["provider"]["headroom"]["options"]["baseURL"] == "http://127.0.0.1:9001/v1"
+
+
+def test_wrap_opencode_handles_malformed_config_file(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Wrap handles a malformed opencode.json by backing it up before overwriting."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+ _set_test_home(monkeypatch, tmp_path)
+
+ config_file = tmp_path / ".config" / "opencode" / "opencode.json"
+ config_file.parent.mkdir(parents=True, exist_ok=True)
+ malformed = '{"model": "gpt-4o",}' # trailing comma
+ config_file.write_text(malformed)
+ backup_file = config_file.with_suffix(".json.headroom-backup")
+
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=SystemExit(0)):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ result = runner.invoke(main, ["wrap", "opencode", "--port", "9000", "--no-mcp"])
+
+ assert result.exit_code == 0, result.output
+ assert backup_file.exists(), "backup must be created before overwriting"
+ assert backup_file.read_text() == malformed, "backup must preserve original byte-for-byte"
+ # The config file is now valid JSON with headroom provider.
+ config = json.loads(config_file.read_text())
+ assert "headroom" in config.get("provider", {})
+
+
+def test_wrap_opencode_handles_empty_config_file(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Wrap handles an empty opencode.json file gracefully."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+ _set_test_home(monkeypatch, tmp_path)
+
+ config_file = tmp_path / ".config" / "opencode" / "opencode.json"
+ config_file.parent.mkdir(parents=True, exist_ok=True)
+ config_file.write_text("")
+
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=SystemExit(0)):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ result = runner.invoke(main, ["wrap", "opencode", "--port", "9000", "--no-mcp"])
+
+ assert result.exit_code == 0, result.output
+ config = json.loads(config_file.read_text())
+ assert config["provider"]["headroom"]["options"]["baseURL"] == "http://127.0.0.1:9000/v1"
+
+
+def test_wrap_opencode_handles_config_dir_missing(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Wrap creates the config directory when it doesn't exist."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+ _set_test_home(monkeypatch, tmp_path)
+
+ config_dir = tmp_path / ".config" / "opencode"
+ assert not config_dir.exists()
+
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=SystemExit(0)):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ result = runner.invoke(main, ["wrap", "opencode", "--port", "9000", "--no-mcp"])
+
+ assert result.exit_code == 0, result.output
+ assert config_dir.exists()
+ assert (config_dir / "opencode.json").exists()
+
+
+def test_wrap_opencode_rtk_preserves_existing_agents_md(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """RTK injection appends to AGENTS.md without removing existing content."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+ _set_test_home(monkeypatch, tmp_path)
+
+ existing_content = "# My custom rules\nUse spaces, not tabs."
+ (tmp_path / "AGENTS.md").write_text(existing_content)
+
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=SystemExit(0)):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ result = runner.invoke(main, ["wrap", "opencode", "--port", "9000", "--no-mcp"])
+
+ assert result.exit_code == 0, result.output
+ content = (tmp_path / "AGENTS.md").read_text()
+ assert existing_content in content
+ assert wrap_mod._RTK_MARKER in content
+
+
+def test_wrap_opencode_no_rtk_leaves_agents_md_untouched(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """`--no-rtk` flag leaves existing AGENTS.md untouched."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+ _set_test_home(monkeypatch, tmp_path)
+
+ existing_content = "# My custom rules\nUse spaces, not tabs."
+ (tmp_path / "AGENTS.md").write_text(existing_content)
+
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=SystemExit(0)):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ result = runner.invoke(
+ main, ["wrap", "opencode", "--port", "9000", "--no-rtk", "--no-mcp"]
+ )
+
+ assert result.exit_code == 0, result.output
+ content = (tmp_path / "AGENTS.md").read_text()
+ assert content == existing_content, "--no-rtk modified AGENTS.md"
+ assert wrap_mod._RTK_MARKER not in content
+
+
+def test_wrap_opencode_respects_opencode_config_env(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """OPENCODE_CONFIG env var overrides the default config path."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+ _set_test_home(monkeypatch, tmp_path)
+
+ custom_config = tmp_path / "custom" / "config.json"
+ monkeypatch.setenv("OPENCODE_CONFIG", str(custom_config))
+
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=SystemExit(0)):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ result = runner.invoke(main, ["wrap", "opencode", "--port", "9000", "--no-mcp"])
+
+ assert result.exit_code == 0, result.output
+ assert custom_config.exists()
+ default_config = tmp_path / ".config" / "opencode" / "opencode.json"
+ assert not default_config.exists(), "default config should not be created when OPENCODE_CONFIG is set"
+
+
+def test_wrap_opencode_headroom_project_from_cwd(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """HEADROOM_PROJECT is set based on the current working directory name."""
+ project_dir = tmp_path / "my-project"
+ project_dir.mkdir()
+ monkeypatch.chdir(project_dir)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+ monkeypatch.delenv("HEADROOM_PROJECT", raising=False)
+ _set_test_home(monkeypatch, tmp_path)
+
+ captured: dict[str, object] = {}
+
+ def fake_launch_tool(**kwargs): # noqa: ANN003
+ captured.update(kwargs)
+
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ result = runner.invoke(main, ["wrap", "opencode", "--port", "9000", "--no-mcp"])
+
+ assert result.exit_code == 0, result.output
+ env = captured["env"]
+ assert env.get("HEADROOM_PROJECT") == "my-project"
+
+
+def test_wrap_opencode_respects_existing_headroom_project(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """User-set HEADROOM_PROJECT env var is preserved, not overridden."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+ _set_test_home(monkeypatch, tmp_path)
+ monkeypatch.setenv("HEADROOM_PROJECT", "user-set-value")
+
+ captured: dict[str, object] = {}
+
+ def fake_launch_tool(**kwargs): # noqa: ANN003
+ captured.update(kwargs)
+
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ result = runner.invoke(main, ["wrap", "opencode", "--port", "9000", "--no-mcp"])
+
+ assert result.exit_code == 0, result.output
+ env = captured["env"]
+ assert env["HEADROOM_PROJECT"] == "user-set-value"
+
+
+def test_wrap_opencode_config_merges_existing_model(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Wrap preserves the user's existing model selection."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+ _set_test_home(monkeypatch, tmp_path)
+
+ config_file = tmp_path / ".config" / "opencode" / "opencode.json"
+ config_file.parent.mkdir(parents=True, exist_ok=True)
+ config_file.write_text('{"model": "openai/gpt-4o"}')
+
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=SystemExit(0)):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ result = runner.invoke(main, ["wrap", "opencode", "--port", "9000", "--no-mcp"])
+
+ assert result.exit_code == 0, result.output
+ config = json.loads(config_file.read_text())
+ assert config["model"] == "openai/gpt-4o"
+ assert config["provider"]["headroom"]["npm"] == "@ai-sdk/openai-compatible"
+
+
+# ---------------------------------------------------------------------------
+# Edge cases — unwrap
+# ---------------------------------------------------------------------------
+
+
+def test_unwrap_opencode_removes_config_when_only_headroom_content(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Unwrap removes the config file entirely when it contained only Headroom content."""
+ monkeypatch.chdir(tmp_path)
+ _set_test_home(monkeypatch, tmp_path)
+
+ config_file = tmp_path / ".config" / "opencode" / "opencode.json"
+ config_file.parent.mkdir(parents=True, exist_ok=True)
+ wrapped_content = (
+ wrap_mod._PROVIDER_MARKER_START
+ + '\n"provider": {},\n'
+ + wrap_mod._PROVIDER_MARKER_END
+ )
+ config_file.write_text(wrapped_content)
+
+ with patch.object(wrap_mod, "_stop_local_proxy_for_unwrap", return_value="stopped"):
+ result = runner.invoke(main, ["unwrap", "opencode"])
+
+ assert result.exit_code == 0, result.output
+ assert "Removed" in result.output
+ assert not config_file.exists()
+
+
+def test_unwrap_opencode_noop_when_config_missing(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Unwrap is a safe no-op when the config file doesn't exist."""
+ monkeypatch.chdir(tmp_path)
+ _set_test_home(monkeypatch, tmp_path)
+
+ with patch.object(wrap_mod, "_stop_local_proxy_for_unwrap", return_value="stopped"):
+ result = runner.invoke(main, ["unwrap", "opencode"])
+
+ assert result.exit_code == 0, result.output
+ assert "does not exist" in result.output
+
+
+def test_unwrap_opencode_noop_when_no_headroom_markers(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Unwrap is a safe no-op when the config has no Headroom markers."""
+ monkeypatch.chdir(tmp_path)
+ _set_test_home(monkeypatch, tmp_path)
+
+ config_file = tmp_path / ".config" / "opencode" / "opencode.json"
+ config_file.parent.mkdir(parents=True, exist_ok=True)
+ config_file.write_text('{"model": "openai/gpt-4o"}')
+
+ with patch.object(wrap_mod, "_stop_local_proxy_for_unwrap", return_value="stopped"):
+ result = runner.invoke(main, ["unwrap", "opencode"])
+
+ assert result.exit_code == 0, result.output
+ assert "no Headroom wrap markers" in result.output
+ assert config_file.read_text().strip() == '{"model": "openai/gpt-4o"}'
+
+
+def test_wrap_unwrap_rewrap_is_idempotent(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Full wrap-unwrap-rewrap cycle produces consistent results."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+ _set_test_home(monkeypatch, tmp_path)
+
+ config_file = tmp_path / ".config" / "opencode" / "opencode.json"
+ config_file.parent.mkdir(parents=True, exist_ok=True)
+ user_config = '{"model": "openai/gpt-4o", "provider": {"openai": {}}}'
+ config_file.write_text(user_config)
+
+ # First wrap
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=SystemExit(0)):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ runner.invoke(main, ["wrap", "opencode", "--port", "9000", "--no-mcp"])
+
+ # Unwrap
+ with patch.object(wrap_mod, "_stop_local_proxy_for_unwrap", return_value="stopped"):
+ runner.invoke(main, ["unwrap", "opencode"])
+
+ # After unwrap, file should match original
+ after_unwrap = json.loads(config_file.read_text())
+ assert after_unwrap["model"] == "openai/gpt-4o"
+ assert "headroom" not in after_unwrap.get("provider", {})
+
+ # Re-wrap
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=SystemExit(0)):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ runner.invoke(main, ["wrap", "opencode", "--port", "9001", "--no-mcp"])
+
+ # After re-wrap, headroom should be back, model unchanged
+ after_rewrap = json.loads(config_file.read_text())
+ assert after_rewrap["model"] == "openai/gpt-4o"
+ assert "headroom" in after_rewrap.get("provider", {})
+
+
+def test_unwrap_opencode_restores_backup_and_removes_it(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Unwrap removes the backup file after successful restore."""
+ monkeypatch.chdir(tmp_path)
+ _set_test_home(monkeypatch, tmp_path)
+
+ config_file = tmp_path / ".config" / "opencode" / "opencode.json"
+ backup_file = config_file.with_suffix(".json.headroom-backup")
+ config_file.parent.mkdir(parents=True, exist_ok=True)
+ original = '{"model": "openai/gpt-4o"}'
+ config_file.write_text(original)
+ backup_file.write_text(original)
+
+ with patch.object(wrap_mod, "_stop_local_proxy_for_unwrap", return_value="stopped"):
+ result = runner.invoke(main, ["unwrap", "opencode"])
+
+ assert result.exit_code == 0, result.output
+ assert "Restored prior" in result.output
+ assert not backup_file.exists(), "backup file was not cleaned up after restore"
+
+
+def test_wrap_opencode_no_arguments_is_valid(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """`headroom wrap opencode` with no additional arguments is a valid command."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+ _set_test_home(monkeypatch, tmp_path)
+
+ captured: dict[str, object] = {}
+
+ def fake_launch_tool(**kwargs): # noqa: ANN003
+ captured.update(kwargs)
+
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ result = runner.invoke(main, ["wrap", "opencode", "--no-mcp"])
+
+ assert result.exit_code == 0, result.output
+ assert captured["tool_label"] == "OPENCODE"
+ assert captured["args"] == ()
+
+
+def test_wrap_opencode_with_memory_flag(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """--memory flag is accepted and does not crash."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+ _set_test_home(monkeypatch, tmp_path)
+
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=SystemExit(0)):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ result = runner.invoke(
+ main, ["wrap", "opencode", "--port", "9000", "--memory", "--no-mcp"]
+ )
+
+ assert result.exit_code == 0, result.output
+
+
+def test_wrap_opencode_with_backend_and_anyllm_provider(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """--backend and --anyllm-provider flags are accepted."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+ _set_test_home(monkeypatch, tmp_path)
+
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=SystemExit(0)):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ result = runner.invoke(
+ main, [
+ "wrap", "opencode", "--port", "9000",
+ "--backend", "anyllm", "--anyllm-provider", "groq",
+ "--no-mcp",
+ ]
+ )
+
+ assert result.exit_code == 0, result.output
+
+
+def test_wrap_opencode_with_no_proxy(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """--no-proxy flag skips proxy startup but still configures the tool."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+ _set_test_home(monkeypatch, tmp_path)
+
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=SystemExit(0)):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ result = runner.invoke(
+ main, ["wrap", "opencode", "--port", "9000", "--no-proxy", "--no-mcp"]
+ )
+
+ assert result.exit_code == 0, result.output
+
+
+def test_wrap_opencode_with_verbose_flag(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """--verbose flag does not crash."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+ _set_test_home(monkeypatch, tmp_path)
+
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=SystemExit(0)):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ result = runner.invoke(
+ main, ["wrap", "opencode", "--port", "9000", "--verbose", "--no-mcp"]
+ )
+
+ assert result.exit_code == 0, result.output
+
+
+def test_wrap_opencode_respects_opencode_home_env(
+ runner: CliRunner,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """OPENCODE_HOME env var controls where AGENTS.md is written."""
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
+ custom_home = str(tmp_path / "custom-opencode-home")
+ monkeypatch.setenv("HOME", str(tmp_path))
+ monkeypatch.setenv("OPENCODE_HOME", custom_home)
+
+ with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=SystemExit(0)):
+ with patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")):
+ result = runner.invoke(
+ main, ["wrap", "opencode", "--port", "9000", "--no-mcp"]
+ )
+
+ assert result.exit_code == 0, result.output
+ agents_md = Path(custom_home) / "AGENTS.md"
+ assert agents_md.exists()
diff --git a/tests/test_cli/test_wrap_persistent.py b/tests/test_cli/test_wrap_persistent.py
index 7911a1c77..7bdfb5654 100644
--- a/tests/test_cli/test_wrap_persistent.py
+++ b/tests/test_cli/test_wrap_persistent.py
@@ -509,6 +509,7 @@ def test_ensure_proxy_restarts_for_flags_when_no_other_wrapper(monkeypatch) -> N
monkeypatch.setattr(wrap_cli, "_check_proxy", lambda port: len(calls) == 0)
monkeypatch.setattr(wrap_cli, "_query_proxy_health", lambda port: health)
monkeypatch.setattr(wrap_cli, "_live_proxy_clients", lambda *a, **kw: [])
+ monkeypatch.setattr(wrap_cli, "_port_bind_error", lambda port: None)
monkeypatch.setattr(
wrap_cli,
"_kill_proxy_by_pid",
diff --git a/tests/test_install/test_paths.py b/tests/test_install/test_paths.py
index 821dfc15a..5c632804d 100644
--- a/tests/test_install/test_paths.py
+++ b/tests/test_install/test_paths.py
@@ -66,3 +66,4 @@ def test_env_target_and_config_paths(monkeypatch, tmp_path: Path) -> None:
assert install_paths.claude_settings_path() == tmp_path / ".claude" / "settings.json"
assert install_paths.codex_config_path() == tmp_path / ".codex" / "config.toml"
assert install_paths.openclaw_config_path() == tmp_path / ".openclaw" / "openclaw.json"
+ assert install_paths.opencode_config_path() == tmp_path / ".config" / "opencode" / "opencode.json"
diff --git a/tests/test_install/test_providers.py b/tests/test_install/test_providers.py
index f02da01c5..6e5b50fdc 100644
--- a/tests/test_install/test_providers.py
+++ b/tests/test_install/test_providers.py
@@ -16,6 +16,9 @@ from headroom.providers.codex.install import apply_provider_scope as apply_codex
from headroom.providers.codex.install import build_install_env as build_codex_install_env
from headroom.providers.codex.install import revert_provider_scope as revert_codex_provider_scope
from headroom.providers.copilot.install import build_install_env as build_copilot_install_env
+from headroom.providers.opencode.install import apply_provider_scope as apply_opencode_provider_scope
+from headroom.providers.opencode.install import build_install_env as build_opencode_install_env
+from headroom.providers.opencode.install import revert_provider_scope as revert_opencode_provider_scope
def _manifest(tmp_path: Path) -> DeploymentManifest:
@@ -487,6 +490,88 @@ def test_revert_claude_provider_scope_ignores_missing_settings_file(tmp_path: Pa
revert_claude_provider_scope(mutation, manifest)
+# ---------------------------------------------------------------------------
+# OpenCode provider tests
+# ---------------------------------------------------------------------------
+
+
+def test_opencode_build_install_env_leaves_provider_env_unset() -> None:
+ env = build_opencode_install_env(port=5566, backend="ignored")
+ assert env == {}
+
+
+def test_apply_and_revert_opencode_provider_scope(monkeypatch, tmp_path: Path) -> None:
+ config_path = tmp_path / "opencode.json"
+ config_path.write_text('{"model": "openai/gpt-4o"}')
+ monkeypatch.setattr(
+ "headroom.providers.opencode.install.opencode_config_path", lambda: config_path
+ )
+ manifest = _manifest(tmp_path)
+
+ mutation = apply_opencode_provider_scope(manifest)
+ assert mutation is not None
+ assert mutation.target == "opencode"
+ assert mutation.kind == "json-block"
+
+ content = config_path.read_text()
+ data = json.loads(content)
+ assert data["provider"]["headroom"]["options"]["baseURL"] == "http://127.0.0.1:8787/v1"
+ assert data["model"] == "openai/gpt-4o" # user model preserved
+
+ revert_opencode_provider_scope(mutation, manifest)
+ reverted = json.loads(config_path.read_text())
+ assert reverted["model"] == "openai/gpt-4o"
+ assert "headroom" not in reverted.get("provider", {})
+
+
+def test_apply_opencode_provider_scope_skips_non_provider_scope(
+ monkeypatch, tmp_path: Path
+) -> None:
+ config_path = tmp_path / "opencode.json"
+ monkeypatch.setattr(
+ "headroom.providers.opencode.install.opencode_config_path", lambda: config_path
+ )
+ manifest = _manifest(tmp_path)
+ manifest.scope = "user"
+
+ mutation = apply_opencode_provider_scope(manifest)
+ assert mutation is None
+ assert not config_path.exists()
+
+
+def test_apply_opencode_provider_scope_creates_new_config_when_missing(
+ monkeypatch, tmp_path: Path
+) -> None:
+ config_path = tmp_path / "nested" / "opencode.json"
+ monkeypatch.setattr(
+ "headroom.providers.opencode.install.opencode_config_path", lambda: config_path
+ )
+ manifest = _manifest(tmp_path)
+
+ mutation = apply_opencode_provider_scope(manifest)
+ assert mutation is not None
+ data = json.loads(config_path.read_text())
+ assert data["provider"]["headroom"]["options"]["baseURL"] == "http://127.0.0.1:8787/v1"
+
+
+def test_revert_opencode_provider_scope_ignores_missing_path_and_file(
+ tmp_path: Path,
+) -> None:
+ manifest = _manifest(tmp_path)
+ revert_opencode_provider_scope(
+ ManagedMutation(target="opencode", kind="json-block"),
+ manifest,
+ )
+ revert_opencode_provider_scope(
+ ManagedMutation(
+ target="opencode",
+ kind="json-block",
+ path=str(tmp_path / "missing.json"),
+ ),
+ manifest,
+ )
+
+
# ---------------------------------------------------------------------------
# Bug 3 regression tests (#406): requires_openai_auth and openai_base_url
# must never appear in the headroom provider block.
@@ -699,3 +784,106 @@ def test_persistent_install_strip_removes_openai_base_url(monkeypatch, tmp_path:
f"orphaned openai_base_url must be removed by revert:\n{orphan_reverted}"
)
assert 'model = "gpt-4o"' in orphan_reverted
+
+
+# ---------------------------------------------------------------------------
+# Planner-level opencode smoke tests
+# ---------------------------------------------------------------------------
+
+
+def test_planner_resolves_opencode_as_install_target() -> None:
+ from headroom.install.planner import resolve_targets
+
+ targets = resolve_targets("manual", ["opencode"])
+ assert "opencode" in targets
+
+
+def test_planner_opencode_in_supported_targets_enum() -> None:
+ from headroom.install.models import ToolTarget
+ from headroom.install.planner import SUPPORTED_TARGETS, PROVIDER_SCOPE_TARGETS
+
+ assert ToolTarget.OPENCODE in SUPPORTED_TARGETS
+ assert ToolTarget.OPENCODE in PROVIDER_SCOPE_TARGETS
+
+
+def test_planner_opencode_in_provider_scope_targets() -> None:
+ from headroom.install.planner import resolve_targets
+
+ targets = resolve_targets("manual", ["opencode"], scope="provider")
+ assert "opencode" in targets
+
+
+def test_planner_build_tool_envs_includes_opencode() -> None:
+ from headroom.install.planner import build_tool_envs
+
+ envs = build_tool_envs(port=8787, backend="anthropic", targets=["opencode"])
+ assert "opencode" in envs
+ assert envs["opencode"] == {}
+
+
+def test_planner_resolve_all_includes_opencode() -> None:
+ from headroom.install.planner import resolve_targets
+
+ targets = resolve_targets("all", [])
+ assert "opencode" in targets
+
+
+def test_planner_provider_scope_unsupported_error_excludes_opencode() -> None:
+ import click
+ import pytest
+ from headroom.install.planner import resolve_targets
+
+ with pytest.raises(click.ClickException, match="unsupported targets"):
+ resolve_targets("manual", ["cursor"], scope="provider")
+
+
+# ---------------------------------------------------------------------------
+# Opencode revert OSError fallback
+# ---------------------------------------------------------------------------
+
+
+def test_revert_opencode_provider_scope_fallback_on_oserror(
+ monkeypatch, tmp_path: Path
+) -> None:
+ """revert_opencode_provider_scope falls back to strip when backup copy fails."""
+ config_path = tmp_path / "opencode.json"
+ backup_path = config_path.with_suffix(".json.headroom-backup")
+ config_path.parent.mkdir(parents=True, exist_ok=True)
+
+ from headroom.install.models import ManagedMutation
+ from headroom.providers.opencode.config import (
+ _PROVIDER_MARKER_START,
+ _PROVIDER_MARKER_END,
+ )
+ original = '{"model": "openai/gpt-4o"}'
+ backup_path.write_text(original)
+
+ provider_json = '{"headroom":{"npm":"@ai-sdk/openai-compatible","name":"Headroom Proxy","options":{"baseURL":"http://127.0.0.1:8787/v1"}}}'
+ config_path.write_text(
+ f'{_PROVIDER_MARKER_START}\n"provider": {provider_json},\n{_PROVIDER_MARKER_END}\n'
+ )
+
+ monkeypatch.setattr(
+ "headroom.providers.opencode.install.opencode_config_path",
+ lambda: config_path,
+ )
+
+ from headroom.providers.opencode.install import revert_provider_scope
+
+ manifest = _manifest(tmp_path)
+
+ def _fail_copy2(src, dst):
+ msg = "permission denied"
+ raise OSError(msg)
+
+ monkeypatch.setattr("shutil.copy2", _fail_copy2)
+
+ revert_provider_scope(
+ ManagedMutation(
+ target="opencode", kind="json-block", path=str(config_path)
+ ),
+ manifest,
+ )
+
+ assert backup_path.exists() # backup preserved when copy fails
+ assert not config_path.exists() or "headroom" not in config_path.read_text()
diff --git a/tests/test_learn/test_scanner.py b/tests/test_learn/test_scanner.py
index 0f6dcb9f1..295c6fe59 100644
--- a/tests/test_learn/test_scanner.py
+++ b/tests/test_learn/test_scanner.py
@@ -164,8 +164,8 @@ class TestGreedyPathDecode:
result = _greedy_path_decode(tmp_path, [])
assert result == tmp_path
- def test_empty_parts_returns_none_when_not_exists(self) -> None:
- result = _greedy_path_decode(Path("/nonexistent/path"), [])
+ def test_empty_parts_returns_none_when_not_exists(self, tmp_path: Path) -> None:
+ result = _greedy_path_decode(tmp_path / "missing", [])
assert result is None
diff --git a/tests/test_mcp_registry_opencode.py b/tests/test_mcp_registry_opencode.py
new file mode 100644
index 000000000..4ce831b40
--- /dev/null
+++ b/tests/test_mcp_registry_opencode.py
@@ -0,0 +1,392 @@
+"""Tests for :class:`headroom.mcp_registry.opencode.OpencodeRegistrar`."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from headroom.mcp_registry.opencode import (
+ OpencodeRegistrar,
+ _diff_specs,
+ _entry_to_spec,
+ _spec_to_entry,
+ _specs_equivalent,
+)
+from headroom.mcp_registry.base import RegisterStatus
+
+
+def _write_json(path: Path, data: dict[str, Any]) -> None:
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(json.dumps(data, indent=2) + "\n")
+
+
+def _registrar(tmp_path: Path) -> OpencodeRegistrar:
+ return OpencodeRegistrar(config_path=tmp_path / "opencode.json")
+
+
+def test_detect_when_binary_present(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ """Detection succeeds when the opencode binary is in PATH."""
+ monkeypatch.setenv("PATH", str(tmp_path))
+ (tmp_path / "opencode").write_text("#!/bin/sh\necho ok")
+ (tmp_path / "opencode").chmod(0o755)
+ registrar = _registrar(tmp_path)
+ assert registrar.detect() is True
+
+
+def test_detect_when_config_dir_present(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ """Detection succeeds when the config directory exists."""
+ monkeypatch.setenv("PATH", "/nonexistent")
+ config_dir = tmp_path / "opencode"
+ config_dir.mkdir()
+ registrar = OpencodeRegistrar(config_path=config_dir / "opencode.json")
+ assert registrar.detect() is True
+
+
+def test_detect_when_nothing_present(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ """Detection fails when neither binary nor config dir exists."""
+ monkeypatch.setenv("PATH", "/nonexistent")
+ registrar = OpencodeRegistrar(config_path=tmp_path / "nonexistent" / "opencode.json")
+ assert registrar.detect() is False
+
+
+def test_get_server_returns_none_when_absent(tmp_path: Path) -> None:
+ """get_server returns None when the server is not configured."""
+ registrar = _registrar(tmp_path)
+ assert registrar.get_server("headroom") is None
+
+
+def test_get_server_returns_spec_when_present(tmp_path: Path) -> None:
+ """get_server parses the existing MCP entry correctly."""
+ config = {
+ "mcp": {
+ "headroom": {
+ "type": "remote",
+ "url": "http://127.0.0.1:8787/mcp",
+ "enabled": True,
+ }
+ }
+ }
+ _write_json(tmp_path / "opencode.json", config)
+ registrar = _registrar(tmp_path)
+ spec = registrar.get_server("headroom")
+ assert spec is not None
+ assert spec.name == "headroom"
+
+
+def test_register_server_creates_config_when_missing(tmp_path: Path) -> None:
+ """register_server creates the config file when it doesn't exist."""
+ registrar = _registrar(tmp_path)
+ from headroom.mcp_registry.base import ServerSpec
+
+ spec = ServerSpec(name="headroom", command="headroom", args=("mcp", "serve"))
+ result = registrar.register_server(spec)
+ assert result.status == RegisterStatus.REGISTERED
+ config_path = tmp_path / "opencode.json"
+ assert config_path.exists()
+
+
+def test_register_server_idempotent(tmp_path: Path) -> None:
+ """register_server is a no-op when the same spec is already present."""
+ registrar = _registrar(tmp_path)
+ from headroom.mcp_registry.base import ServerSpec
+
+ spec = ServerSpec(name="headroom", command="headroom", args=("mcp", "serve"))
+ registrar.register_server(spec)
+ result = registrar.register_server(spec)
+ assert result.status == RegisterStatus.ALREADY
+
+
+def test_unregister_server_removes_entry(tmp_path: Path) -> None:
+ """unregister_server removes the server entry."""
+ registrar = _registrar(tmp_path)
+ from headroom.mcp_registry.base import ServerSpec
+
+ spec = ServerSpec(name="headroom", command="headroom", args=("mcp", "serve"))
+ registrar.register_server(spec)
+ assert registrar.unregister_server("headroom") is True
+ assert registrar.get_server("headroom") is None
+
+
+def test_unregister_server_returns_false_when_absent(tmp_path: Path) -> None:
+ """unregister_server returns False when the server was not registered."""
+ registrar = _registrar(tmp_path)
+ assert registrar.unregister_server("headroom") is False
+
+
+def test_specs_equivalent_true() -> None:
+ from headroom.mcp_registry.base import ServerSpec
+
+ a = ServerSpec(name="headroom", command="headroom", args=("mcp", "serve"))
+ b = ServerSpec(name="headroom", command="headroom", args=("mcp", "serve"))
+ assert _specs_equivalent(a, b) is True
+
+
+def test_specs_equivalent_false() -> None:
+ from headroom.mcp_registry.base import ServerSpec
+
+ a = ServerSpec(name="headroom", command="headroom", args=("mcp", "serve"))
+ b = ServerSpec(name="headroom", command="other", args=("mcp", "serve"))
+ assert _specs_equivalent(a, b) is False
+
+
+# ---------------------------------------------------------------------------
+# Edge cases
+# ---------------------------------------------------------------------------
+
+
+def test_register_server_force_overwrites_mismatch(tmp_path: Path) -> None:
+ """register_server with force=True overwrites a mismatched existing server."""
+ registrar = _registrar(tmp_path)
+ from headroom.mcp_registry.base import ServerSpec
+
+ spec_a = ServerSpec(name="headroom", command="old", args=("serve",))
+ spec_b = ServerSpec(name="headroom", command="headroom", args=("mcp", "serve"))
+
+ registrar.register_server(spec_a)
+ assert registrar.register_server(spec_b).status == RegisterStatus.MISMATCH
+ assert registrar.register_server(spec_b, force=True).status == RegisterStatus.REGISTERED
+ updated = registrar.get_server("headroom")
+ assert updated is not None
+ assert updated.command == "headroom"
+
+
+def test_unregister_removes_mcp_key_when_empty(tmp_path: Path) -> None:
+ """unregister_server removes the top-level 'mcp' key when it becomes empty."""
+ registrar = _registrar(tmp_path)
+ from headroom.mcp_registry.base import ServerSpec
+
+ spec = ServerSpec(name="headroom", command="headroom", args=("mcp", "serve"))
+ registrar.register_server(spec)
+ assert registrar.unregister_server("headroom") is True
+ assert registrar.get_server("headroom") is None
+ # mcp key should be removed entirely
+ import json
+ data = json.loads((tmp_path / "opencode.json").read_text())
+ assert "mcp" not in data
+
+
+def test_register_server_leaves_other_mcp_servers(tmp_path: Path) -> None:
+ """register_server preserves other MCP servers in the config."""
+ registrar = _registrar(tmp_path)
+ from headroom.mcp_registry.base import ServerSpec
+
+ # Pre-populate with a user-managed MCP server
+ _write_json(tmp_path / "opencode.json", {
+ "mcp": {
+ "existing-server": {"type": "remote", "url": "https://example.com", "enabled": True},
+ }
+ })
+
+ spec = ServerSpec(name="headroom", command="headroom", args=("mcp", "serve"))
+ registrar.register_server(spec)
+
+ data = json.loads((tmp_path / "opencode.json").read_text())
+ assert "headroom" in data["mcp"]
+ assert "existing-server" in data["mcp"]
+
+
+def test_unregister_preserves_other_mcp_servers(tmp_path: Path) -> None:
+ """unregister_server leaves other MCP servers intact."""
+ registrar = _registrar(tmp_path)
+ from headroom.mcp_registry.base import ServerSpec
+
+ _write_json(tmp_path / "opencode.json", {
+ "mcp": {
+ "existing-server": {"type": "remote", "url": "https://example.com"},
+ }
+ })
+ spec = ServerSpec(name="headroom", command="headroom", args=("mcp", "serve"))
+ registrar.register_server(spec)
+ registrar.unregister_server("headroom")
+
+ data = json.loads((tmp_path / "opencode.json").read_text())
+ assert "headroom" not in data["mcp"]
+ assert "existing-server" in data["mcp"]
+
+
+def test_get_server_returns_none_for_non_dict_mcp(tmp_path: Path) -> None:
+ """get_server returns None when 'mcp' is not a dict."""
+ registrar = _registrar(tmp_path)
+ _write_json(tmp_path / "opencode.json", {"mcp": "not-a-dict"})
+ assert registrar.get_server("headroom") is None
+
+
+def test_get_server_handles_missing_config_file(tmp_path: Path) -> None:
+ """get_server returns None when the config file doesn't exist."""
+ registrar = _registrar(tmp_path)
+ assert registrar.get_server("headroom") is None
+
+
+def test_register_server_handles_config_with_no_mcp_key(tmp_path: Path) -> None:
+ """register_server adds 'mcp' key when it doesn't exist."""
+ registrar = _registrar(tmp_path)
+ _write_json(tmp_path / "opencode.json", {"model": "gpt-4o"})
+ from headroom.mcp_registry.base import ServerSpec
+
+ spec = ServerSpec(name="headroom", command="headroom", args=("mcp", "serve"))
+ registrar.register_server(spec)
+
+ data = json.loads((tmp_path / "opencode.json").read_text())
+ assert data["model"] == "gpt-4o" # preserved
+ assert "headroom" in data["mcp"]
+
+
+def test_register_server_with_env_vars(tmp_path: Path) -> None:
+ """register_server handles ServerSpec with environment variables."""
+ registrar = _registrar(tmp_path)
+ from headroom.mcp_registry.base import ServerSpec
+
+ spec = ServerSpec(
+ name="headroom",
+ command="headroom",
+ args=("mcp", "serve"),
+ env={"HEADROOM_PROXY_URL": "http://127.0.0.1:9090"},
+ )
+ registrar.register_server(spec)
+
+ data = json.loads((tmp_path / "opencode.json").read_text())
+ assert data["mcp"]["headroom"]["env"] == {"HEADROOM_PROXY_URL": "http://127.0.0.1:9090"}
+
+
+def test_register_then_re_register_with_different_env_returns_mismatch(tmp_path: Path) -> None:
+ """Re-registering with different env returns MISMATCH without force."""
+ registrar = _registrar(tmp_path)
+ from headroom.mcp_registry.base import ServerSpec
+
+ spec_a = ServerSpec(name="headroom", command="headroom", args=("mcp", "serve"))
+ spec_b = ServerSpec(
+ name="headroom",
+ command="headroom",
+ args=("mcp", "serve"),
+ env={"NEW_VAR": "value"},
+ )
+ registrar.register_server(spec_a)
+ result = registrar.register_server(spec_b)
+ assert result.status == RegisterStatus.MISMATCH
+
+
+def test_register_server_on_malformed_config_file(tmp_path: Path) -> None:
+ """register_server overwrites a malformed config file, preserving nothing."""
+ registrar = _registrar(tmp_path)
+ (tmp_path / "opencode.json").write_text("not valid json at all")
+ from headroom.mcp_registry.base import ServerSpec
+
+ spec = ServerSpec(name="headroom", command="headroom", args=("mcp", "serve"))
+ result = registrar.register_server(spec)
+ assert result.status == RegisterStatus.REGISTERED
+
+ data = json.loads((tmp_path / "opencode.json").read_text())
+ assert "headroom" in data["mcp"]
+
+
+def test_entry_to_spec_command_as_string() -> None:
+ """_entry_to_spec handles a string command (not a list)."""
+ entry = {
+ "type": "remote",
+ "command": "some-command",
+ "enabled": True,
+ }
+ spec = _entry_to_spec("test", entry)
+ assert spec.name == "test"
+ assert spec.command == "some-command"
+ assert spec.args == ()
+
+
+def test_entry_to_spec_no_command() -> None:
+ """_entry_to_spec handles an entry without a 'command' key."""
+ entry: dict[str, Any] = {
+ "type": "remote",
+ "url": "http://example.com",
+ "enabled": True,
+ }
+ spec = _entry_to_spec("test", entry)
+ assert spec.name == "test"
+ assert spec.command == ""
+
+
+def test_spec_to_entry_roundtrip() -> None:
+ """_spec_to_entry and _entry_to_spec are inverses for local commands."""
+ from headroom.mcp_registry.base import ServerSpec
+
+ original = ServerSpec(
+ name="test",
+ command="python",
+ args=("-m", "server"),
+ env={"KEY": "VAL"},
+ )
+ entry = _spec_to_entry(original)
+ assert entry["type"] == "remote"
+ assert entry["command"] == ["python", "-m", "server"]
+ assert entry["env"] == {"KEY": "VAL"}
+
+ restored = _entry_to_spec("test", entry)
+ assert restored.name == original.name
+ assert restored.command == original.command
+ assert restored.args == original.args
+ assert restored.env == original.env
+
+
+def test_diff_specs_all_fields() -> None:
+ """_diff_specs reports differences in all fields."""
+ from headroom.mcp_registry.base import ServerSpec
+
+ a = ServerSpec(name="s", command="cmd_a", args=("a1",), env={"K": "A"})
+ b = ServerSpec(name="s", command="cmd_b", args=("b1",), env={"K": "B"})
+ diff = _diff_specs(a, b)
+ assert "cmd_a" in diff
+ assert "cmd_b" in diff
+ assert "a1" in diff
+ assert "b1" in diff
+
+
+def test_diff_specs_no_difference_returns_generic_message() -> None:
+ """_diff_specs returns a generic message when no identifiable field differs."""
+ from headroom.mcp_registry.base import ServerSpec
+
+ a = ServerSpec(name="s", command="x")
+ b = ServerSpec(name="s", command="x")
+ diff = _diff_specs(a, b)
+ assert "unidentified field" in diff
+
+
+def test_register_server_returns_already_status(
+ tmp_path: Path,
+) -> None:
+ r = _registrar(tmp_path)
+ from headroom.mcp_registry.base import ServerSpec
+
+ spec = ServerSpec(name="already", command="cmd")
+ r.register_server(spec)
+ result = r.register_server(spec)
+ assert result.status == RegisterStatus.ALREADY
+
+
+def test_unregister_server_handles_oserror(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ r = _registrar(tmp_path)
+ from headroom.mcp_registry.base import ServerSpec
+
+ spec = ServerSpec(name="bad-unregister", command="cmd")
+ r.register_server(spec)
+
+ def _fail_write(*args: Any, **kwargs: Any) -> None:
+ msg = "permission denied"
+ raise OSError(msg)
+
+ monkeypatch.setattr(
+ "headroom.mcp_registry.opencode._write_json", _fail_write
+ )
+ ok = r.unregister_server("bad-unregister")
+ assert ok is False
+
+
+def test_get_all_registrars_includes_opencode() -> None:
+ from headroom.mcp_registry.install import get_all_registrars
+
+ registrars = get_all_registrars()
+ names = [r.name for r in registrars]
+ assert "opencode" in names
diff --git a/tests/test_memory/test_traffic_learner.py b/tests/test_memory/test_traffic_learner.py
index 9ccb4c346..cca523f39 100644
--- a/tests/test_memory/test_traffic_learner.py
+++ b/tests/test_memory/test_traffic_learner.py
@@ -1004,6 +1004,9 @@ def _install_plugin_registry(monkeypatch, plugin):
fake.auto_detect_plugins = lambda: [plugin] if plugin is not None else [] # type: ignore[attr-defined]
fake.get_plugin = lambda agent_type: plugin # type: ignore[attr-defined]
monkeypatch.setitem(sys.modules, "headroom.learn.registry", fake)
+ import headroom.learn as learn_pkg
+
+ monkeypatch.setattr(learn_pkg, "registry", fake, raising=False)
def _make_project(path):
@@ -1022,11 +1025,12 @@ class TestFlushToFile:
db = tmp_path / "memory.db"
_init_db(db)
backend = _FakeBackend(db)
+ project_path = tmp_path.resolve()
learner = TrafficLearner(backend=backend, agent_type="claude", min_evidence=2)
writer = _FakeWriter()
- writer.files_to_return = [tmp_path / "CLAUDE.md"]
- proj = _make_project(str(tmp_path))
+ writer.files_to_return = [project_path / "CLAUDE.md"]
+ proj = _make_project(str(project_path))
plugin = _FakePlugin(roots=[proj], writer=writer)
_install_plugin_registry(monkeypatch, plugin)
@@ -1038,7 +1042,7 @@ class TestFlushToFile:
def mk() -> ExtractedPattern:
return ExtractedPattern(
category=PatternCategory.ENVIRONMENT,
- content=f"Use /usr/bin/python3 at {tmp_path}/main.py",
+ content=f"Use /usr/bin/python3 at {project_path}/main.py",
importance=0.6,
)
@@ -1138,7 +1142,8 @@ class TestFlushToFile:
async def test_unanchored_patterns_dropped(self, tmp_path, monkeypatch):
"""Patterns with no path anchoring are dropped before writer is called."""
writer = _FakeWriter()
- plugin = _FakePlugin(roots=[_make_project(str(tmp_path))], writer=writer)
+ project_path = tmp_path.resolve()
+ plugin = _FakePlugin(roots=[_make_project(str(project_path))], writer=writer)
_install_plugin_registry(monkeypatch, plugin)
learner = TrafficLearner(backend=None, agent_type="claude", min_evidence=1)
@@ -1160,14 +1165,15 @@ class TestFlushToFile:
"""A writer raising should be logged; flush must not bubble the error."""
writer = _FakeWriter()
writer.raise_on_write = True
- plugin = _FakePlugin(roots=[_make_project(str(tmp_path))], writer=writer)
+ project_path = tmp_path.resolve()
+ plugin = _FakePlugin(roots=[_make_project(str(project_path))], writer=writer)
_install_plugin_registry(monkeypatch, plugin)
learner = TrafficLearner(backend=None, agent_type="claude", min_evidence=1)
learner._pattern_counts["h"] = (
ExtractedPattern(
category=PatternCategory.ENVIRONMENT,
- content=f"Use {tmp_path}/tool.py",
+ content=f"Use {project_path}/tool.py",
importance=0.6,
evidence_count=2,
),
diff --git a/tests/test_ml_model_registry_lifecycle.py b/tests/test_ml_model_registry_lifecycle.py
index 23e89b80e..bee430f76 100644
--- a/tests/test_ml_model_registry_lifecycle.py
+++ b/tests/test_ml_model_registry_lifecycle.py
@@ -5,9 +5,18 @@ import sys
from types import SimpleNamespace
from unittest.mock import Mock
+import pytest
+
from headroom.models.ml_models import MLModelRegistry
[email protected](autouse=True)
+def reset_ml_model_registry():
+ MLModelRegistry.reset()
+ yield
+ MLModelRegistry.reset()
+
+
def test_unload_many_removes_requested_keys_once(monkeypatch) -> None:
MLModelRegistry.reset()
registry = MLModelRegistry.get()
diff --git a/tests/test_providers_opencode_config.py b/tests/test_providers_opencode_config.py
new file mode 100644
index 000000000..76eb0b182
--- /dev/null
+++ b/tests/test_providers_opencode_config.py
@@ -0,0 +1,469 @@
+"""Tests for OpenCode config file helpers."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from headroom.providers.opencode.config import (
+ HEADROOM_OPENCODE_PLUGIN,
+ _inject_key_into_json,
+ _parse_json_loose,
+ append_headroom_plugin,
+ inject_opencode_provider_config,
+ opencode_config_paths,
+ snapshot_opencode_config_if_unwrapped,
+ strip_opencode_headroom_blocks,
+)
+
+
+def _set_test_home(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+ home = str(tmp_path)
+ monkeypatch.setenv("HOME", home)
+ monkeypatch.setenv("USERPROFILE", home)
+ monkeypatch.delenv("OPENCODE_HOME", raising=False)
+ monkeypatch.delenv("OPENCODE_CONFIG", raising=False)
+
+
+# ---------------------------------------------------------------------------
+# Config paths
+# ---------------------------------------------------------------------------
+
+
+def test_opencode_config_paths_default(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """Default config path resolves to ~/.config/opencode/opencode.json."""
+ _set_test_home(monkeypatch, tmp_path)
+ config_file, backup_file = opencode_config_paths()
+ assert config_file == tmp_path / ".config" / "opencode" / "opencode.json"
+ assert backup_file == tmp_path / ".config" / "opencode" / "opencode.json.headroom-backup"
+
+
+def test_opencode_config_paths_from_env(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """OPENCODE_CONFIG env var overrides the default path."""
+ custom_path = tmp_path / "custom" / "opencode.json"
+ monkeypatch.setenv("OPENCODE_CONFIG", str(custom_path))
+ config_file, backup_file = opencode_config_paths()
+ assert config_file == custom_path
+ assert backup_file == tmp_path / "custom" / "opencode.json.headroom-backup"
+
+
+# ---------------------------------------------------------------------------
+# Snapshot
+# ---------------------------------------------------------------------------
+
+
+def test_snapshot_creates_backup(tmp_path: Path) -> None:
+ """snapshot creates a backup copy of the config file."""
+ config_file = tmp_path / "opencode.json"
+ backup_file = tmp_path / "opencode.json.headroom-backup"
+ config_file.write_text('{"model": "openai/gpt-4o"}')
+ snapshot_opencode_config_if_unwrapped(config_file, backup_file)
+ assert backup_file.exists()
+ assert backup_file.read_text() == config_file.read_text()
+
+
+def test_snapshot_skips_if_backup_exists(tmp_path: Path) -> None:
+ """snapshot is a no-op when the backup already exists."""
+ config_file = tmp_path / "opencode.json"
+ backup_file = tmp_path / "opencode.json.headroom-backup"
+ config_file.write_text('{"model": "a"}')
+ backup_file.write_text('{"model": "b"}')
+ snapshot_opencode_config_if_unwrapped(config_file, backup_file)
+ assert backup_file.read_text() == '{"model": "b"}'
+
+
+def test_snapshot_skips_if_markers_present(tmp_path: Path) -> None:
+ """snapshot skips if the config already contains Headroom markers."""
+ config_file = tmp_path / "opencode.json"
+ backup_file = tmp_path / "opencode.json.headroom-backup"
+ config_file.write_text('// --- Headroom proxy provider ---\n{}')
+ snapshot_opencode_config_if_unwrapped(config_file, backup_file)
+ assert not backup_file.exists()
+
+
+# ---------------------------------------------------------------------------
+# Strip blocks
+# ---------------------------------------------------------------------------
+
+
+def test_strip_blocks_removes_provider_and_mcp() -> None:
+ """strip removes both provider and MCP blocks."""
+ content = (
+ "// --- Headroom proxy provider ---\n"
+ '{"provider": {}}\n'
+ "// --- end Headroom proxy provider ---\n"
+ "// --- Headroom MCP server ---\n"
+ '{"mcp": {}}\n'
+ "// --- end Headroom MCP server ---\n"
+ '{"model": "openai/gpt-4o"}'
+ )
+ cleaned = strip_opencode_headroom_blocks(content)
+ assert "Headroom" not in cleaned
+ assert '{"model": "openai/gpt-4o"}' in cleaned
+
+
+def test_strip_blocks_preserves_user_content() -> None:
+ """strip leaves user content untouched when no blocks are present."""
+ content = '{"model": "openai/gpt-4o", "provider": {"openai": {}}}'
+ cleaned = strip_opencode_headroom_blocks(content)
+ assert cleaned == content
+
+
+# ---------------------------------------------------------------------------
+# Parse JSON loose
+# ---------------------------------------------------------------------------
+
+
+def test_parse_json_loose_strips_comments() -> None:
+ """_parse_json_loose ignores // comments."""
+ text = '{\n "model": "gpt-4o", // default model\n "provider": {}\n}'
+ data = _parse_json_loose(text)
+ assert data["model"] == "gpt-4o"
+ assert "provider" in data
+
+
+def test_parse_json_loose_returns_empty_on_invalid() -> None:
+ """_parse_json_loose returns empty dict for invalid JSON."""
+ assert _parse_json_loose("not json") == {}
+
+
+# ---------------------------------------------------------------------------
+# Inject key
+# ---------------------------------------------------------------------------
+
+
+def test_inject_key_merges_dicts() -> None:
+ """_inject_key_into_json merges nested dicts."""
+ data = {"provider": {"openai": {}}}
+ data = _inject_key_into_json(data, "provider", {"headroom": {}})
+ assert "openai" in data["provider"]
+ assert "headroom" in data["provider"]
+
+
+def test_inject_key_overwrites_non_dict() -> None:
+ """_inject_key_into_json overwrites when existing value is not a dict."""
+ data = {"model": "gpt-4o"}
+ data = _inject_key_into_json(data, "model", "headroom/claude-sonnet-4-6")
+ assert data["model"] == "headroom/claude-sonnet-4-6"
+
+
+# ---------------------------------------------------------------------------
+# Inject provider config
+# ---------------------------------------------------------------------------
+
+
+def test_inject_provider_config_creates_file(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ """inject_opencode_provider_config creates the config file when missing."""
+ _set_test_home(monkeypatch, tmp_path)
+ inject_opencode_provider_config(port=8787)
+ config_file = tmp_path / ".config" / "opencode" / "opencode.json"
+ assert config_file.exists()
+ config = _parse_json_loose(config_file.read_text())
+ assert config["provider"]["headroom"]["npm"] == "@ai-sdk/openai-compatible"
+ assert "model" not in config # headroom provider is a transparent pass-through
+
+
+def test_inject_provider_config_idempotent(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ """inject_opencode_provider_config is safe to call multiple times."""
+ _set_test_home(monkeypatch, tmp_path)
+ inject_opencode_provider_config(port=8787)
+ inject_opencode_provider_config(port=9999)
+ config_file = tmp_path / ".config" / "opencode" / "opencode.json"
+ config = _parse_json_loose(config_file.read_text())
+ assert config["provider"]["headroom"]["options"]["baseURL"] == "http://127.0.0.1:9999/v1"
+
+
+# ---------------------------------------------------------------------------
+# Edge cases — JSON parsing
+# ---------------------------------------------------------------------------
+
+
+def test_parse_json_loose_handles_valid_json() -> None:
+ """_parse_json_loose returns correct dict for valid JSON without comments."""
+ data = _parse_json_loose('{"model": "gpt-4o", "key": "value"}')
+ assert data == {"model": "gpt-4o", "key": "value"}
+
+
+def test_parse_json_loose_handles_jsonc_with_comments() -> None:
+ """_parse_json_loose strips comments and returns valid data."""
+ text = (
+ '{\n'
+ ' "model": "gpt-4o",\n'
+ ' // this is a comment\n'
+ ' "provider": {}\n'
+ '}'
+ )
+ data = _parse_json_loose(text)
+ assert data["model"] == "gpt-4o"
+ assert data["provider"] == {}
+
+
+def test_parse_json_loose_handles_urls_in_json() -> None:
+ """_parse_json_loose does NOT corrupt URLs containing //."""
+ text = '{"baseURL": "http://127.0.0.1:8787/v1"}'
+ data = _parse_json_loose(text)
+ assert data["baseURL"] == "http://127.0.0.1:8787/v1"
+
+
+def test_parse_json_loose_handles_comments_and_urls() -> None:
+ """_parse_json_loose handles both comments and URLs in the same file."""
+ text = (
+ '{\n'
+ ' // proxy configuration\n'
+ ' "baseURL": "http://127.0.0.1:8787/v1",\n'
+ ' "name": "Headroom // Proxy"\n'
+ '}'
+ )
+ data = _parse_json_loose(text)
+ assert data["baseURL"] == "http://127.0.0.1:8787/v1"
+ assert data["name"] == "Headroom // Proxy"
+
+
+def test_parse_json_loose_returns_empty_on_empty_string() -> None:
+ """_parse_json_loose returns {} for empty input."""
+ assert _parse_json_loose("") == {}
+
+
+def test_parse_json_loose_returns_empty_on_whitespace() -> None:
+ """_parse_json_loose returns {} for whitespace-only input."""
+ assert _parse_json_loose(" \n \t ") == {}
+
+
+def test_parse_json_loose_returns_empty_on_trailing_comma() -> None:
+ """_parse_json_loose returns {} for malformed JSON (trailing comma)."""
+ assert _parse_json_loose('{"model": "gpt-4o",}') == {}
+
+
+def test_parse_json_loose_returns_empty_on_unclosed_brace() -> None:
+ """_parse_json_loose returns {} for malformed JSON (unclosed brace)."""
+ assert _parse_json_loose('{"model": "gpt-4o"') == {}
+
+
+# ---------------------------------------------------------------------------
+# Edge cases — strip blocks
+# ---------------------------------------------------------------------------
+
+
+def test_strip_blocks_handles_empty_string() -> None:
+ """strip_opencode_headroom_blocks returns empty string for empty input."""
+ assert strip_opencode_headroom_blocks("") == ""
+
+
+def test_strip_blocks_handles_whitespace_only() -> None:
+ """strip_opencode_headroom_blocks returns empty string for whitespace input."""
+ assert strip_opencode_headroom_blocks(" \n ") == ""
+
+
+def test_strip_blocks_preserves_non_headroom_jsonc() -> None:
+ """strip_opencode_headroom_blocks preserves JSONC comments not from Headroom."""
+ content = (
+ '// user comment\n'
+ '{"model": "gpt-4o"}\n'
+ '// another user comment\n'
+ )
+ cleaned = strip_opencode_headroom_blocks(content)
+ assert '// user comment' in cleaned
+ assert '{"model": "gpt-4o"}' in cleaned
+
+
+def test_strip_blocks_removes_only_one_of_two_identical_blocks() -> None:
+ """strip_opencode_headroom_blocks removes all provider blocks, not just the first."""
+ from headroom.providers.opencode.config import _PROVIDER_MARKER_END, _PROVIDER_MARKER_START
+ content = (
+ _PROVIDER_MARKER_START + "\nblock1\n" + _PROVIDER_MARKER_END + "\n"
+ + _PROVIDER_MARKER_START + "\nblock2\n" + _PROVIDER_MARKER_END
+ )
+ cleaned = strip_opencode_headroom_blocks(content)
+ assert _PROVIDER_MARKER_START not in cleaned
+ assert "block1" not in cleaned
+ assert "block2" not in cleaned
+
+
+def test_strip_blocks_handles_only_mcp_markers() -> None:
+ """strip_opencode_headroom_blocks also strips MCP markers."""
+ from headroom.providers.opencode.config import _MCP_MARKER_END, _MCP_MARKER_START
+ content = (
+ _MCP_MARKER_START + "\nmcp data\n" + _MCP_MARKER_END
+ )
+ cleaned = strip_opencode_headroom_blocks(content)
+ assert _MCP_MARKER_START not in cleaned
+
+
+# ---------------------------------------------------------------------------
+# Edge cases — inject config
+# ---------------------------------------------------------------------------
+
+
+def test_inject_provider_config_merges_with_existing_mcp(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """inject_opencode_provider_config merges headroom MCP with existing MCP servers."""
+ _set_test_home(monkeypatch, tmp_path)
+ config_file = tmp_path / ".config" / "opencode" / "opencode.json"
+ config_file.parent.mkdir(parents=True, exist_ok=True)
+ config_file.write_text('{"mcp": {"existing-server": {"type": "remote", "url": "https://example.com"}}}')
+
+ inject_opencode_provider_config(port=8787)
+
+ config = json.loads(config_file.read_text())
+ assert "existing-server" in config["mcp"]
+ assert "headroom" in config["mcp"]
+
+
+def test_inject_provider_config_idempotent_with_complex_config(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """inject_opencode_provider_config is idempotent on complex configs."""
+ _set_test_home(monkeypatch, tmp_path)
+ config_file = tmp_path / ".config" / "opencode" / "opencode.json"
+ config_file.parent.mkdir(parents=True, exist_ok=True)
+ config_file.write_text(json.dumps({
+ "model": "openai/gpt-4o",
+ "provider": {"openai": {"models": {"gpt-4o": {}}}},
+ "mcp": {"myserver": {"type": "local", "command": ["echo"]}},
+ }))
+
+ inject_opencode_provider_config(port=8787)
+ inject_opencode_provider_config(port=8787)
+
+ config = json.loads(config_file.read_text())
+ assert "openai" in config["provider"]
+ assert "headroom" in config["provider"]
+ assert "myserver" in config["mcp"]
+ assert "headroom" in config["mcp"]
+
+
+def test_inject_provider_config_preserves_unrelated_top_level_keys(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """inject_opencode_provider_config preserves top-level keys like plugin, permission, etc."""
+ _set_test_home(monkeypatch, tmp_path)
+ config_file = tmp_path / ".config" / "opencode" / "opencode.json"
+ config_file.parent.mkdir(parents=True, exist_ok=True)
+ config_file.write_text(json.dumps({
+ "plugin": ["some-plugin"],
+ "permission": {"bash": {"*": "ask"}},
+ "model": "openai/gpt-4o",
+ }))
+
+ inject_opencode_provider_config(port=8787)
+
+ config = json.loads(config_file.read_text())
+ assert config["plugin"] == ["some-plugin"]
+ assert config["permission"] == {"bash": {"*": "ask"}}
+ assert "headroom" in config.get("provider", {})
+
+
+def test_append_headroom_plugin_adds_plugin_once() -> None:
+ config: dict[str, object] = {"plugin": ["some-plugin"]}
+
+ assert append_headroom_plugin(config) is True
+ assert append_headroom_plugin(config) is False
+
+ assert config["plugin"] == ["some-plugin", HEADROOM_OPENCODE_PLUGIN]
+
+
+def test_append_headroom_plugin_preserves_configured_tuple_entry() -> None:
+ config: dict[str, object] = {
+ "plugin": [[HEADROOM_OPENCODE_PLUGIN, {"proxyUrl": "http://127.0.0.1:8787"}]]
+ }
+
+ assert append_headroom_plugin(config) is False
+ assert config["plugin"] == [
+ [HEADROOM_OPENCODE_PLUGIN, {"proxyUrl": "http://127.0.0.1:8787"}]
+ ]
+
+
+def test_inject_provider_config_no_crash_on_unwriteable_dir(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """inject_opencode_provider_config raises click.ClickException on OSError."""
+
+ import click as click_mod
+ monkeypatch.setenv("HOME", "/nonexistent/path/that/cannot/be/created")
+ try:
+ inject_opencode_provider_config(port=8787)
+ except click_mod.ClickException:
+ pass
+ except OSError:
+ pass
+
+
+# ---------------------------------------------------------------------------
+# Runtime module coverage: build_opencode_config_content, build_launch_env
+# ---------------------------------------------------------------------------
+
+
+def test_build_opencode_config_content_without_mcp() -> None:
+ from headroom.providers.opencode.runtime import build_opencode_config_content
+
+ config = build_opencode_config_content(port=8787, include_mcp=False)
+ assert "provider" in config
+ assert "mcp" not in config
+ assert "model" not in config
+ assert config["plugin"] == [["headroom-opencode", {"proxyUrl": "http://127.0.0.1:8787/v1"}]]
+
+
+def test_build_launch_env_with_project(monkeypatch: pytest.MonkeyPatch) -> None:
+ from headroom.providers.opencode.runtime import build_launch_env
+
+ monkeypatch.delenv("HEADROOM_PROJECT", raising=False)
+ monkeypatch.delenv("OPENAI_BASE_URL", raising=False)
+ monkeypatch.delenv("ANTHROPIC_BASE_URL", raising=False)
+
+ env, display = build_launch_env(
+ port=8787,
+ project="test-proj",
+ include_mcp=False,
+ )
+ assert env["HEADROOM_PROJECT"] == "test-proj"
+ assert "headroom-opencode" in env["OPENCODE_CONFIG_CONTENT"]
+ assert "OPENAI_BASE_URL" not in env
+ assert "ANTHROPIC_BASE_URL" not in env
+
+
+def test_build_launch_env_with_custom_environ() -> None:
+ from headroom.providers.opencode.runtime import build_launch_env
+
+ custom = {
+ "EXISTING_VAR": "keep-me",
+ "OPENAI_BASE_URL": "https://deepseek.example/v1",
+ "ANTHROPIC_BASE_URL": "https://anthropic.example",
+ }
+ env, display = build_launch_env(
+ port=8787,
+ environ=custom,
+ include_mcp=False,
+ )
+ assert env["EXISTING_VAR"] == "keep-me"
+ assert env["OPENAI_BASE_URL"] == "https://deepseek.example/v1"
+ assert env["ANTHROPIC_BASE_URL"] == "https://anthropic.example"
+
+
+def test_proxy_base_url() -> None:
+ from headroom.providers.opencode.runtime import proxy_base_url
+
+ assert proxy_base_url(9000) == "http://127.0.0.1:9000/v1"
+
+
+def test_inject_provider_config_strips_existing_markers(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ _set_test_home(monkeypatch, tmp_path)
+ config_file = tmp_path / ".config" / "opencode" / "opencode.json"
+ config_file.parent.mkdir(parents=True, exist_ok=True)
+
+ inject_opencode_provider_config(port=9000)
+ first = config_file.read_text()
+ assert "headroom" in first
+
+ inject_opencode_provider_config(port=9001)
+ second = config_file.read_text()
+ assert "headroom" in second
+ assert second.count("headroom") == first.count("headroom")
diff --git a/tests/test_providers_opencode_install.py b/tests/test_providers_opencode_install.py
new file mode 100644
index 000000000..e9daa8d55
--- /dev/null
+++ b/tests/test_providers_opencode_install.py
@@ -0,0 +1,112 @@
+"""Tests for OpenCode install-time helpers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from headroom.install.models import ConfigScope, DeploymentManifest
+from headroom.providers.opencode.install import (
+ apply_provider_scope,
+ build_install_env,
+ revert_provider_scope,
+)
+
+
+def _manifest(port: int = 8787) -> DeploymentManifest:
+ return DeploymentManifest(
+ profile="test",
+ preset="persistent-task",
+ runtime_kind="python",
+ supervisor_kind="none",
+ scope=ConfigScope.PROVIDER.value,
+ provider_mode="auto",
+ targets=[],
+ port=port,
+ host="127.0.0.1",
+ backend="anthropic",
+ proxy_args=[],
+ base_env={},
+ tool_envs={},
+ )
+
+
+def test_build_install_env() -> None:
+ """build_install_env leaves OpenCode provider env vars untouched."""
+ env = build_install_env(port=8787, backend="anthropic")
+ assert env == {}
+
+
+def test_apply_provider_scope_creates_config(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """apply_provider_scope creates the opencode config with headroom provider."""
+ home = str(tmp_path)
+ monkeypatch.setenv("HOME", home)
+ monkeypatch.setenv("USERPROFILE", home)
+ monkeypatch.delenv("OPENCODE_HOME", raising=False)
+ monkeypatch.delenv("OPENCODE_CONFIG", raising=False)
+
+ manifest = _manifest(port=8787)
+ mutation = apply_provider_scope(manifest)
+ assert mutation is not None
+ assert mutation.target == "opencode"
+ assert mutation.kind == "json-block"
+
+ config_file = tmp_path / ".config" / "opencode" / "opencode.json"
+ assert config_file.exists()
+ import json
+ config = json.loads(config_file.read_text())
+ assert config["provider"]["headroom"]["options"]["baseURL"] == "http://127.0.0.1:8787/v1"
+
+
+def test_apply_provider_scope_skips_when_scope_is_not_provider(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """apply_provider_scope returns None when scope is not PROVIDER."""
+ manifest = _manifest()
+ manifest.scope = ConfigScope.USER.value
+ result = apply_provider_scope(manifest)
+ assert result is None
+
+
+def test_revert_provider_scope_restores_file(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """revert_provider_scope strips the Headroom block from the config."""
+ home = str(tmp_path)
+ monkeypatch.setenv("HOME", home)
+ monkeypatch.setenv("USERPROFILE", home)
+ monkeypatch.delenv("OPENCODE_HOME", raising=False)
+ monkeypatch.delenv("OPENCODE_CONFIG", raising=False)
+
+ config_file = tmp_path / ".config" / "opencode" / "opencode.json"
+ config_file.parent.mkdir(parents=True, exist_ok=True)
+ config_file.write_text('{"model": "openai/gpt-4o"}')
+
+ from headroom.install.models import ManagedMutation
+ mutation = ManagedMutation(
+ target="opencode",
+ kind="json-block",
+ path=str(config_file),
+ )
+ manifest = _manifest()
+ revert_provider_scope(mutation, manifest)
+ assert config_file.exists()
+ assert config_file.read_text().strip() == '{"model": "openai/gpt-4o"}'
+
+
+def test_revert_provider_scope_noop_when_file_missing(
+ tmp_path: Path,
+) -> None:
+ """revert_provider_scope is a safe no-op when the config file is gone."""
+ from headroom.install.models import ManagedMutation
+ mutation = ManagedMutation(
+ target="opencode",
+ kind="json-block",
+ path=str(tmp_path / "nonexistent.json"),
+ )
+ manifest = _manifest()
+ revert_provider_scope(mutation, manifest)
+ # Should not raise
diff --git a/uv.lock b/uv.lock
index aaafe46bb..e63341b2f 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1449,12 +1449,12 @@ wheels = [
[[package]]
name = "headroom-ai"
-version = "0.25.0"
+version = "0.26.0"
source = { editable = "." }
dependencies = [
{ name = "ast-grep-cli" },
{ name = "click" },
- { name = "litellm" },
+ { name = "litellm", marker = "python_full_version < '3.14'" },
{ name = "opentelemetry-api" },
{ name = "pydantic" },
{ name = "rich" },
@@ -1522,7 +1522,7 @@ dev = [
{ name = "hnswlib" },
{ name = "httpx", extra = ["http2"] },
{ name = "langchain-ollama" },
- { name = "litellm" },
+ { name = "litellm", marker = "python_full_version < '3.14'" },
{ name = "mypy" },
{ name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version < '3.11'" },
{ name = "numpy", version = "2.4.1", source = { registry = "https://pypi.org/simple/" }, marker = "python_full_version >= '3.11'" },
@@ -1679,8 +1679,8 @@ requires-dist = [
{ name = "langchain-core", marker = "extra == 'langchain'", specifier = ">=1.3.3,<4.0" },
{ name = "langchain-ollama", marker = "extra == 'dev'", specifier = ">=0.2.0" },
{ name = "langchain-openai", marker = "extra == 'langchain'", specifier = ">=1.1.14,<2.0" },
- { name = "litellm", specifier = ">=1.86.2,<2.0" },
- { name = "litellm", marker = "extra == 'dev'", specifier = ">=1.86.2,<2.0" },
+ { name = "litellm", marker = "python_full_version < '3.14'", specifier = ">=1.86.2,<2.0" },
+ { name = "litellm", marker = "python_full_version < '3.14' and extra == 'dev'", specifier = ">=1.86.2,<2.0" },
{ name = "lm-eval", extras = ["api"], marker = "extra == 'benchmark'", specifier = ">=0.4.0" },
{ name = "magika", marker = "extra == 'proxy'", specifier = ">=0.6.0" },
{ name = "mcp", marker = "extra == 'mcp'", specifier = ">=1.0.0" },
@@ -2289,18 +2289,18 @@ name = "litellm"
version = "1.88.1"
source = { registry = "https://pypi.org/simple/" }
dependencies = [
- { name = "aiohttp" },
- { name = "click" },
- { name = "fastuuid" },
- { name = "httpx" },
- { name = "importlib-metadata" },
- { name = "jinja2" },
- { name = "jsonschema" },
- { name = "openai" },
- { name = "pydantic" },
- { name = "python-dotenv" },
- { name = "tiktoken" },
- { name = "tokenizers" },
+ { name = "aiohttp", marker = "python_full_version < '3.14'" },
+ { name = "click", marker = "python_full_version < '3.14'" },
+ { name = "fastuuid", marker = "python_full_version < '3.14'" },
+ { name = "httpx", marker = "python_full_version < '3.14'" },
+ { name = "importlib-metadata", marker = "python_full_version < '3.14'" },
+ { name = "jinja2", marker = "python_full_version < '3.14'" },
+ { name = "jsonschema", marker = "python_full_version < '3.14'" },
+ { name = "openai", marker = "python_full_version < '3.14'" },
+ { name = "pydantic", marker = "python_full_version < '3.14'" },
+ { name = "python-dotenv", marker = "python_full_version < '3.14'" },
+ { name = "tiktoken", marker = "python_full_version < '3.14'" },
+ { name = "tokenizers", marker = "python_full_version < '3.14'" },
]
sdist = { url = "https://files.pythonhosted.org/packages/16/ea/f99ececb7f22703fe120f1d8be9ffb749ec9453fbbbbbebc0d6a6b4d7864/litellm-1.88.1.tar.gz", hash = "sha256:89c6b74cc7912d6365793006ff951c0450fe847625008dfe49de8a7dc4529aa5", size = 13885969, upload-time = "2026-06-09T01:06:25.192Z" }
wheels = [