mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
fix/plugin-launcher-isolated-python
9
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
87c12931fb |
fix(opencode): stop routing a host's bare /messages or /responses to the proxy (#4781) (#4791)
## Description A `POST` whose path ends in a wire endpoint but that sits at a host's origin root (`/messages`, `/responses`, `/chat/completions`) is no longer routed to the proxy unless that origin is a configured provider base URL. Closes #4781. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) ## Changes Made - `plugins/opencode/src/transport.ts` — `hasWireRootBefore` no longer treats "no segment before the endpoint" as a wire root, so a bare `/messages` at an unknown host goes direct. - `plugins/opencode/src/transport.test.ts` — the bare-endpoint assertions from #4758 move into a #4781 case that pins both directions: direct by default, routed once the base is registered; the #4758 case keeps the prefixes that still route. - `plugins/opencode/README.md` — states the actual routing rule, and the two shapes that still route without a configured base. - `headroom/providers/opencode/_dist/index.js`, `headroom/providers/opencode/hook-shim/handler.js` — rebuilt, since the `opencode-plugin` gate compares bytes against `dist-standalone`. - `plugins/opencode/scripts/live-proof-4781.mjs` — the live proof below, committed so it can be rerun. ## Why #4758 stopped a suffix match from routing non-LLM hosts, but kept bare endpoints routable "because compatible gateways use those paths". That left exactly one non-LLM shape still leaking: `POST https://rest.messagebird.com/messages` with `Authorization: AccessKey ...` went to the proxy, carrying a non-LLM credential (#4781). Becoming the bare path is not evidence of a provider — it is equally the shape of a messaging API. A provider mounted at an origin root is still routed, because its base URL *is* a configured wire root (`isConfiguredWireRoot` matches every path on that origin when the base path is empty), which is how OpenCode reports `provider.<id>.options.baseURL`. ```ts return ( last !== undefined && (isVersionSegment(last) || IMMEDIATE_WIRE_ROOTS.has(last) || segments.some((s) => NAMED_WIRE_ROOTS.has(s))) ); ``` Everything else is untouched: version prefixes (`/v1`, `/v1beta`, `/v4`), immediate `api`, named roots (`backend-api`, `codex`, `openai`, `anthropic`, `zen`), Gemini colon actions, configured bases, `excludeHosts`, and the method gate. ## Testing - [x] New tests added for new functionality - [x] Manual testing performed `plugins/opencode` is a TypeScript package, so its gates are npm scripts rather than `pytest` / `ruff` / `mypy`; `npm audit` and the rest run in the repo's own CI. ### Test Output ```text > vitest run Test Files 4 passed (4) Tests 80 passed (80) > node node_modules/@typescript/native/bin/tsc --noEmit (clean, no output) > node scripts/live-proof-4781.mjs === decisions (real sockets, real fetch, real built plugin) === PASS MessageBird-shaped POST /messages -> left alone PASS MessageBird batches POST /messages/batches -> left alone PASS LLM control POST /v1/messages -> REROUTED to proxy PASS LLM control POST /v1/chat/completions -> REROUTED to proxy === what reached the proxy === POST /v1/messages x-headroom-base-url=http://localtest.me:8899 original-path=null POST /v1/chat/completions x-headroom-base-url=http://localtest.me:8899 original-path=/v1/chat/completions === MessageBird-shaped requests that reached the proxy: 0 === === what reached the upstream directly === POST /messages auth=AccessKey FAKE-TEST-VALUE (no proxy headers: true) POST /messages/batches auth=AccessKey FAKE-TEST-VALUE (no proxy headers: true) ALL CASES PASS ``` Before the fix, same script, source reverted to `HEAD~1` and the bundle rebuilt: ```text === decisions (real sockets, real fetch, real built plugin) === FAIL MessageBird-shaped POST /messages -> REROUTED to proxy PASS MessageBird batches POST /messages/batches -> left alone PASS LLM control POST /v1/messages -> REROUTED to proxy PASS LLM control POST /v1/chat/completions -> REROUTED to proxy === what reached the proxy === POST /messages x-headroom-base-url=http://localtest.me:8899 original-path=null ``` Reverting only `src/transport.ts` also fails the unit test (`1 failed | 79 passed`), satisfying "a test that fails before your fix and passes after". ## Real Behavior Proof - Environment: Windows 11 (win32), Node v26.10.0, this branch of `plugins/opencode`, committed wheel bundle `headroom/providers/opencode/_dist/index.js` loaded via `plugin.server(...)` as `headroom wrap opencode` does; upstream and proxy are local HTTP fixtures on real TCP sockets and `globalThis.fetch` is Node's undici, not a stub. - Exact command / steps: `cd plugins/opencode && npm ci && npm run build:standalone && node scripts/live-proof-4781.mjs`, which POSTs a MessageBird-shaped SMS payload and two LLM control requests to `http://localtest.me:8899` (resolves to 127.0.0.1 but is not a loopback spelling, so traffic really leaves the process) and records which server received each one. - Observed result: after the patch `POST /messages` and `POST /messages/batches` reach the upstream directly with no `x-headroom-base-url` header and the proxy receives zero MessageBird-shaped requests, while `/v1/messages` and `/v1/chat/completions` still reach the proxy with the upstream origin header; with `src/transport.ts` reverted to `HEAD~1` the same run reroutes `POST /messages` to the proxy, reproducing the reported leak over a real socket (full output in `Testing` → `Test Output`). - Not tested: a real MessageBird account and the real `rest.messagebird.com` host, since the payload and `AccessKey` are fake and routing is decided before DNS; the proxy's handling of an SMS body, which never arrives after this change; and a live OpenCode host process, since the fixture drives the plugin's own `server()` entry rather than an OpenCode session. ## Runtime Rollout Safety - Rollout-managed feature(s): none, no feature flag is involved. - Minimum rollout channel: next released `headroom-opencode` / wheel. - Stable/default behavior changed: yes, deliberately — a `POST` to `/messages`, `/responses` or `/chat/completions` at a host's origin root now goes direct unless that origin is a configured provider base URL; users whose gateway is configured via `provider.<id>.options.baseURL` are unaffected. - Kill switch / disable path: `excludeHosts` / `HEADROOM_OPENCODE_EXCLUDE_HOSTS` forces a host direct, and configuring the base URL or listing it in `wireRoots` forces a bare-path provider through the proxy. - Unsafe override required: no. - Qualification impact: none. - Rollback path: revert the commits; the transport and the committed bundle revert together. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title ## Additional Notes Residual, deliberately not solved and now stated in the README: `/api/v2/messages` and `/v2/responses` still route. No path shape separates those from a gateway rooted at `/api` or `/v2`; only the host or the request body could, and reading the body inside a sync `fetch` wrapper buys a new class of failure for a shape `excludeHosts` already covers. I did not add a known-host allowlist either: it can only recognise hosts someone already thought of, and it regresses compatible gateways silently — the failure mode #4747 was filed about. --------- Co-authored-by: JerrettDavis <mxjerrett@gmail.com> |
||
|
|
c48778c4ab |
fix(opencode): stop routing non-LLM hosts and paths to the proxy (#4747) (#4758)
Closes #4747. ## Description The OpenCode transport shim decides whether to reroute a request from the URL string alone. That decision had three blind spots: two too literal, one too narrow. **Hosts.** `isLoopback` compared the raw hostname against exactly `"127.0.0.1"` and `"::1"`, so every other spelling of loopback counted as remote and its request — with the caller's `Authorization` header — went to the proxy: | URL host | `URL.hostname` | old check | new check | | --- | --- | --- | --- | | `127.0.0.2` | `127.0.0.2` | remote | loopback | | `127.1.2.3` | `127.1.2.3` | remote | loopback | | `[::ffff:127.0.0.2]` | `[::ffff:7f00:2]` | remote | loopback | | `localhost.` | `localhost.` | remote | loopback | | `api.x.example.` | `api.x.example.` | not excluded | excluded | The trailing-dot row is the same bug on the `excludeHosts` path: `example.com.` is the fully qualified spelling of `example.com`, so an excluded host was routed anyway. **Paths.** Any path ending in `/messages` or `/responses` was treated as an LLM endpoint, so Discord's `/api/v10/channels/123/messages` and a forms API's `/forms/123/responses` were rerouted. That needs a wire root in front of the endpoint. **Configured bases.** The first version of that wire-root rule could only recognise root names it knew (`v1`, `api`, `openai`, …), so a compatible gateway configured at `https://gateway.invalid/tenant/acme` lost its routing entirely: OpenCode 1.x sent `/tenant/acme/chat/completions` through the patched `fetch` straight upstream, with no compression and no telemetry. The plugin's own `modelBaseRoutesThroughProxy` still accepted that base, so the transport disagreed with the plugin. Provider base URLs from OpenCode's configuration are now authoritative, matched by origin and path prefix rather than by root name, and the path heuristics stay as the fallback when no configuration is available. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Refactoring (no functional changes) - [ ] Tests only ## Reproduction On `main`, with the plugin's transport installed: ```js installHeadroomTransport({ proxyUrl: "http://127.0.0.1:8787/v1", excludeHosts: ["api.x.example"] }); await fetch("http://127.0.0.2:11434/v1/chat/completions", { method: "POST" }); // routed to proxy await fetch("http://localhost./v1/chat/completions", { method: "POST" }); // routed to proxy await fetch("https://api.x.example./v1/chat/completions", { method: "POST" }); // routed to proxy await fetch("https://discord.com/api/v10/channels/123/messages", { method: "POST" }); // routed to proxy ``` A local provider on `127.0.0.2` or `[::ffff:127.0.0.2]`, a `.internal` host spelled with a trailing dot, and a non-LLM `POST` all ended up at the Headroom proxy instead of their own server. For the configured-base half, on the previous head `b695e697` with a provider base URL of `https://gateway.invalid/tenant/acme`: ```js await fetch("https://gateway.invalid/tenant/acme/chat/completions", { method: "POST" }); // main: proxy. |
||
|
|
3d9a6f2cf7 |
fix(opencode): route Copilot Claude models through the proxy (#4594)
## Description
Closes #4248. The OpenCode 2.x plugin routes models through Headroom by
rewriting model `baseURL`s in `ctx.model.transform`, but it recognized
only the OpenAI wires (`openai-compatible`, `*/chat`, `*/responses`).
Copilot's Claude models use `@opencode/ai/providers/anthropic` (Messages
wire), so they were skipped and their requests never reached the proxy,
while Copilot GPT models kept working.
`modelWireSuffix` now also maps `anthropic`, `anthropic-compatible` and
model-level `*/messages` packages to `/messages`, reusing the existing
rewrite. The config-level `headroom wrap opencode` path cannot cover
Copilot because OpenCode creates that provider dynamically.
## Type of Change
- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)
## Changes Made
<details>
<summary>changes details</summary>
- `plugins/opencode/src/plugin.ts`: rename `openAiWireSuffix` to
`modelWireSuffix`, map the Anthropic Messages wires to `/messages`.
- `plugins/opencode/README.md`: document that Anthropic Messages models
are rewritten too.
- `plugins/opencode/src/plugin.test.ts`: three new cases plus a narrowed
negative case.
- `headroom/providers/opencode/_dist/index.js`: rebuilt so the wheel
bundle stays byte-identical (CI `cmp` gate).
</details>
## Testing
<details>
<summary>testing details</summary>
- [x] Unit tests pass (`npm test -- --maxWorkers=2`: 66 passed at
current head)
- [x] Type checking passes (`npm run typecheck`)
- [x] Linting: repo lint is Python-only; plugin gates are typecheck,
build, test, bundle `cmp`, all run
- [x] New tests added
- [x] Manual testing performed — actual OpenCode CLI plus real proxy and
controlled upstream; live Copilot not tested
### Test Output
<!-- Paste relevant command output or artifact links here -->
<details><summary>commands and output</summary>
```text
npm test -- --maxWorkers=2 -> 4 files, 66 passed at
|
||
|
|
99e223c0e2 |
deps: Bump tsup from 8.5.1 to 9.0.0 in /plugins/opencode (#4385)
Build the OpenCode plugin with the patched esbuild line inside tsup's supported range. Headroom's existing esbuild 0.28 security override is outside tsup 8.5.1's ^0.27.0 declaration. Tsup 9 declares ^0.28.2, so retain the major upgrade and raise the override floor from ^0.28.1 to ^0.28.2. The original tsup 9 lock still selected 0.28.1; this follow-up corrects that mismatch and documents the source-build requirements. ## Dependency assessment - **Version reason:** use an upstream-supported build combination for the existing dependency-security mitigation, rather than forcing the selected esbuild release outside the old bundler's range. This does not claim a new advisory in 0.28.1 or that the old built plugin was demonstrated broken. Tsup remains the existing builder; [v9](https://github.com/egoist/tsup/releases/tag/v9.0.0) also changes debug/obug, watchers and related toolchain packages. - **Maintenance/security:** reviewed the published release/manifest and resolved graph. Fresh audit reports zero vulnerabilities; this does not imply every upstream project has a spotless history. Platform-selector metadata outside the esbuild refresh is preserved instead of accepting unrelated npm-version normalization. - **Node/build boundary:** tsup requires `^22.18.0 || ^24.11.0 || >=26.0.0`; the current graph's ini 7 also requires `^22.22.2 || ^24.15.0 || >=26.0.0`. The README documents both and the verified Node 24.22.2 choice. Published plugin/host runtime declarations are unchanged. An earlier Node 22.22.0 pass emitted the existing ini warning; acceptance uses the supported Node 24 install. - **Native/install/network:** existing esbuild/Rollup platform code and lifecycle scripts remain build inputs. Rollup's optional GNU Linux-x64 LZMA and Android-x64 bindings are present; the LZMA entry is a real optional dependency, not an orphan. Windows x64 installation/build was tested; these non-Windows paths were not. No new install-script flag is introduced. Existing plugin runtime dependencies are unchanged; tsup remains a development dependency. npm and host support-dependency installation use the registry. No plugin is published and no inference/provider message is requested. The branch is synchronized with main's merged security and SDK updates. ## Real behavior proof Windows x64 / Node 24.22.2 / npm 10.9.4, fresh isolated checkout. From `plugins/opencode`, under that Node: ```bash npm ci --ignore-scripts=false --no-audit --no-fund npm test npm run typecheck npm run build npm run build:standalone npm audit --json node ../../scripts/verify_opencode_bundle.mjs . ``` The install has no engine warning; **61 tests pass**, typecheck and both builds succeed, audit reports zero vulnerabilities. The committed portable proof imports actual `dist/index.js` and `dist-standalone/index.js`, invokes the built server entry and performs real chat/retrieve HTTP requests against an ephemeral loopback fixture. It asserts original upstream/path, project/session headers, response and retrieval content; output reports PASS. The plugin routes the synthetic OpenAI URL to the fixture. Hooks/sockets/processes are disposed. This is built-artifact wire behavior, not a claim that the fixture is the Python service. **Actual host loading:** installed official `opencode-ai@1.19.4`, matching the installed 1.x plugin SDK, into a task-only prefix/cache. Its native Windows `opencode.cmd debug config --print-logs` ran from an isolated task workspace with the built main entry `file:///G:/git/headroom-dep4385/plugins/opencode/dist/index.js` configured directly. No wrapper was used for this check. It exited 0 with successful bootstrap/configuration/disposal and no loader error. A separate instrumentation probe preserved the exported object shape and delegated its actual `server` function; it recorded `id=headroom`, retrieval-tool registration and the shell-environment hook. It did not adapt the object into a legacy function. The host's XDG config/data/state/cache point at task-only directories. Enabled providers are empty; auto-update, remote model fetching and default plugins are disabled. Credential environment names are removed in the child shell only; user home/config/auth files are not repurposed. The CLI installed support dependencies in the isolated config, so registry traffic occurred. No inference command or provider action was requested. Node syntax and whitespace checks pass. Independent technical review found no code or dependency-policy blocker in the corrected build range/source-runtime boundaries. Untested: actual OpenCode 2.x, registry-tarball plugin installation, the Python compression proxy in this smoke, streaming, live providers, hook-shim spawning, non-Windows native installation, or production publishing. Current-head hosted CI must pass before approval. --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: JerrettDavis <mxjerrett@gmail.com> |
||
|
|
1d4b357ca7 |
feat(opencode): support the OpenCode 2.x plugin API (#3999)
## Description Takeover of #3719 by @laurence-diack-pk, who has been unavailable since Sep 23 and whose branch was left conflicted with `main`. The original commit is preserved and @laurence-diack-pk remains its author; this branch adds follow-up commits addressing @JerrettDavis's review and the findings from live OpenCode 2.x testing. It makes the OpenCode plugin and `headroom wrap opencode` work on both OpenCode 1.x and 2.x. On 2.x the 1.x function plugin was silently dropped (the loader requires a `{ id, setup }` default export loaded from a directory), and Effect's `FetchHttpClient` keeps its own `fetch` reference from before plugins load — so `wrap opencode` loaded no plugin and routed nothing. Closes #3669. Supersedes #3719. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [x] New feature (non-breaking change that adds functionality) ## Changes Made Carried from #3719: - One plugin for both versions: default export `{ id: "headroom", server, setup }`; 1.x calls `server`, 2.x calls `setup`. - 2.x `setup`: registers `headroom_retrieve` via `ctx.tool.transform` (`codemode: false`), sets `HEADROOM_*` shell env through the `create.before` hook, and returns a cleanup that releases the refcounted transport so hot reloads do not stack interceptors. - 2.x model routing: `ctx.model.transform` points remote OpenAI-wire models at the proxy with `x-headroom-base-url` / `x-headroom-original-path` headers, since 2.x keeps its own `fetch` reference and the transport patch alone misses model traffic. - Wheel ships the bundle as `_dist/index.js`; `headroom_opencode_plugin_path()` returns the directory; `wrap opencode` adds `--standalone` on 2.x so the private server sees `OPENCODE_CONFIG_CONTENT`. Follow-up commits (review from #3719 + live testing): - Rebased on current `main` (0.40.0). Fixed the routing-contract conflict: replaced `routesThroughProxy` (TS2554 against `shouldRoute`'s 3-arg signature) with `modelBaseRoutesThroughProxy`, a deliberate model-base eligibility check that keeps the shared protocol / loopback / proxy-origin / excluded-host contract but drops the endpoint-suffix requirement, since 2.x hands us model base URLs (e.g. `/v1`), not inference endpoints. - `setup` now resolves the effective `excludeHosts` once (option over `HEADROOM_OPENCODE_EXCLUDE_HOSTS`) and applies it to both the transport install and the model rewrite, with new tests for both paths. - Fixed `test_build_launch_env_with_project` to decode `OPENCODE_CONFIG_CONTENT` instead of substring-matching the raw path, which JSON backslash escaping makes impossible on Windows. - `opencode_major_version` now reads the `v2` channel marker in dev builds (`opencode v0.0.0-v2-<stamp>`), which previously parsed as major 0, so `wrap` skips `--standalone` and the private server never loads Headroom's config. - Rebuilt `_dist/index.js` and `hook-shim/handler.js`; drift check clean. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .` — run on the changed paths) - [x] Type checking passes (`mypy headroom` — run on the changed paths) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text # plugins/opencode $ npm ci && npm run typecheck && npm run build:standalone && npm test tsc: clean (no TS2554) vitest: Test Files 3 passed (3) | Tests 45 passed (45) $ cmp dist-standalone/index.js ../../headroom/providers/opencode/_dist/index.js # identical $ cmp dist-standalone/hook-shim/handler.js ../../headroom/providers/opencode/hook-shim/handler.js # identical # focused Python suites (same set as #3719, plus the 2.x dev-build version case) $ pytest tests/test_providers_opencode_plugin_path.py tests/test_providers_opencode_config.py \ tests/test_providers_opencode_install.py tests/test_cli/test_wrap_opencode.py \ tests/test_mcp_registry_opencode.py tests/test_learn/test_opencode_scanner.py -q 193 passed in 1.10s $ ruff check / ruff format --check on changed paths: clean $ mypy headroom/providers/opencode headroom/cli/wrap.py: Success: no issues found ``` ## Real Behavior Proof - Environment: macOS arm64, Node v26.10.0, Python 3.13, headroom from this branch (0.41.0-dev). Tested against two real OpenCode 2.x clients, each in throwaway XDG dirs with its own proxy port: - `opencode 2.0.19` (official 2.x binary); - OpenCode 2.x head built from `anomalyco/opencode@v2` (`0.0.0-v2-202610061051`, Bun 1.4.2, `bun run script/build.ts --single` in `packages/cli`). - Exact command / steps: throwaway XDG dirs and a dedicated proxy port; fake key first (routing proof), then the real key (end-to-end proof): ```bash # fake key first (routing proof), then the real key (end-to-end proof) OPENCODE_API_KEY=<key> headroom wrap opencode --port 8799 --no-serena -- \ run -m opencode-go/deepseek-v4.1-flash "reply with the single word ok" # exclusion check HEADROOM_OPENCODE_EXCLUDE_HOSTS=opencode.ai OPENCODE_API_KEY=<key> headroom wrap opencode ... ``` (`opencode-go` declares `OPENCODE_API_KEY` as its env credential in the catalog, so no interactive login is needed.) - Observed result: routed 401 with the fake key and 200 with the real key through the proxy, `--standalone` added automatically, exclusion honored — details: - **Fake key** — proxy log: `proxy_inbound_request POST /v1/chat/completions` with `user-agent: opencode/latest/2.0.19/cli` (and `opencode/v2/0.0.0-v2-202610061051/cli` for the head), headers `x-headroom-base-url: https://opencode.ai` and `x-headroom-original-path: /zen/go/v1/chat/completions`; forwarded upstream, `401` from the fake key — routed through Headroom. - **Real key** — the model answered `ok`; proxy `status=200` with upstream `https://opencode.ai/inference/go/openai/v1/chat/completions`. - `wrap` added `--standalone` automatically on 2.0.19, and again on the v2 head after the dev-build version fix (explicit `--standalone` also works, per the kill-switch path). - **Exclusion** — with `HEADROOM_OPENCODE_EXCLUDE_HOSTS=opencode.ai` the model still answered while the proxy saw **zero** new chat requests: the 2.x model transform honors the exclusion list. - Not tested: Windows; OpenAI "responses"-wire against a live 2.x server; Anthropic-wire custom providers on 2.x; loading the plugin by npm name (`headroom-opencode`), which needs a published release; OpenCode 1.x older than 1.2.20. ## Runtime Rollout Safety - Rollout-managed feature(s): none - Minimum rollout channel: n/a - Stable/default behavior changed: on OpenCode 2.x, `wrap opencode` launches with `--standalone` (a private server per session); on 1.x behaviour is unchanged apart from the plugin path now being a directory. - Kill switch / disable path: pass `--server <url>` or `--standalone` explicitly; `HEADROOM_OPENCODE_PLUGIN_PATH` still overrides the plugin location. - Unsafe override required: no - Qualification impact: none - Rollback path: revert this PR; the wheel bundle and plugin path revert with it. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Additional Notes @laurence-diack-pk — thank you for the original implementation; the commit is preserved verbatim at the base of this branch. @JerrettDavis — this addresses the routing-contract conflict you described in #3719 (the missing `excludeHosts` argument and the model-base vs endpoint mismatch), the Windows assertion, and a dev-build version-detection gap found while validating on macOS. Live 2.x validation is done on both 2.0.19 and today's `v2` head; details above. --------- Co-authored-by: laurence <laurence.diack@peekrobotics.co.nz> Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Co-authored-by: JerrettDavis <mxjerrett@gmail.com> |
||
|
|
0024b57405 |
feat(opencode): exclude hosts from transport plugin routing (#3668)
## Description The OpenCode transport plugin rewrites every non-loopback HTTP(S) request to the Headroom proxy, both in the OpenCode process and in every spawned Node child via the hook-shim. When a provider validates the client on the wire and rejects the proxy hop (OpenCode Zen free tier, some enterprise gateways), the only way to keep that provider working is to unload the plugin, which drops Headroom for every other provider too. This adds an exclude list to `shouldRoute()`. Hosts come from the `excludeHosts` plugin option, or from `HEADROOM_OPENCODE_EXCLUDE_HOSTS` (comma-separated) when the option is absent, with the same option-over-env precedence `proxyUrl` already uses. An entry matches the host and all of its subdomains (`example.com`, `.example.com` and `*.example.com` are equivalent). Excluded requests go straight upstream with their original URL, init and headers: no `x-headroom-base-url`, no compression, no telemetry. The effective list is exported to `process.env` and to spawned child env so the hook-shim copy of the transport makes the same decision. Default is empty, so nothing changes for existing installs. Root cause: `shouldRoute()` (unchanged since #1105) only checked scheme, loopback and the proxy origin; it had no configuration input at all, and the child-process shim configures itself purely from env, so any opt-out has to be env-readable and exported by `withShimEnv`/`installProcessEnv` or children silently diverge from the parent (#3633 points this out). Considered and not done here: path-level globs (both reported cases are host-level; can be layered on later as a separate variable), proxy-side passthrough (still a proxy hop, which is what the Zen gate rejects), and a default exclusion for `registry.npmjs.org` (a separate decision; this keeps zero behavior change by default). The Zen `/responses` bug itself is #3656 / #3659. Closes #3657 Refs #3633 Note: #3657 is a feature request and did not yet have a maintainer 👍 when I opened this, so I am keeping it small and happy to change the surface: drop the plugin option and ship env-only, rename the variable to #3633's `HEADROOM_OPENCODE_ROUTE_EXCLUDE`, or hold until the surface is agreed. ## Type of Change - [ ] Bug fix (non-breaking change that fixes an issue) - [x] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `plugins/opencode/src/transport.ts`: `normalizeExcludeHosts` / `isExcludedHost`; `shouldRoute` takes the list and returns `false` on a match (fetch, `http`/`https.request`/`get`, and `http2.connect`, which is now allowed for excluded hosts instead of blocked); `installHeadroomTransport` resolves `options.excludeHosts ?? process.env.HEADROOM_OPENCODE_EXCLUDE_HOSTS`; `installProcessEnv` and `withShimEnv` export the **effective** list through `withExcludeHostsEnv` — set when non-empty, deleted when empty — so an explicit `excludeHosts: []` clears a pre-existing variable for the process and for every spawned child (review finding, second commit). - `plugins/opencode/src/plugin.ts`: `excludeHosts?: string[]` on `HeadroomOpenCodePluginOptions`, passed through. - `plugins/opencode/src/transport.test.ts`: six tests — env var with subdomain/case/`.`/`*.` forms and non-matching hosts still routed; option precedence over env; Node `https.request` and `http2.connect` on excluded hosts; child env propagation (and no variable set when nothing is excluded); explicit empty override clears a pre-existing variable in-process, in `process.env`, and in default/custom/stale-carrying child env; the variable tracks each re-install's resolved list. - `headroom/providers/opencode/_dist/entry.opencode.js`, `headroom/providers/opencode/hook-shim/handler.js`: rebuilt with `npm run build:standalone`. - `plugins/opencode/README.md`, `docs/content/docs/opencode.mdx`: document the option, the variable and the matching rule. ## Testing - [ ] Unit tests pass (`pytest`) — not run in full locally; `tests/test_providers_opencode_plugin_path.py` and `tests/test_providers_opencode_config.py` give the same result as `main` on my Windows checkout (44 passed, 1 pre-existing Windows-only path-escaping failure in `test_build_launch_env_with_project`). No Python source changed. - [ ] Linting passes (`ruff check .`) — no Python changed. - [ ] Type checking passes (`mypy headroom`) — no Python changed. - [x] New tests added for new functionality - [x] Manual testing performed Plugin CI sequence from `.github/workflows/opencode-plugin.yml`, run after rebasing onto `main` (`67eb910e`): typecheck, build, test, standalone build, bundle parity, plus commitlint and `npm audit`. ### Test Output ```text $ cd plugins/opencode && npm ci && npm run typecheck && npm run build && npm test found 0 vulnerabilities typecheck exit=0 Test Files 2 passed (2) Tests 23 passed (23) $ npm run build:standalone && cmp dist-standalone/entry.opencode.js ../../headroom/providers/opencode/_dist/entry.opencode.js && cmp dist-standalone/hook-shim/handler.js ../../headroom/providers/opencode/hook-shim/handler.js entry.opencode.js: IDENTICAL handler.js: IDENTICAL # the four new tests against unpatched transport.ts (fix stashed, tests kept): ❯ src/transport.test.ts (19 tests | 4 failed) × keeps HEADROOM_OPENCODE_EXCLUDE_HOSTS hosts and their subdomains off the proxy (#3657) × prefers the excludeHosts option over HEADROOM_OPENCODE_EXCLUDE_HOSTS × leaves excluded hosts alone for Node https.request and http2.connect × propagates excluded hosts into child process env so the hook-shim matches AssertionError: expected URL { href: 'http://127.0.0.1:8787/v1/responses', ... } to be 'https://opencode.ai/zen/v1/responses' $ npx commitlint --config .commitlintrc.json --edit <msg> # exit 0 $ npm audit --package-lock-only --audit-level=low # found 0 vulnerabilities ``` ## Real Behavior Proof - Environment: Windows 11, Node v24.13.0, plugin built from this branch (`npm run build` for the in-process check, the committed wheel `hook-shim/handler.js` from this branch for the child-process check), fake proxy on `127.0.0.1` recording `x-headroom-base-url`. `HEADROOM_OPENCODE_EXCLUDE_HOSTS=opencode.ai`. - Exact command / steps: (1) import `dist/index.js`, install the transport with `excludeHosts: ["opencode.ai"]`, `fetch("https://opencode.ai/zen/v1/responses")` then `fetch("https://api.anthropic.com/v1/messages")`, record what the original `fetch` received; (2) spawn `node --import=<hook-shim/handler.js>` with `HEADROOM_OPENCODE_TRANSPORT_PROXY_URL=<fake proxy>` and the variable above, `fetch("https://opencode.ai/zen/v1/responses")` from the child, watch the fake proxy; (3) same two scripts on unpatched `main` as the control. - Observed result: (1) `{"url":"https://opencode.ai/zen/v1/responses","base":null}` then `{"url":"http://127.0.0.1:8787/v1/messages","base":"https://api.anthropic.com"}` — excluded host untouched, Anthropic still routed; (2) `child: fetch resolved status 401 from https://opencode.ai/zen/v1/responses` / `fake proxy saw: []` — the child went direct to the real host (401 is opencode.ai answering an unauthenticated request) and the proxy never saw it; (3) on `main` both scripts route `opencode.ai` to the proxy with `base: https://opencode.ai`, and on this branch the same happens when the variable is spelled wrong (`HEADROOM_OPENCODE_ROUTE_EXCLUDE`), i.e. an unknown variable changes nothing. - Empty-override check (review finding): parent env `HEADROOM_OPENCODE_EXCLUDE_HOSTS=api.anthropic.com`, transport installed with `excludeHosts: []`, a child spawned through the wrapped `child_process.spawn` preloaded with the committed hook-shim, both fetch `api.anthropic.com`: on the reviewed head the child inherited `"api.anthropic.com"` and went direct; on this head `child env var: undefined` and the fake proxy saw `x-headroom-base-url: ["https://api.anthropic.com","https://api.anthropic.com"]` — parent and child agree. - Not tested: a live OpenCode session against the real Zen free-tier model (I don't have OpenCode Zen credentials); macOS/Linux; Bun-spawned children (they inherit `process.env`, which `installProcessEnv` now sets, same path as `NODE_OPTIONS`); the full Python suite (CI). ## Runtime Rollout Safety - Rollout-managed feature(s): none. - Minimum rollout channel: n/a. - Stable/default behavior changed: no. With no `excludeHosts` option and no `HEADROOM_OPENCODE_EXCLUDE_HOSTS`, `shouldRoute()` is unchanged and the variable is never written. Only configured hosts bypass the proxy; for them `http2.connect` is now allowed instead of throwing. - Kill switch / disable path: unset the variable / remove the option; excluded traffic goes back through the proxy on next launch. - Unsafe override required: no. - Qualification impact: none. - Rollback path: revert this commit (source and the two committed bundles change together). ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Additional Notes Start reading at `shouldRoute()` and `normalizeExcludeHosts()` in `plugins/opencode/src/transport.ts`, then `installHeadroomTransport` for the option/env resolution and the two env exports. The bundle diffs are the same hunks compiled. The one decision I'd most like challenged is shipping both a plugin option and an env var: the env var is required regardless (it is the only surface that reaches `headroom wrap opencode`, which registers the plugin as a bare path, and the hook-shim in child processes), and the option mirrors the reporter's proposed API; dropping the option is a six-line change if you'd rather keep one surface. Known limits: entries are bare hosts (no scheme, port or path), IDN entries must be given in punycode, and like `HEADROOM_OPENCODE_TRANSPORT_PROXY_URL` the exported variable is not removed from `process.env` on dispose. --------- Co-authored-by: JD Davis <mxjerrett@gmail.com> |
||
|
|
c2fc4d3753 |
fix(ccr): make headroom_retrieve a hash-only full-content lookup (#1532)
The optional `query` parameter on headroom_retrieve routed retrieval through CompressionStore.search(), which BM25-scored the items inside a single cached blob and dropped everything below a 0.3 relevance floor. On small per-blob corpora with conversational queries this returned an empty result the large majority of the time, so the LLM saw "nothing found" for content that was actually present — pushing users to turn compression off entirely. Retrieval is fundamentally a hash lookup (this already matches the Rust proxy's CCR store, which is put/get only — "no BM25 search"). Remove the query/search path end to end and always return the full original content: Core (Python proxy): - tool schemas (anthropic/openai/google) drop the `query` property - parse_tool_call returns the hash (str | None) instead of (hash, query) - response handler, proxy POST/GET/tool-call handlers, the MCP retrieve tool, and the streaming feedback recorders retrieve by hash only - proactive context-tracker expansion always restores full content - delete CompressionStore.search() and its BM25 machinery (the bm25 module stays — it is still used by relevance/) - CCRToolCall.query, CCRToolResult.was_search, and ExpansionRecommendation.expand_full/search_query are removed Plugins (advertised a now-defunct query param to the LLM): - hermes (Python), openclaw + opencode (TypeScript) retrieve tools drop `query` from their schemas, signatures, request URLs, and tests Benchmarks/docs: - ccr_regression + adversarial benchmarks switch from store.search() to full hash retrieval (search input-injection tests repurposed to the hash, the only remaining input surface) - wiki/ARCHITECTURE.md, wiki/ccr.md, docs/content/docs/ccr.mdx, config.py and store docstrings updated to describe hash-only retrieval Tests updated to assert full-content retrieval and guard the removed surface; the full CCR/proxy/store/TOIN suite passes. ruff + mypy clean. ## Description <!-- Briefly explain the change and why it is needed. --> Closes # ## Type of Change - [ ] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - ## Testing <!-- Check what you actually ran, then paste the real command output below. --> - [ ] Unit tests pass (`pytest`) - [ ] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [ ] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text # Paste relevant command output or artifact links here ``` ## Real Behavior Proof - Environment: - Exact command / steps: - Observed result: - Not tested: ## Review Readiness - [ ] I have performed a self-review - [ ] This PR is ready for human review ## Checklist - [ ] My code follows the project's style guidelines - [ ] I have performed a self-review of my code - [ ] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [ ] My changes generate no new warnings - [ ] I have added tests that prove my fix is effective or that my feature works - [ ] New and existing unit tests pass locally with my changes - [ ] I have updated the CHANGELOG.md if applicable ## Screenshots (if applicable) Add screenshots to help explain your changes. ## Additional Notes <!-- Mention any N/A checklist items, tradeoffs, follow-ups, or maintainer context. --> |
||
|
|
fa05ebc849 |
docs: clarify OpenCode integration (#1317)
## Description Clarifies the OpenCode documentation follow-up for PR #1105 so users can install `headroom-opencode`, configure provider routing, use the native plugin, and copy working retrieve/compression helper examples. ## Type of Change - [x] Documentation update - [ ] Bug fix - [ ] New feature - [ ] Breaking change ## Changes Made - Documented how `headroom wrap opencode` wires provider config, MCP tools, and runtime environment. - Documented the native `HeadroomPlugin` path, `HEADROOM_PROXY_URL`, retrieve tooling, and programmatic config helpers. - Fixed `plugins/opencode/README.md` examples so `compressWithHeadroom` uses the exported options-object API and `headroom_retrieve` uses `hash`. ## Testing - [x] Type checks pass. - [x] Unit tests pass. - [x] Whitespace check passes. ### Test Output ```text plugins/opencode: npm run typecheck > tsc --noEmit plugins/opencode: npm test Test Files 2 passed (2) Tests 9 passed (9) docs: npm run types:check ✓ Types generated successfully repo: git diff --check (no output) ``` ## Real Behavior Proof - Environment: Local macOS worktree at `docs/pr-1105-documentation-followup`, Node/npm project commands run from `plugins/opencode` and `docs`. - Exact command / steps: Updated the README snippets, ran `npm run typecheck`, reran `npm test` with elevated permissions after the sandbox blocked a local `127.0.0.1` listener, ran `npm run types:check` in `docs`, and ran `git diff --check`. - Observed result: Typecheck completed with `tsc --noEmit`; the OpenCode package test suite reported 2 files and 9 tests passed; docs type generation completed successfully; `git diff --check` produced no output. - Not tested: Browser-rendered documentation preview. `docs: npm run build` was started locally but produced no output for roughly 90 seconds and was stopped, so this follow-up does not claim a fresh local docs build result. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Additional Notes - The linked review comment asked for README examples to match `compressWithHeadroom(messages, options)` and `createHeadroomRetrieveTool` requiring `hash`; both snippets now match the exported API. |
||
|
|
b4571cc346 |
feat: headroom wrap opencode / unwrap opencode CLI (#1105)
## Summary This PR implements transparent `headroom wrap opencode` support without asking users to edit OpenCode provider URLs, choose an extra CLI flag, or maintain a static provider list. The wrapper now lives at the runtime transport boundary: OpenCode keeps its user/provider config, while Headroom intercepts outbound provider traffic in-process and routes it through the local Headroom proxy. ## What changed ### Transparent OpenCode wrapping - `headroom wrap opencode` injects the `headroom-opencode` plugin through `OPENCODE_CONFIG_CONTENT`. - Existing OpenCode provider URLs are preserved. We do not rewrite user config URLs to point at Headroom. - Existing `OPENAI_BASE_URL` and `ANTHROPIC_BASE_URL` env vars are preserved. - Local OpenCode traffic, localhost traffic, and Headroom proxy traffic bypass the shim to avoid loops. ### Runtime transport interception - Added an OpenCode plugin transport shim that wraps: - `globalThis.fetch` - `http.request` / `http.get` - `https.request` / `https.get` - External provider calls are routed to the local Headroom proxy. - The original upstream origin is passed through `x-headroom-base-url`, so the proxy can forward to the real provider without changing OpenCode config. - External `http2.connect` is blocked loudly instead of allowing direct provider traffic to leak outside Headroom. ### Live provider additions Provider coverage is no longer based on a static config scan. Because routing happens at outbound request time, providers added mid-session are routed through Headroom automatically as long as they use the covered Node transport paths. ### Subagent and child-process coverage - The parent OpenCode plugin sets a packaged Node preload shim through `NODE_OPTIONS=--import=.../hook-shim/handler.js`. - The transport shim patches `child_process.spawn`, `exec`, `execFile`, and `fork` so child Node processes receive the Headroom preload even when OpenCode passes a custom `env`. - The child-process shim fails closed if it loads without `HEADROOM_OPENCODE_TRANSPORT_PROXY_URL`. - This closes the subagent leak path where a child Node process could otherwise start without Headroom transport interception. ## Why this goes beyond PR #1089 PR #1089 improves OpenCode provider registration, but it still focuses on provider config shape. This PR moves the enforcement boundary to runtime transport interception. This PR goes further because: - No provider URL rewriting is required. - New providers added mid-session are covered automatically. - Subagents and child Node processes inherit the Headroom transport shim. - Direct external HTTP/2 paths fail loudly instead of leaking. - The wrap remains transparent to the user's OpenCode provider config. - The wrapper is fail-closed for unsupported child-process preload state. ## Additional robustness fixes While validating the change in Docker, the full Python suite exposed unrelated Linux/container robustness issues. These are fixed in this PR so the suite is green: - Binary cache handling now treats cache paths under a non-writable existing parent as unavailable, including when tests run as root in Docker. - `release_version.py` honors `MANUAL_VER` before git calls so direct script execution works outside a `.git` checkout. - Test logger isolation now resets relevant Headroom child loggers so proxy logging setup cannot poison later `caplog` tests. - The scanner missing-path test now uses a guaranteed missing `tmp_path` child instead of relying on `/nonexistent/path`. ## Validation All implementation validation was run inside Docker. - Full Python suite from a fresh Docker copy: `6605 passed, 523 skipped`. - Ruff on changed Python/OpenCode paths: passed. - OpenCode plugin typecheck: passed. - OpenCode plugin tests: `9 passed`. - OpenCode plugin build: passed. - Hook shim preload smoke test: passed. ## Notes This PR intentionally does not add a CLI option. `headroom wrap opencode` means full wrap. Either Headroom wraps OpenCode transparently, or the path fails loudly instead of silently leaking provider traffic. --------- Co-authored-by: Rudimar Ronsoni <6081613+rudironsoni@users.noreply.github.com> |