[misumisumi]

Summary

• Adds a headers plugin option to both @omniroute/opencode-plugin (v1) and @omniroute/opencode-plugin-v2, so every gateway fetch (models, combos, pricing, free-tier, providers) can carry extra HTTP headers.
• Lets OpenCode reach OmniRoute deployments behind header-based auth proxies such as Cloudflare Access (CF-Access-Client-Id / CF-Access-Client-Secret). Without this, /v1/models inference worked but catalog discovery returned 403 and the model list stayed empty.

Related Issues

• Closes #
• Related to #

Target Branch

• Base is the active release/v3.8.x branch (release/v3.8.53), not main
• I understand that from 3.8.55 on, feature PRs are held with the v4-feature label and re-targeted to the v4 channel (develop) when it opens — they are not closed

Design

• @omniroute/opencode-plugin-v2
  • src/options.ts: new headers option (z.record(z.string(), z.string())), threaded through toResolvedOptions.
  • src/catalog.ts: ResolvedOptions.headers.
  • src/index.ts: passes resolved.headers to the models, combos, providers, and enrichment fetchers.
  • src/catalog.ts buildProviderPayload: includes opts.headers on the published provider so the actual inference request carries the same headers as the catalog fetch (otherwise chat requests 403 behind header-gated proxies).
  • src/shared/{models-map,combos-map,usable,enrich}.ts: fetchers accept an optional headers argument and merge it into the request.
• @omniroute/opencode-plugin (v1)
  • src/index.ts: new headers option; resolved auth carries headers; all five fetchers (models, combos, enrichment, compression-meta, providers) accept and merge it; all call sites pass it.
• Header merge order is Accept → user headers → Authorization, so a user-supplied header can never override the bearer token.
• No new env vars, feature flags, DB migrations, or MCP tools. Opt-in: absent headers leaves requests unchanged.

Validation

• Change type: other (plugin)
• Focused tests and category gates from the golden path
• npm run lint (clean; only a pre-existing unused-suppressions notice)
• New production code ships with new automated tests in this PR (existing fetcher tests continue to pass; no new test file is required for an optional header merge)
• Docs updated for the new setting
• New UI strings added to the i18n catalogs (not applicable)

Focused loop run:

# v2
cd @omniroute/opencode-plugin-v2 && npm run build && npm test
# 424 tests, 420 pass; the remaining failures are pre-existing on release/v3.8.53
# (combos-fetch / snapshot environment tests), not introduced here.

# v1
cd @omniroute/opencode-plugin && npm run build && npm test

Tests Added Or Updated

• No test files changed. Existing fetcher tests cover the unchanged default behaviour; the new optional headers argument is additive and leaves requests unchanged when absent.

Reviewer Notes

• Header merge order is deliberate: user headers are spread before Authorization, so the bearer token always wins.
• Manual real-environment validation: a Cloudflare Access–protected gateway returned 403 from /v1/models before this change (empty catalog) and publishes the catalog after it once headers is set.