fix(ai): satisfy OpenCode Zen free-tier gate (403 FreeTierError) (#12306)

[palprateek]

What

I asked for the complete header fix — the canonical opencode/<version> User-Agent plus a stable ses_-shaped session token — implemented on a branch in this repo with tests, and after reviewing the diff extended it to the body-gate (tool-name) half and the 403 error scoping.

OpenCode's Zen/Go gateway refuses requests that don't carry OpenCode's own client
identity. All four gate conditions were verified against the live gateway:

1. User-Agent leading token opencode/<version> — omp now sends opencode/1.18.31
   (explicit caller overrides like the Claude OAuth fingerprint still win)
2. x-opencode-session matching ses_<12 hex><14 alnum> — now a deterministic token
   derived from the conversation id, so routing and prompt-cache pinning survive
   across turns; background traffic (usage polls, discovery) derives from the install id
3. stream: true — omp's agent turns already stream
4. The bash + read tool names in tools[] (any-two-of-five does not
   suffice — the default advisor roster read/grep/glob without bash
   is still refused) — stream() (single funnel behind
   stream/complete/streamSimple) pads calls missing either name (advisors,
   one-shot helpers) with stub entries for the missing pair member; stubs are wire-inert
   and never enter the tool registry

Also scoped the error: a 403 FreeTierError denial is model-scoped client policy, not
a credential problem — it no longer rotates sibling keys or invalidates the stored
credential, and the surfaced message explains the restriction instead of reading like
an auth failure. Shared contract lives in @oh-my-pi/pi-catalog/wire/opencode.

Why

fixes #12306 — community bisection there established all four conditions; two open PRs
(#12325, #12326) each implemented only conditions 1–2, which the bisection shows is
insufficient (tool-less auxiliary calls keep 403ing).

Testing

• bun check clean; pi-ai 4863 pass, pi-catalog 1027/1027 (the 12 pre-existing
  pi-ai env failures reproduce on clean main)

• Live gateway A/B (byte-identical bodies, only identity headers varied):

  Probe	Identity	Result
  free model	old omp (omp/18.2.6 + raw UUID session)	403 FreeTierError
  free model	this branch (opencode/1.18.31 + ses_ token)	429 FreeUsageLimitError (gate passed; quota limiter answered)
  isolation	omp UA + correctly-shaped ses_ session	403 FreeTierError (UA independently required)
  paid SKU	both identities	402 Insufficient funds (gate only guards free SKUs)

  A 429 is the pass condition: the quota limiter only evaluates after the identity
  gate accepts. Wire capture confirmed padding: tool-less requests left the client as
  bash,read.

---

• bun check passes
• Tested locally
• CHANGELOG updated with the required attribution (if user-facing; internal issue fixes use issue links, external contributions add the PR link and contributor credit after creation)

[ForeverInLaw]

≥5 OpenCode core tool names in tools[]

Only two are needed: bash and read

#12306 (comment)

[palprateek]

Addressed in 668b66c: the gate check was weakened from all five tool names to any two. withOpenCodeGateTools now pads tool-less calls with exactly bash + read and leaves any roster already carrying two of the five (bash, edit, glob, grep, read) untouched. Gate tests updated to the two-name threshold; bun check clean, opencode suites green (98 pass).

[roboomp]

Thanks @palprateek — thorough, well-scoped fix for the OpenCode free-tier 403 with live A/B evidence, changelog entries in both touched packages, docs, and contract-level tests. Rank: P1 — the four-part fix (canonical opencode/* UA, deterministic ses_ session token via toOpenCodeSessionToken, tool-name body padding, non-rotating/model-scoped error classification) is correct and conventional; one behavioral tradeoff deserves a maintainer decision before merge.

Findings:

• stream.ts (should-fix / question): withOpenCodeGateTools advertises real tool names (bash/edit/glob/grep/read) with empty descriptions on every OpenCode request, including tool-less auxiliary calls. Nothing sets toolChoice, so the model can emit a phantom tool call on an advisor/one-shot turn whose caller expects text and has no exec handler — yielding empty .text. Net still positive vs a hard 403, but worth confirming toolChoice: "none" (or equivalent) was considered, plus a test that auxiliary completions still return text.
• google-shared.ts (nit): the added provider arg to finalize is unrelated to #12306 (Google never matches the opencode/copilot/cline/ollama rewrites); harmless, just widens the diff.

Correctness spot-checks passed: applyInferenceHeaders preserves prior behavior for non-OpenCode/no-session paths; toOpenCodeSessionToken output satisfies OPENCODE_SESSION_TOKEN_PATTERN (26-char shape); Claude OAuth fingerprint still wins via setHeaderIfAbsent; padding funnels through streamDispatch for stream/complete/streamSimple. Minor doc drift: the stream.ts comment says the gate "requires at least five" tool names while the PR body says the gate now needs only two — padding all five is a safe superset, so no action needed.

Not anchored to diff

• packages/ai/src/stream.ts:958 — should-fix / maintainer question: withOpenCodeGateTools advertises real tool names (bash, edit, glob, grep, read) with empty descriptions on every OpenCode request, including tool-less auxiliary calls (advisors, one-shot helpers via streamSimple/completeSimple). The stubs are wire-inert for the gate, but they are still valid tool declarations the model sees — nothing here sets toolChoice, so the model can emit a bash/read tool call on an auxiliary turn whose caller has no exec handler and expects text. The result is an AssistantMessage with a tool call and empty .text, i.e. a silently broken advisor/summary for OpenCode free models. Before padding, those calls hard-403; after, they mostly work but carry this new failure mode. Was forcing toolChoice: "none" (or otherwise suppressing invocation) considered for the padded case? A test that a tool-less auxiliary completion still yields text (not a phantom tool call) would lock this down.

[palprateek]

Addressed the roboomp review in 8711894: padded tool-less OpenCode calls now pin toolChoice to none (explicit caller choices still win; rosters carrying real tools are untouched so agent turns keep full tool use). The gate reads tools[], not tool_choice, so the pin is gate-neutral. New tests assert the wire body (bash,read + tool_choice:none) and that the auxiliary turn still returns text. bun check clean; branch re-merged onto latest main and MERGEABLE.

[palprateek]

@can1357 — ready for your gates: branch MERGEABLE at 6323af0, 0 unresolved threads, roboomp's findings addressed (toolChoice:none pin + google-shared rationale). Needs you: (1) approve the pending fork workflow runs (CI 35737735017, OMP Nix 35737735116 — action_required), (2) review approval. bun check clean; targeted suites green.

[palprateek]

@roboomp please re-review the latest head — your stream.ts toolChoice question is fixed (tool_choice:none pin in 8711894, plus wire tests) and the google-shared nit is answered in its thread. Latest head: 6323af0.

[palprateek]

Rebased onto latest main (merge cf6fce4) — GitHub now reports MERGEABLE, 0 unresolved threads. bun check clean; gate suites green (pi-ai 75 pass across the 4 OpenCode/auth suites, pi-catalog opencode-provider 26 pass).

Still needs a maintainer: (1) approve the fork workflow runs (action_required), (2) review approval — roboomp's stream.ts toolChoice question was fixed in 8711894 with wire tests. @can1357

[palprateek]

Rebased onto latest main (merge 120995f) — GitHub now reports MERGEABLE, 0 unresolved threads. bun run check:ts clean; gate suites green (101 pass across the 5 OpenCode/auth suites, plus Vercel attribution 7 pass).

Still needs a maintainer: (1) approve the fork workflow runs (36322064606 CI, 36322064604 OMP Nix — action_required), (2) review approval — roboomp's stream.ts toolChoice question was fixed in 8711894 with wire tests. @can1357

[palprateek]

Re-merged onto latest main (3b9375b) — MERGEABLE again, 0 unresolved threads. One resolution note: kept the strengthened usage-attribution test over aa5aab0's deletion — it now asserts the exact gateway wire shape the gate enforces, not the old existence checks. Suites green (102 pass), check:ts clean.

Still needs a maintainer: (1) approve fork runs (36546257086 CI, 36546257057 OMP Nix — action_required), (2) review approval. @can1357

[palprateek]

Re-merged onto latest main (b53c11c) — MERGEABLE, 0 unresolved threads. Docs resolution: kept this PR's free-tier gating bullet; accepted main's consolidation of the pre-existing whenThinking/big-pickle notes. Suites green (102 pass).

Still needs a maintainer: (1) approve fork runs (37117180238 CI, 37117180217 OMP Nix — action_required), (2) review approval. @can1357

[palprateek]

Re-merged onto latest main (9667937) — MERGEABLE, 0 unresolved threads. Resolution: gate-tool padding now layers on top of main's withSupportedSamplingParams wrapper in streamDispatch. check:ts clean, suites green (102 pass).

Still needs a maintainer: (1) approve fork runs (37123450011 CI, 37123450010 OMP Nix — action_required), (2) review approval. @can1357

[palprateek]

Re-merged onto latest main (fcdfa63) — MERGEABLE, 0 unresolved threads. Resolution: adopted main's in-flight-limit plumbing and import cleanup in stream.ts, gate padding intact. check:ts clean, suites green (102 pass).

Still needs a maintainer: (1) approve fork runs (37628087751 CI, 37628087677 OMP Nix — action_required), (2) review approval. @can1357

[NoelJacob]

Warning: advisor: Advisor unavailable for opencode-zen/big-pickle: OpenCode rejected this request
with 403 FreeTierError: its free tier can only be used from within OpenCode. Your API key is valid —
paid models on the same key keep working. Pick a paid model with /model; if this model is expected
to work in omp, the gateway's gate has likely changed and the regression should be reported.

It seems the endpoint mandatorily needs read and bash tool.

The adviser does not work with the latest commit and this pull request merged on top

[palprateek]

@NoelJacob — good catch, confirmed and fixed in d4938e2: the padding only fired below two-of-five, but your advisor roster carries read/grep/glob with no bash, so nothing was padded and the gate still refused it. The rule is now the specific bash+read pair (matching your finding): the advisor gets a bash stub with no tool_choice pin since it owns real tools. Regression test included. Could you re-test the advisor on this head?

[palprateek]

Re-merged onto latest main (13c7e36) — MERGEABLE, 0 unresolved threads, clean auto-merge. Suites green (111 pass), check:ts clean. Includes the bash+read pair fix for the advisor 403.

Still needs a maintainer: (1) approve fork runs (38123553676 CI, 38123553639 OMP Nix — action_required), (2) review approval. @can1357

[NoelJacob]

check this https://github.com/NoelJacob/oh-my-pi/tree/fix-opencode-zen-gated @palprateek

[palprateek]

Reviewed and ported in 6a92d10 — thank you, all three parts were valuable: (1) your October partial-combo bisection is now cited in the wire comment as the evidence for the pair rule, (2) withOpenCodeGateShape is now shared by both funnels (plus your funnel-coverage tests), (3) the none pin stays off openai-responses. Credited you in the changelog entry. Could you verify the advisor works on this head and confirm the Responses-400 concern from your testing? @NoelJacob

[NoelJacob]

Yes it works

[palprateek]

@roboomp @can1357 — requesting re-review on the latest head (6f3276c, re-merged onto main; mergeability recomputing). Since your last look: (1) the gate rule is now the specific bash+read pair, not any-two-of-five — NoelJacob's advisor 403 proved a read/grep/glob roster without bash still 403s; (2) the padding logic is now the shared withOpenCodeGateShape helper applied in both dispatch funnels, with the tool_choice:none pin kept off openai-responses (NoelJacob collab, credited in changelog). Suites green (113 pass), check:ts clean, 0 unresolved threads. (Note: I can't re-request via the API — no permission — so this comment is the request.)

[VeilSilence]

Despite all of this, today I hit issue again. Trying to figure what/why cause this.