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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
feat: headroom wrap opencode / unwrap opencode CLI (#1105)
Rudimar Ronsonib4571cc346f6
diff --git a/.serena/.gitignore b/.serena/.gitignorenew file mode 100644index 000000000..2e510aff5--- /dev/null+++ b/.serena/.gitignore@@ -0,0 +1,2 @@+/cache+/project.local.ymldiff --git a/.serena/project.yml b/.serena/project.ymlnew file mode 100644index 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.mdnew file mode 100644index 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/Makefileindex 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-e2ediff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.jsonindex 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.mdxnew file mode 100644index 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.mdxindex 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/Dockerfileindex 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/wrapdiff --git a/e2e/wrap/run.py b/e2e/wrap/run.pyindex d6313795f..aeb8b5fdf 100644--- a/e2e/wrap/run.py+++ b/e2e/wrap/run.py@@ -35,6 +35,7 @@ CLINE_PORT = 28892CONTINUE_PORT = 28893GOOSE_PORT = 28894OPENHANDS_PORT = 28895+OPENCODE_PORT = 28896def 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.pyindex 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 nodiff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.pyindex 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_prefixfrom .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) CLIheadroom wrap openhands # OpenHands CLIheadroom 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.pyindex 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.pyindex a0f6a3def..c7a89545b 100644--- a/headroom/install/paths.py+++ b/headroom/install/paths.py@@ -2,6 +2,7 @@from __future__ import annotations+import osimport reimport sysfrom 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.pyindex 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.pyindex 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__.pyindex 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, ServerSpecfrom .claude import ClaudeRegistrarfrom .codex import CodexRegistrarfrom .display import any_succeeded, format_result, format_results+from .opencode import OpencodeRegistrarfrom .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.pyindex 71401051a..86127c190 100644--- a/headroom/mcp_registry/install.py+++ b/headroom/mcp_registry/install.py@@ -7,6 +7,7 @@ from collections.abc import Iterablefrom .base import MCPRegistrar, RegisterResult, RegisterStatus, ServerSpecfrom .claude import ClaudeRegistrarfrom .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.pynew file mode 100644index 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.pyindex 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.pyindex 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) -> HeadroomOdef 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.pyindex 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.pyindex 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__.pynew file mode 100644index 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.pynew file mode 100644index 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 excdiff --git a/headroom/providers/opencode/install.py b/headroom/providers/opencode/install.pynew file mode 100644index 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.pynew file mode 100644index 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, displaydiff --git a/headroom/release_version.py b/headroom/release_version.pyindex 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}")+ returntags = 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}")+ returnif not level:level = determine_bump_level(list_release_commits(root, previous_tag))diff --git a/headroom/telemetry/context.py b/headroom/telemetry/context.pyindex f3494a2b8..1e3c9ae0e 100644--- a/headroom/telemetry/context.py+++ b/headroom/telemetry/context.py@@ -21,7 +21,7 @@ from typing import Anylogger = 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 downstreamdiff --git a/plugins/opencode/.gitignore b/plugins/opencode/.gitignorenew file mode 100644index 000000000..d4d7e3f61--- /dev/null+++ b/plugins/opencode/.gitignore@@ -0,0 +1,3 @@+node_modules+dist+*.logdiff --git a/plugins/opencode/README.md b/plugins/opencode/README.mdnew file mode 100644index 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.0diff --git a/plugins/opencode/hook-shim/handler.js b/plugins/opencode/hook-shim/handler.jsnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.ps1index 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.shindex 64e0f33dd..18edc2e45 100644--- a/scripts/install.sh+++ b/scripts/install.sh@@ -1476,15 +1476,15 @@ main() {returnfi- (($# >= 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 2case "${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";;esacdiff --git a/tests/conftest.py b/tests/conftest.pyindex 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 = Trueyielddiff --git a/tests/test_cli/test_install_cli.py b/tests/test_cli/test_install_cli.pyindex 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.outputdef 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.pynew file mode 100644index 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.pyindex 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) -> Nmonkeypatch.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.pyindex 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.pyindex 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_codexfrom headroom.providers.codex.install import build_install_env as build_codex_install_envfrom headroom.providers.codex.install import revert_provider_scope as revert_codex_provider_scopefrom 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_scopedef _manifest(tmp_path: Path) -> DeploymentManifest:@@ -487,6 +490,88 @@ def test_revert_claude_provider_scope_ignores_missing_settings_file(tmp_path: Parevert_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.pyindex 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 Nonediff --git a/tests/test_mcp_registry_opencode.py b/tests/test_mcp_registry_opencode.pynew file mode 100644index 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 namesdiff --git a/tests/test_memory/test_traffic_learner.py b/tests/test_memory/test_traffic_learner.pyindex 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.pyindex 23e89b80e..bee430f76 100644--- a/tests/test_ml_model_registry_lifecycle.py+++ b/tests/test_ml_model_registry_lifecycle.py@@ -5,9 +5,18 @@ import sysfrom types import SimpleNamespacefrom 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.pynew file mode 100644index 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.pynew file mode 100644index 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 raisediff --git a/uv.lock b/uv.lockindex 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 = [