Files
headroom/tests/test_providers_opencode_config.py
66e0086952 feat(opencode): add repeatable --extra-model flag for custom wrap-time models (#2364)
## Description

`headroom wrap opencode` injects a hardcoded model list
(`HEADROOM_OPENCODE_MODELS`) into the `headroom` provider block of
`opencode.json`. There's no way to add custom models (for example a
free-tier DeepSeek) at wrap time. Hand-patching `opencode.json` is the
only workaround, and the next wrap overwrites it.

This PR adds a repeatable `--extra-model` flag and a
`HEADROOM_OPENCODE_EXTRA_MODELS` env var. Both take
`id[=name[=context_window[=output_limit]]]` specs. Extra models are
merged into the injected provider block alongside the built-ins, and
flag specs win over env specs on id collision. `name` defaults to the
id, `context_window` to 200000, and `output_limit` to `min(16384,
context_window)`.

Fields are separated by `=` rather than `:` because model ids routinely
contain `:`. Ollama ids are `name:tag` (`qwen2.5-coder:7b`), and
OpenRouter free-tier ids end in `:free`. With a `:` separator those were
silently cut down to a different id (Devin review, 2026-10-03).

The PR also fixes the wrap/unwrap lifecycle the flag depends on. A wrap
that starts without an `opencode.json` used to write the file with no
backup and no record of what Headroom put in it, so `headroom unwrap
opencode` left the injected models and the proxy base URL behind while
reporting that OpenCode was no longer routed through Headroom, and a
re-wrap under `--openai-api-url` kept an extra model Headroom had
injected but no longer advertised. Wrap now records what it owns in
`opencode.json.headroom-managed.json`, and unwrap uses that record: it
removes the model ids and the base URL Headroom wrote, keeps everything
else in the file, drops an extra model that is no longer requested, and
deletes the config file when Headroom created it and nothing else is
left in it.

Closes #2359

## Type of Change

- [x] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- [x] Documentation update
- [ ] Refactoring (no functional changes)

## Changes Made

- `headroom/providers/opencode/config.py`:
- New `parse_extra_model_spec()`, which splits on `=` with an optional
fourth `output_limit` field and raises `ValueError` on an empty id or a
non-integer / non-positive limit.
- New `extra_models_from_env()`, which reads comma-separated specs from
`HEADROOM_OPENCODE_EXTRA_MODELS`.
- An `extra_models` parameter threaded through
`headroom_provider_entry()`, `_render_provider_block()` and
`inject_opencode_provider_config()`.
- With `keep_user_entries` (#3125's `--openai-api-url` gate),
`--extra-model` entries win over a kept user entry with the same id.
- New managed-state sidecar (`opencode.json.headroom-managed.json`)
recording the model ids and base URL Headroom injected and whether
Headroom created the config file. `inject_opencode_provider_config()`
writes it on every injection; `record_opencode_config_origin()` marks a
config that Headroom creates because none existed.
- `remove_managed_opencode_provider()` drops the recorded model ids, the
recorded base URL, and the provider block once nothing else is left in
it. Entries the user added or edited are preserved.
- `_drop_stale_managed_models()` prunes an extra model Headroom injected
but no longer advertises, including an extra that overrode a built-in id
and is dropped again, so a re-wrap without the flag restores the
built-in defaults rather than keeping the old override.
- `snapshot_opencode_config_if_unwrapped()` no longer snapshots a config
Headroom wrote itself as pre-wrap content.
- `headroom/providers/opencode/runtime.py`: extras also reach the
launch-time `OPENCODE_CONFIG_CONTENT`.
- `headroom/cli/wrap.py`:
- A repeatable `--extra-model` option on `wrap opencode`. Env and flag
specs are parsed up front, and a malformed spec raises
`click.BadParameter`. The merged dict goes to both
`inject_opencode_provider_config` call sites (prepare-only and launch)
and to the launch env. Also adds a help text and docstring example.
- `wrap opencode` records the config origin before the first config
mutation.
- `unwrap opencode` undoes the recorded provider entries when there is
no pre-wrap backup, keeps the rest of the file, and removes a config
Headroom created once nothing Headroom-owned is left in it.
- `docs/content/docs/opencode.mdx`: new "Adding models" subsection
(format, defaults, Ollama/OpenRouter example, built-in id override, the
env var's no-comma limitation) and an env-var table row. The subsection
and the "How It Works Under The Hood" unwrap step now describe the
managed-state record and the automatic cleanup it enables.
- Tests:
- Spec parsing: full spec with output, defaults, the output cap at small
contexts, colon-bearing ids (`qwen2.5-coder:7b`,
`deepseek/deepseek-chat:free`, a name containing `:`), and invalid specs
including a bad output limit.
- Env parsing, provider-entry merge, and end-to-end inject. Also
@JerrettDavis's collision test across both `keep_user_entries` values.
- CLI: the flag reaches `opencode.json`, the env var persists, both
reach `OPENCODE_CONFIG_CONTENT` on launch, the flag wins over a kept
user entry under `--openai-api-url`, and a malformed spec exits with a
usage error.
- Managed state: the sidecar records the injected ids and base URL, a
config the user already had is not marked as Headroom-created, a re-wrap
does not snapshot Headroom's own config, a dropped extra model is pruned
(including an override of a built-in id, which returns to the built-in
defaults), a user model and a user-edited model survive, and the
provider removal keeps unrelated user entries.
- Lifecycle: a fresh wrap followed by an unwrap removes the config file
again (with and without the MCP entry), user content added after a fresh
wrap survives the unwrap, a re-wrap without the extra model drops the
stale one, and a directly injected provider entry is undone by the
unwrap callback as well.
- A user setting that is false, zero or an empty string is content, not
an empty section: such a setting survives the unwrap instead of costing
the user the whole file.

## Testing

- [x] Unit tests pass locally
- [x] Lint/format/type checks pass locally
- [x] New tests added for new functionality

The new parsing tests fail against the previous `:`-based parser:

```text
FAILED tests/test_providers_opencode_config.py::test_parse_extra_model_spec_keeps_colons_in_ids[qwen2.5-coder:7b-...]
FAILED tests/test_providers_opencode_config.py::test_parse_extra_model_spec_keeps_colons_in_ids[deepseek/deepseek-chat:free=DeepSeek Free-...]
FAILED tests/test_providers_opencode_config.py::test_parse_extra_model_spec_full
...
================ 21 failed, 2 passed, 103 deselected in 0.86s =================
```

With this branch (head 6be848942):

```text
$ pytest tests/test_providers_opencode_config.py tests/test_cli/test_wrap_opencode.py -q
179 passed, 2 skipped in 3.31s

$ pytest tests -q -k "opencode"
322 passed, 26 skipped

$ ruff check headroom/providers/opencode/config.py headroom/cli/wrap.py tests/test_providers_opencode_config.py tests/test_cli/test_wrap_opencode.py
All checks passed!
$ ruff format --check (same files)
4 files already formatted
$ mypy headroom --ignore-missing-imports --no-site-packages
headroom\fileperms.py:92: error: Module has no attribute "fchmod"; maybe "chmod"?  [attr-defined]
headroom\proxy\interceptors\astgrep.py:220: error: Module has no attribute "O_DIRECTORY"  [attr-defined]
...
Found 7 errors in 2 files (checked 561 source files)
```

The mypy errors are the Windows-only `os.fchmod` / `os.O_DIRECTORY`
false positives in files this PR does not touch. The same Windows
path-escaping failures that `test_build_launch_env_with_project` used to
hit (`tests/test_cli/test_unwrap_claude.py`,
`tests/test_wrap_code_memory.py`, `tests/test_install/test_planner.py`,
`tests/test_cli/test_wrap_stale_marker.py`) reproduce on unchanged
`main` and are unrelated to this change. `Dependency audit (pip-audit)`
passes on this head; only `Rust advisories (cargo audit)` fails, on
advisories published after upstream `main`'s last green run (2026-11-13
04:47) — `quinn-udp` `RUSTSEC-2026-0538` and `rustix`
`RUSTSEC-2026-0486`. `Cargo.lock` on this branch is byte-identical to
upstream `main` (`81818d49`), so the PR does not introduce them.

## Real Behavior Proof

- Environment: Windows 11, Python 3.13, this branch vs. the previous
`:`-based parser and vs. the previous unwrap lifecycle,
`HOME`/`USERPROFILE` pointed at a temp dir.
- Exact command / steps: `headroom wrap opencode --prepare-only
--no-serena --extra-model "qwen2.5-coder:7b" --extra-model
"deepseek/deepseek-chat:free=DeepSeek Free=65536"`, then read
`provider.headroom.models` from `~/.config/opencode/opencode.json`; then
`headroom unwrap opencode --no-stop-proxy` against a config that did not
exist before the wrap.
- Observed result: with the old parser the entries were `qwen2.5-coder`
(name `7b`) and `deepseek/deepseek-chat` (name `free=DeepSeek
Free=65536`, context 200000): wrong ids, and the paid DeepSeek model
instead of the free one. With this branch they're `qwen2.5-coder:7b`
(name defaults to the id, context 200000, output 16384) and
`deepseek/deepseek-chat:free` (name `DeepSeek Free`, context 65536,
output 16384), next to the built-in `gpt-4o` / `gpt-4.1`. After the
unwrap of a fresh wrap, `opencode.json` and its managed-state sidecar
are both gone and no `provider.headroom` block is left. After the unwrap
of a fresh wrap the user had added to, the file keeps the user's own
model id, key and `theme`, and only the injected ids and the
`http://127.0.0.1:8787/v1` base URL are gone.
- Not tested: a full (non-prepare-only) wrap launching the real OpenCode
binary against a live upstream; the OpenCode TS plugin side (extras are
user-supplied and intentionally not synced into
`plugins/opencode/src/provider.ts` `DEFAULT_MODELS`).

## Runtime Rollout Safety

- Rollout-managed feature(s): none; CLI-only opt-in flag and env var on
`headroom wrap opencode`, plus a `opencode.json.headroom-managed.json`
sidecar next to the OpenCode config
- Minimum rollout channel: stable
- Stable/default behavior changed: no. Without `--extra-model` or
`HEADROOM_OPENCODE_EXTRA_MODELS` the injected provider block is
unchanged. `unwrap opencode` now also removes the provider entries
Headroom recorded, which is what it already reported doing
- Kill switch / disable path: drop the flag and unset
`HEADROOM_OPENCODE_EXTRA_MODELS`, then re-wrap; delete the sidecar to
stop Headroom from tracking the config
- Unsafe override required: no
- Qualification impact: none; no proxy, compression or request-path code
changed
- Rollback path: revert the PR; `headroom unwrap opencode` restores the
pre-wrap `opencode.json` when a backup exists

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/2364"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-11-17 02:38:10 +05:30

1255 lines
49 KiB
Python

"""Tests for OpenCode config file helpers."""
from __future__ import annotations
import json
from pathlib import Path
import click
import pytest
from headroom.providers.opencode.config import (
HEADROOM_OPENCODE_EXTRA_MODELS_ENV,
HEADROOM_OPENCODE_MODELS,
HEADROOM_OPENCODE_PLUGIN,
_inject_key_into_json,
_parse_json_loose,
extra_models_from_env,
headroom_provider_entry,
inject_opencode_provider_config,
opencode_config_paths,
parse_extra_model_spec,
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"
def test_opencode_config_paths_default_jsonc(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""Default config path resolves to opencode.jsonc when it exists."""
_set_test_home(monkeypatch, tmp_path)
base_dir = tmp_path / ".config" / "opencode"
base_dir.mkdir(parents=True, exist_ok=True)
jsonc_path = base_dir / "opencode.jsonc"
jsonc_path.write_text("{}")
config_file, backup_file = opencode_config_paths()
assert config_file == jsonc_path
assert backup_file == base_dir / "opencode.jsonc.headroom-backup"
def test_opencode_config_paths_env_overrides_jsonc(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""OPENCODE_CONFIG takes precedence even if opencode.jsonc exists."""
_set_test_home(monkeypatch, tmp_path)
base_dir = tmp_path / ".config" / "opencode"
base_dir.mkdir(parents=True, exist_ok=True)
jsonc_path = base_dir / "opencode.jsonc"
jsonc_path.write_text("{}")
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"
# Bare model ids: OpenCode resolves them as "headroom/<id>" (#1657).
models = config["provider"]["headroom"]["models"]
assert set(models) == {"gpt-4o", "gpt-4.1"}
# The injected provider is OpenAI-compatible. Claude models must remain on
# OpenCode's native Anthropic provider so they are not sent to OpenAI.
assert not any(model_id.startswith("claude-") for model_id in models)
assert all(not model_id.startswith("headroom/") for model_id in models)
assert "mcp" not in config
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"
def test_inject_provider_config_keeps_the_users_models_and_options(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""A third-party upstream needs its own model ids and key under `headroom`.
OpenCode only resolves `headroom/<id>` for listed ids, so wiping the user's
entries made `wrap opencode --openai-api-url ...` unusable for DeepSeek.
"""
_set_test_home(monkeypatch, tmp_path)
config_file = tmp_path / ".config" / "opencode" / "opencode.json"
config_file.parent.mkdir(parents=True)
config_file.write_text(
json.dumps(
{
"provider": {
"headroom": {
"npm": "something-else",
"options": {
"apiKey": "{env:DEEPSEEK_API_KEY}",
"baseURL": "https://api.deepseek.com/v1",
},
"models": {"deepseek-chat": {"name": "DeepSeek Chat"}},
},
"anthropic": {"options": {"timeout": 5}},
}
}
),
encoding="utf-8",
)
inject_opencode_provider_config(port=8787, keep_user_entries=True)
inject_opencode_provider_config(port=9999, keep_user_entries=True)
config = _parse_json_loose(config_file.read_text())
headroom = config["provider"]["headroom"]
# Headroom still owns how the provider reaches the proxy.
assert headroom["npm"] == "@ai-sdk/openai-compatible"
assert headroom["options"]["baseURL"] == "http://127.0.0.1:9999/v1"
# The user's key and model ids survive alongside Headroom's defaults.
assert headroom["options"]["apiKey"] == "{env:DEEPSEEK_API_KEY}"
assert set(headroom["models"]) == {"deepseek-chat", "gpt-4o", "gpt-4.1"}
assert headroom["models"]["deepseek-chat"] == {"name": "DeepSeek Chat"}
assert config["provider"]["anthropic"] == {"options": {"timeout": 5}}
def test_inject_provider_config_drops_user_entries_without_an_explicit_upstream(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""Without a named upstream the proxy forwards to OpenAI, so a kept key would go there."""
_set_test_home(monkeypatch, tmp_path)
config_file = tmp_path / ".config" / "opencode" / "opencode.json"
config_file.parent.mkdir(parents=True)
config_file.write_text(
json.dumps(
{
"provider": {
"headroom": {
"npm": "something-else",
"options": {
"apiKey": "{env:DEEPSEEK_API_KEY}",
"baseURL": "https://api.deepseek.com/v1",
},
"models": {"deepseek-chat": {"name": "DeepSeek Chat"}},
},
"anthropic": {"options": {"timeout": 5}},
}
}
),
encoding="utf-8",
)
inject_opencode_provider_config(port=8787)
headroom = _parse_json_loose(config_file.read_text())["provider"]["headroom"]
assert "apiKey" not in headroom["options"]
assert set(headroom["models"]) == {"gpt-4o", "gpt-4.1"}
# ---------------------------------------------------------------------------
# Extra models
# ---------------------------------------------------------------------------
def test_parse_extra_model_spec_full() -> None:
"""Full id=name=context=output spec parses into a provider models entry."""
model_id, entry = parse_extra_model_spec("deepseek-v4-pro=DeepSeek V4=1000000=384000")
assert model_id == "deepseek-v4-pro"
assert entry == {"name": "DeepSeek V4", "limit": {"context": 1000000, "output": 384000}}
def test_parse_extra_model_spec_defaults() -> None:
"""Name defaults to the id, context to 200000, output to min(16384, context)."""
model_id, entry = parse_extra_model_spec("deepseek-chat")
assert model_id == "deepseek-chat"
assert entry == {"name": "deepseek-chat", "limit": {"context": 200000, "output": 16384}}
_, named = parse_extra_model_spec("deepseek-chat=DeepSeek Chat=65536")
assert named == {"name": "DeepSeek Chat", "limit": {"context": 65536, "output": 16384}}
# A context window below the default output caps the output, and an empty
# name field still falls back to the id.
_, small = parse_extra_model_spec("small-model==8192")
assert small == {"name": "small-model", "limit": {"context": 8192, "output": 8192}}
@pytest.mark.parametrize(
("spec", "expected_id", "expected_name"),
[
("qwen2.5-coder:7b", "qwen2.5-coder:7b", "qwen2.5-coder:7b"),
(
"deepseek/deepseek-chat:free=DeepSeek Free",
"deepseek/deepseek-chat:free",
"DeepSeek Free",
),
("deepseek-r1:14b=DeepSeek R1: 14B=65536", "deepseek-r1:14b", "DeepSeek R1: 14B"),
],
)
def test_parse_extra_model_spec_keeps_colons_in_ids(
spec: str, expected_id: str, expected_name: str
) -> None:
"""Ollama (`name:tag`) and OpenRouter (`:free`) ids keep their colons."""
model_id, entry = parse_extra_model_spec(spec)
assert model_id == expected_id
assert entry["name"] == expected_name
@pytest.mark.parametrize(
"spec",
[
"",
"=name=1000",
"id=name=abc",
"id=name=0",
"id=name=1000=abc",
"id=name=1000=-1",
"id=n=1=2=3",
],
)
def test_parse_extra_model_spec_invalid(spec: str) -> None:
"""Empty id or a bad context window / output limit raises ValueError."""
with pytest.raises(ValueError):
parse_extra_model_spec(spec)
def test_extra_models_from_env(monkeypatch: pytest.MonkeyPatch) -> None:
"""HEADROOM_OPENCODE_EXTRA_MODELS parses comma-separated specs."""
monkeypatch.setenv(
HEADROOM_OPENCODE_EXTRA_MODELS_ENV,
"deepseek-chat=DeepSeek Chat=65536, qwen2.5-coder:7b",
)
models = extra_models_from_env()
assert models["deepseek-chat"]["limit"]["context"] == 65536
assert models["qwen2.5-coder:7b"]["name"] == "qwen2.5-coder:7b"
monkeypatch.delenv(HEADROOM_OPENCODE_EXTRA_MODELS_ENV)
assert extra_models_from_env() == {}
def test_headroom_provider_entry_merges_extra_models() -> None:
"""Extra models are merged alongside the built-in model list."""
_, entry = parse_extra_model_spec("deepseek-chat=DeepSeek Chat=65536")
provider = headroom_provider_entry(8787, {"deepseek-chat": entry})
assert "gpt-4o" in provider["models"]
assert provider["models"]["deepseek-chat"]["name"] == "DeepSeek Chat"
def test_inject_provider_config_with_extra_models(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""inject_opencode_provider_config writes extra models into the config."""
_set_test_home(monkeypatch, tmp_path)
_, entry = parse_extra_model_spec("deepseek-chat=DeepSeek Chat=65536")
inject_opencode_provider_config(port=8787, extra_models={"deepseek-chat": entry})
config_file = tmp_path / ".config" / "opencode" / "opencode.json"
config = _parse_json_loose(config_file.read_text())
models = config["provider"]["headroom"]["models"]
assert models["deepseek-chat"]["limit"]["context"] == 65536
assert "gpt-4o" in models
def test_build_opencode_config_content_with_extra_models() -> None:
"""build_opencode_config_content threads extra models into the headroom provider."""
from headroom.providers.opencode.runtime import build_opencode_config_content
_, entry = parse_extra_model_spec("deepseek-chat=DeepSeek Chat=65536")
config = build_opencode_config_content(
port=8787, include_mcp=False, include_plugin=False, extra_models={"deepseek-chat": entry}
)
models = config["provider"]["headroom"]["models"]
assert models["deepseek-chat"]["name"] == "DeepSeek Chat"
assert "gpt-4o" in models
# ---------------------------------------------------------------------------
# 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_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_preserves_existing_mcp(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""inject_opencode_provider_config preserves MCP without adding headroom."""
_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" not 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" not 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_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(
monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
from headroom.providers.opencode.runtime import build_opencode_config_content
plugin = tmp_path / "headroom-plugin"
plugin.mkdir()
(plugin / "index.js").write_text("export default {}", encoding="utf-8")
monkeypatch.setenv("HEADROOM_OPENCODE_PLUGIN_PATH", str(plugin))
config = build_opencode_config_content(port=8787, include_mcp=False)
assert "mcp" not in config
assert "model" not in config
# Native providers are pointed at the proxy so traffic routes through Headroom.
providers = config["provider"]
assert providers["anthropic"]["options"]["baseURL"] == "http://127.0.0.1:8787/v1"
assert providers["openai"]["options"]["baseURL"] == "http://127.0.0.1:8787/v1"
# The headroom provider exposes only models supported by its
# OpenAI-compatible endpoint so "headroom/<id>" resolves safely (#1657).
assert providers["headroom"]["options"]["baseURL"] == "http://127.0.0.1:8787/v1"
models = providers["headroom"]["models"]
assert set(models) == {"gpt-4o", "gpt-4.1"}
assert not any(model_id.startswith("claude-") for model_id in models)
assert all(not model_id.startswith("headroom/") for model_id in models)
# The transport plugin directory is injected by absolute path (opencode loads it directly).
assert config["plugin"] == [str(plugin)]
def test_build_opencode_config_content_skips_plugin_when_unbuilt(
monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
from headroom.providers.opencode.runtime import build_opencode_config_content
# An override pointing at a missing file resolves to None → no plugin entry,
# but native-provider routing still applies (the pip-only fallback).
monkeypatch.setenv("HEADROOM_OPENCODE_PLUGIN_PATH", str(tmp_path / "missing.js"))
config = build_opencode_config_content(port=8787)
assert "plugin" not in config
assert config["provider"]["anthropic"]["options"]["baseURL"] == "http://127.0.0.1:8787/v1"
def test_build_opencode_config_content_with_mcp_uses_local_stdio() -> None:
from headroom.providers.opencode.runtime import build_opencode_config_content
config = build_opencode_config_content(port=9000, include_mcp=True)
assert config["mcp"]["headroom"] == {
"type": "local",
"command": ["headroom", "mcp", "serve"],
"enabled": True,
"environment": {"HEADROOM_PROXY_URL": "http://127.0.0.1:9000"},
}
def test_build_launch_env_with_project(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> 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)
plugin = tmp_path / "headroom-plugin"
plugin.mkdir()
(plugin / "index.js").write_text("export default {}", encoding="utf-8")
monkeypatch.setenv("HEADROOM_OPENCODE_PLUGIN_PATH", str(plugin))
env, display = build_launch_env(
port=8787,
project="test-proj",
include_mcp=False,
)
assert env["HEADROOM_PROJECT"] == "test-proj"
# Plugin loaded → its proxy target is exported for self-configuration.
assert env["HEADROOM_PROXY_URL"] == "http://127.0.0.1:8787"
# Compare the decoded entry: JSON escapes Windows backslashes, so the raw
# path is not a substring of the serialized text there.
assert json.loads(env["OPENCODE_CONFIG_CONTENT"])["plugin"] == [str(plugin)]
assert f"plugin={HEADROOM_OPENCODE_PLUGIN}" in display
assert "OPENAI_BASE_URL" not in env
assert "ANTHROPIC_BASE_URL" not in env
def test_build_launch_env_forwards_session_token_when_plugin_present(
monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
"""Token reaches OpenCode only via the transport plugin -- the only
header-capable layer (native baseURL is header-blind, like Cursor)."""
from headroom.providers.opencode.runtime import build_launch_env
plugin = tmp_path / "entry.opencode.js"
plugin.write_text("export default () => {}", encoding="utf-8")
monkeypatch.setenv("HEADROOM_OPENCODE_PLUGIN_PATH", str(plugin))
env, _display = build_launch_env(
port=8787,
include_mcp=False,
session_token="tok-abc",
)
assert env["HEADROOM_OPENCODE_SESSION_TOKEN"] == "tok-abc"
def test_build_launch_env_omits_session_token_when_plugin_absent(
monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
"""No plugin -> no header surface -> token must not be forwarded,
same as Cursor's UNKNOWN."""
from headroom.providers.opencode.runtime import build_launch_env
monkeypatch.setenv("HEADROOM_OPENCODE_PLUGIN_PATH", str(tmp_path / "missing.js"))
env, _display = build_launch_env(
port=8787,
include_mcp=False,
session_token="tok-abc",
)
assert "HEADROOM_OPENCODE_SESSION_TOKEN" 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")
@pytest.mark.parametrize("keep_user_entries", [False, True])
def test_extra_models_override_persisted_collision_with_upstream_gate(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, keep_user_entries: bool
) -> None:
_set_test_home(monkeypatch, tmp_path)
config_file = tmp_path / ".config" / "opencode" / "opencode.json"
config_file.parent.mkdir(parents=True)
config_file.write_text(
json.dumps(
{
"provider": {
"headroom": {
"options": {
"apiKey": "third-party-secret",
"baseURL": "https://old.invalid",
},
"models": {
"deepseek-chat": {"name": "Old model"},
"private-model": {"name": "Private"},
},
}
}
}
),
encoding="utf-8",
)
_, entry = parse_extra_model_spec("deepseek-chat=DeepSeek Chat=65536")
inject_opencode_provider_config(
port=8787, extra_models={"deepseek-chat": entry}, keep_user_entries=keep_user_entries
)
provider = json.loads(config_file.read_text(encoding="utf-8"))["provider"]["headroom"]
assert provider["models"]["deepseek-chat"] == entry
assert provider["options"]["baseURL"] == "http://127.0.0.1:8787/v1"
assert ("private-model" in provider["models"]) is keep_user_entries
assert ("apiKey" in provider["options"]) is keep_user_entries
if keep_user_entries:
assert provider["options"]["apiKey"] == "third-party-secret"
# ---------------------------------------------------------------------------
# OpenCode 2.x --standalone launch flag
# ---------------------------------------------------------------------------
@pytest.mark.parametrize(
("stdout", "returncode", "expected"),
[
("opencode v2.0.12\n", 0, 2),
("1.18.32\n", 0, 1),
("opencode v0.0.0-v2-202610061051\n", 0, 2),
("0.0.0-dev-202610060234\n", 0, 0),
("garbage\n", 0, None),
("opencode v2.0.12\n", 1, None),
],
)
def test_opencode_major_version_parses_both_cli_formats(
monkeypatch: pytest.MonkeyPatch, stdout: str, returncode: int, expected: int | None
) -> None:
import subprocess
import headroom.providers.opencode.runtime as oc_runtime
def fake_run(*args, **kwargs): # noqa: ANN002, ANN003
return subprocess.CompletedProcess(args[0], returncode, stdout=stdout, stderr="")
monkeypatch.setattr(oc_runtime, "run", fake_run)
assert oc_runtime.opencode_major_version("opencode") == expected
def test_opencode_major_version_missing_binary_is_unknown(tmp_path: Path) -> None:
from headroom.providers.opencode.runtime import opencode_major_version
assert opencode_major_version(str(tmp_path / "no-such-opencode")) is None
@pytest.mark.parametrize(
("args", "expected"),
[
((), ("--standalone",)),
(("--continue",), ("--standalone", "--continue")),
(("run", "fix it"), ("run", "--standalone", "fix it")),
(("--print-logs", "mini"), ("--print-logs", "mini", "--standalone")),
(("models",), ("models",)),
(("auth", "list"), ("auth", "list")),
(("--session", "models"), ("--standalone", "--session", "models")),
(("--prompt", "models", "extra"), ("--standalone", "--prompt", "models", "extra")),
(("-s", "stats"), ("--standalone", "-s", "stats")),
(("run", "--agent", "models"), ("run", "--standalone", "--agent", "models")),
(("--standalone",), ("--standalone",)),
(
("run", "--server", "http://127.0.0.1:4096", "x"),
("run", "--server", "http://127.0.0.1:4096", "x"),
),
(("--server=http://127.0.0.1:4096",), ("--server=http://127.0.0.1:4096",)),
],
)
def test_with_opencode_standalone_on_v2(args: tuple[str, ...], expected: tuple[str, ...]) -> None:
from headroom.providers.opencode.runtime import with_opencode_standalone
assert with_opencode_standalone(args, 2) == expected
@pytest.mark.parametrize("major", [1, None])
def test_with_opencode_standalone_leaves_v1_and_unknown_alone(major: int | None) -> None:
from headroom.providers.opencode.runtime import with_opencode_standalone
assert with_opencode_standalone(("run", "fix it"), major) == ("run", "fix it")
@pytest.mark.parametrize("conflict", ["canonical", "sibling"])
def test_jsonc_migration_treats_dangling_conflict_as_ambiguous(
tmp_path: Path, conflict: str
) -> None:
from headroom.providers.opencode.config import migrate_legacy_opencode_jsonc_backup
config = tmp_path / "opencode.jsonc"
canonical = config.with_name(config.name + ".headroom-backup")
legacy = config.with_suffix(".json.headroom-backup")
original = b'{"theme":"unrelated legacy"}\n'
legacy.write_bytes(original)
conflicting_path = canonical if conflict == "canonical" else config.with_suffix(".json")
try:
conflicting_path.symlink_to(tmp_path / "missing-target")
except OSError:
pytest.skip("creating symlinks requires platform permissions")
migrate_legacy_opencode_jsonc_backup(config, canonical)
assert conflicting_path.is_symlink()
assert legacy.read_bytes() == original
conflicting_path.unlink()
migrate_legacy_opencode_jsonc_backup(config, canonical)
assert not canonical.exists()
assert legacy.read_bytes() == original
# ---------------------------------------------------------------------------
# Managed state (what Headroom owns in the config file)
# ---------------------------------------------------------------------------
def _managed_state_path(config_file: Path) -> Path:
return config_file.with_name(config_file.name + ".headroom-managed.json")
def test_inject_provider_config_records_managed_state(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""The sidecar records the model ids and baseURL Headroom injected."""
_set_test_home(monkeypatch, tmp_path)
config_file = tmp_path / ".config" / "opencode" / "opencode.json"
inject_opencode_provider_config(port=8787, extra_models={"my-model": {"name": "My Model"}})
state = json.loads(_managed_state_path(config_file).read_text(encoding="utf-8"))
assert state["created_file"] is True
assert state["managed_base_url"] == "http://127.0.0.1:8787/v1"
assert set(state["managed_models"]) == {"gpt-4o", "gpt-4.1", "my-model"}
def test_inject_provider_config_keeps_existing_file_out_of_created_file(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""A config the user already had is not marked as Headroom-created."""
_set_test_home(monkeypatch, tmp_path)
config_file = tmp_path / ".config" / "opencode" / "opencode.json"
config_file.parent.mkdir(parents=True)
config_file.write_text('{"theme": "dark"}', encoding="utf-8")
inject_opencode_provider_config(port=8787)
state = json.loads(_managed_state_path(config_file).read_text(encoding="utf-8"))
assert state["created_file"] is False
def test_snapshot_skips_a_config_headroom_wrote(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""A re-wrap must not snapshot Headroom's own config as pre-wrap content."""
_set_test_home(monkeypatch, tmp_path)
config_file = tmp_path / ".config" / "opencode" / "opencode.json"
inject_opencode_provider_config(port=8787)
backup_file = config_file.with_name(config_file.name + ".headroom-backup")
assert not backup_file.exists()
inject_opencode_provider_config(port=8787)
assert not backup_file.exists()
def test_snapshot_does_not_back_up_a_config_headroom_created(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""A config Headroom created holds no pre-wrap content to restore."""
_set_test_home(monkeypatch, tmp_path)
config_file = tmp_path / ".config" / "opencode" / "opencode.json"
inject_opencode_provider_config(port=8787)
config_file.write_text('{"theme": "dark"}', encoding="utf-8")
inject_opencode_provider_config(port=8787)
backup_file = config_file.with_name(config_file.name + ".headroom-backup")
assert not backup_file.exists()
def test_reinject_prunes_a_dropped_extra_model(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""A model Headroom injected but no longer advertises is dropped."""
_set_test_home(monkeypatch, tmp_path)
config_file = tmp_path / ".config" / "opencode" / "opencode.json"
extra = {"name": "My Model", "limit": {"context": 200000, "output": 16384}}
inject_opencode_provider_config(port=8787, extra_models={"my-model": extra})
inject_opencode_provider_config(port=8787, keep_user_entries=True)
models = _parse_json_loose(config_file.read_text(encoding="utf-8"))["provider"]["headroom"][
"models"
]
assert "my-model" not in models
assert set(models) == {"gpt-4o", "gpt-4.1"}
@pytest.mark.parametrize("keep_user_entries", [False, True])
def test_reinject_prunes_a_dropped_override_of_a_builtin_id(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, keep_user_entries: bool
) -> None:
"""A dropped --extra-model override of a built-in restores the defaults."""
_set_test_home(monkeypatch, tmp_path)
config_file = tmp_path / ".config" / "opencode" / "opencode.json"
override = {"name": "Override", "limit": {"context": 8000, "output": 4000}}
inject_opencode_provider_config(
port=8787, extra_models={"gpt-4o": override}, keep_user_entries=keep_user_entries
)
inject_opencode_provider_config(port=8787, keep_user_entries=keep_user_entries)
models = _parse_json_loose(config_file.read_text(encoding="utf-8"))["provider"]["headroom"][
"models"
]
assert models["gpt-4o"] == HEADROOM_OPENCODE_MODELS["gpt-4o"]
def test_reinject_keeps_a_user_model_and_a_edited_extra(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""Models the user added or edited survive a re-wrap."""
_set_test_home(monkeypatch, tmp_path)
config_file = tmp_path / ".config" / "opencode" / "opencode.json"
extra = {"name": "My Model", "limit": {"context": 200000, "output": 16384}}
inject_opencode_provider_config(port=8787, extra_models={"my-model": extra})
data = _parse_json_loose(config_file.read_text(encoding="utf-8"))
data["provider"]["headroom"]["models"]["user-model"] = {"name": "User Model"}
data["provider"]["headroom"]["models"]["my-model"] = {"name": "Renamed by the user"}
config_file.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
inject_opencode_provider_config(port=8787, keep_user_entries=True)
models = _parse_json_loose(config_file.read_text(encoding="utf-8"))["provider"]["headroom"][
"models"
]
assert models["user-model"] == {"name": "User Model"}
assert models["my-model"] == {"name": "Renamed by the user"}
def test_remove_managed_opencode_provider_keeps_user_entries() -> None:
"""Only the entries Headroom injected are removed."""
from headroom.providers.opencode.config import (
OpencodeManagedState,
remove_managed_opencode_provider,
)
state = OpencodeManagedState(
created_file=True,
managed_base_url="http://127.0.0.1:8787/v1",
managed_models={"gpt-4o": {"name": "GPT-4o"}},
)
data = {
"provider": {
"headroom": {
"npm": "@ai-sdk/openai-compatible",
"name": "Headroom Proxy",
"options": {"baseURL": "http://127.0.0.1:8787/v1", "apiKey": "secret"},
"models": {"gpt-4o": {"name": "GPT-4o"}, "user-model": {"name": "User"}},
},
"anthropic": {"options": {"timeout": 5}},
},
"theme": "dark",
}
assert remove_managed_opencode_provider(data, state) is True
headroom = data["provider"]["headroom"]
assert headroom["models"] == {"user-model": {"name": "User"}}
assert headroom["options"] == {"apiKey": "secret"}
assert headroom["npm"] == "@ai-sdk/openai-compatible"
assert headroom["name"] == "Headroom Proxy"
assert data["provider"]["anthropic"] == {"options": {"timeout": 5}}
assert data["theme"] == "dark"
def test_remove_managed_opencode_provider_keeps_an_edited_provider_identity() -> None:
"""An npm/name the user edited survives unwrap (#2364).
The reported case: wrap a config that did not exist, edit only
``provider.headroom.npm`` and ``.name``, then unwrap. The edited values are
the user's own provider identity, so removing them emptied the config file
even though the user had made it theirs.
"""
from headroom.providers.opencode.config import (
OpencodeManagedState,
remove_managed_opencode_provider,
)
state = OpencodeManagedState(
created_file=True,
managed_base_url="http://127.0.0.1:8787/v1",
managed_models={"gpt-4o": {"name": "GPT-4o"}},
)
data = {
"provider": {
"headroom": {
"npm": "@ai-sdk/my-fork",
"name": "My Local Gateway",
"options": {"baseURL": "http://127.0.0.1:8787/v1"},
"models": {"gpt-4o": {"name": "GPT-4o"}},
}
}
}
assert remove_managed_opencode_provider(data, state) is True
assert data == {
"provider": {"headroom": {"npm": "@ai-sdk/my-fork", "name": "My Local Gateway"}}
}
def test_remove_managed_opencode_provider_drops_the_empty_provider() -> None:
"""A provider block that only held Headroom's entries is removed."""
from headroom.providers.opencode.config import (
OpencodeManagedState,
remove_managed_opencode_provider,
)
state = OpencodeManagedState(
created_file=True,
managed_base_url="http://127.0.0.1:8787/v1",
managed_models={"gpt-4o": {"name": "GPT-4o"}},
)
data = {
"provider": {
"headroom": {
"npm": "@ai-sdk/openai-compatible",
"name": "Headroom Proxy",
"options": {"baseURL": "http://127.0.0.1:8787/v1"},
"models": {"gpt-4o": {"name": "GPT-4o"}},
}
}
}
assert remove_managed_opencode_provider(data, state) is True
assert data == {}
def test_opencode_config_is_empty_only_for_empty_configs(tmp_path: Path) -> None:
"""A config with content (or with unreadable content) is never empty."""
from headroom.providers.opencode.config import opencode_config_is_empty
config_file = tmp_path / "opencode.json"
config_file.write_text("{}", encoding="utf-8")
assert opencode_config_is_empty(config_file) is True
config_file.write_text('{"provider": {}}', encoding="utf-8")
assert opencode_config_is_empty(config_file) is True
config_file.write_text('{"provider": {"headroom": {}}}', encoding="utf-8")
assert opencode_config_is_empty(config_file) is True
config_file.write_text('{"theme": "dark"}', encoding="utf-8")
assert opencode_config_is_empty(config_file) is False
# A falsy user setting is content, not an empty section.
config_file.write_text('{"autoupdate": false}', encoding="utf-8")
assert opencode_config_is_empty(config_file) is False
config_file.write_text('{"retries": 0}', encoding="utf-8")
assert opencode_config_is_empty(config_file) is False
config_file.write_text('{"model": ""}', encoding="utf-8")
assert opencode_config_is_empty(config_file) is False
config_file.write_text("not json", encoding="utf-8")
assert opencode_config_is_empty(config_file) is False
# Unparseable user config must not be rewritten
# ---------------------------------------------------------------------------
def test_inject_provider_config_keeps_user_keys_with_bom(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""A config saved with a UTF-8 BOM keeps its user keys when the provider is injected."""
_set_test_home(monkeypatch, tmp_path)
config_file = tmp_path / ".config" / "opencode" / "opencode.json"
config_file.parent.mkdir(parents=True)
bom = chr(0xFEFF)
config_file.write_text(bom + '{"model": "gpt-4o", "mcp": {"x": {}}}', encoding="utf-8")
inject_opencode_provider_config(port=8787)
config = json.loads(config_file.read_text(encoding="utf-8"))
assert config["model"] == "gpt-4o"
assert config["mcp"] == {"x": {}}
assert "headroom" in config["provider"]
def test_inject_provider_config_leaves_unparseable_config_untouched(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""A non-empty config that cannot be parsed is reported, not replaced."""
_set_test_home(monkeypatch, tmp_path)
config_file = tmp_path / ".config" / "opencode" / "opencode.json"
config_file.parent.mkdir(parents=True)
original = '{"model": "gpt-4o" "oops": 1}'
config_file.write_text(original, encoding="utf-8")
with pytest.raises(click.ClickException, match="could not parse"):
inject_opencode_provider_config(port=8787)
assert config_file.read_text(encoding="utf-8") == original
@pytest.mark.parametrize("suffix", ["", " \n"])
def test_inject_provider_config_treats_bom_only_config_as_empty(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, suffix: str
) -> None:
"""A config holding only a BOM (and whitespace) is empty, not unparseable."""
_set_test_home(monkeypatch, tmp_path)
config_file = tmp_path / ".config" / "opencode" / "opencode.json"
config_file.parent.mkdir(parents=True)
config_file.write_text(chr(0xFEFF) + suffix, encoding="utf-8")
inject_opencode_provider_config(port=8787)
config = json.loads(config_file.read_text(encoding="utf-8"))
assert "headroom" in config["provider"]
def test_inject_provider_config_reparses_config_with_legacy_marker_block(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""A config holding a comment-marked Headroom block is re-parsed after the strip.
The marker comments are what older writers left in the file; the strip runs
before the provider is merged, and the user's keys outside the block survive.
"""
_set_test_home(monkeypatch, tmp_path)
config_file = tmp_path / ".config" / "opencode" / "opencode.json"
config_file.parent.mkdir(parents=True)
config_file.write_text(
"{\n"
' "model": "gpt-4o",\n'
" // --- Headroom proxy provider ---\n"
' "provider": {"headroom": {"options": {"baseURL": "http://127.0.0.1:1"}}},\n'
" // --- end Headroom proxy provider ---\n"
' "theme": "dark"\n'
"}\n",
encoding="utf-8",
)
inject_opencode_provider_config(port=8787)
config = json.loads(config_file.read_text(encoding="utf-8"))
assert config["model"] == "gpt-4o"
assert config["theme"] == "dark"
headroom = config["provider"]["headroom"]
assert "8787" in json.dumps(headroom)
assert headroom.get("options", {}).get("baseURL") != "http://127.0.0.1:1"