You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit d8208f9
Browse filesBrowse the repository at this point in the historyBrowse files
feat(opencode): the free tier reads the tool catalogue, so MCC sends OpenCode's (#134)
**Broken.** Since some moment in the twelve silent hours before 2026-09-18
00:52 UTC, every MCC request to an OpenCode Zen free model has been answered
HTTP 403 `FreeTierError` -- "OpenCode's free tier can only be used from within
OpenCode". Twenty such attempts are in the request log, all on 2026-09-18,
none before; the last 200 from that host was 2026-09-17 16:48. MCC filed them
as `authentication` / "Provider authentication failed. Check API key.", which
sent the investigation looking at a credential that was never wrong.
**Mechanism.** It is not our regression. Identity code is byte-identical at
v6.74.0, v7.13.0, v7.18.1, v7.23.0 and v7.26.1; no release falls on the
boundary; the installed client 1.18.31 sends the same five headers 1.18.30
did. The gate moved server-side and into the *body*: it now classifies the
request's tool catalogue. Measured 2026-09-18 with MCC's headers untouched in
every row (specs/INVESTIGATION-ZEN-403-FREETIER.md):
E tools bash, edit, glob, grep, read -> 200, SSE stream
F tools Bash, Edit, Glob, Grep, Read -> 403 FreeTierError
A no tools at all -> 403 FreeTierError
H both casings in one catalogue -> 500 server_error, twice
The maintainer said so on the record the same day: "You cannot use the free
tier in other harnesses." Probe H is the constraint on any fix: two tool names
differing only in case are not a catalogue, they are a collision.
**Fix.** On free-tier OpenCode models only, MCC now *translates*. Outbound,
Claude Code's `Bash`/`Read`/`Edit`/`Glob`/`Grep` go as `bash`/`read`/`edit`/
`glob`/`grep` -- spellings read out of the shipped `[email protected]`
bundle (`var IE="bash"`, `var KE="read"`, `var m_="edit"`, `var uE="glob"`,
`var BE="grep"`), not guessed. Every other tool name goes through the 7.18.1
alias codec, which now also aliases away any name that would collide
case-insensitively with a catalogue spelling. Inbound, every tool call is
mapped back before Claude Code sees it, on all three surfaces. No decoy tool
is ever appended.
Scope is data, never a model-name branch: a new `FreeTierToolCatalogue` on the
two OpenCode profiles, admitting a model whose id carries `-free`/`:free`, one
the catalogue prices at zero on that host, or one the operator listed in the
new `OPENCODE_FREE_TIER_MODELS` (default `big-pickle`, which is free and does
not say so). `OPENCODE_CLIENT_IDENTITY=mcc` turns the whole impersonation off.
Three more things the same evidence asked for:
* the user-agent now carries all three segments the real client puts on the
wire -- `opencode/<ver> ai-sdk/provider-utils/4.0.40 runtime/bun/1.3.14`,
re-captured from 1.18.31 on 2026-09-19 -- with the two appended segments
pinnable (`OPENCODE_CLIENT_AI_SDK_VERSION`, `OPENCODE_CLIENT_RUNTIME`);
* `FreeTierError` gets its own `FailureKind.FREE_TIER`: no key bench, no proxy
bench, the chain falls through, and its own sentence instead of "check API
key";
* a tool-less request on a free model still fails, deliberately. The real
OpenCode CLI sends no `tools` key at all on its own title sub-request
(captured 2026-09-19), which is why its free tier refuses that client's own
subagents too (anomalyco/opencode#49592, #49723). Inventing a catalogue MCC
cannot honour would be the larger lie.
**Verification, with real output.**
Golden A/B against a second worktree at v7.27.0, four bodies:
zen_paid byte_identical=True
chat_groq byte_identical=True
zen_free 7.27.0: ['Bash','Read','Edit','Glob','Grep','Write','mcp__...bf22fa52f4e59643']
7.28.0: ['bash','read','edit','glob','grep','Write','mcp__...bf22fa52f4e59643']
zen_big_pickle same two lines
The 68-character MCP name aliases to the same bytes on both sides, so the
prompt-cache prefix does not move.
uv run --offline pytest -q -p no:randomly --ignore=tests/api/test_admin_static_jsdom.py
12388 passed, 69 skipped, 1 warning in 283.76s
uv run --offline pytest -q -p no:randomly -n 2 tests/api/test_admin_static_jsdom.py
4 failed, 329 passed in 251.55s
-- the identical four fail on clean fork/main (334.80s): zero regression.
ruff format --check . 1086 files already formatted
ruff check . All checks passed!
ty check All checks passed!
`git diff fork/main` over credential_rotation, rate_limit, execution,
route_health, proxy_rotation, proxy_rotating, routing, reasoning,
output_tokens, cli/, scripts/ and desktop-shell/: empty.
Live, through a scratch server on D: with the user's key: three attempts, all
answered HTTP 429 `FreeUsageLimitError`. That limiter runs *before* the
free-tier classifier, so those attempts never reached the gate and say nothing
about the 403 either way. What they do prove is the bytes -- the recorded wire
body on both `muse-spark-1.3-contributor-free` (tagged) and `big-pickle`
(untagged, admitted by the new setting) carries
`['bash','read','edit','glob','grep','mcp__...bf22fa52f4e59643']`, the
three-segment user-agent, `stream: true` and the five identity headers.
**Not done.** No live 200 was obtained: the account is rate-limited per IP and
a 429 is inconclusive. The Messages surface is implemented and unit-tested but
has no live free model to exercise it. And a free-tier refusal still reaches
`credential_failure_class`'s status fall-through, which is why the failure
carries 402 rather than the host's 403 -- teaching that function the kind
directly would mean editing a file this PR must leave byte-identical, and
belongs in its own patch.
by FiredMosquito831
Copy file name to clipboardExpand all lines: docs/ROUTING-REFERENCE.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -170,7 +170,7 @@ The card keeps the *unselected* mode's fields visible but disabled, each carryin
170
170
171
171
| Setting | Default | What it does |
172
172
| --- | --- | --- |
173
-
|`FALLBACK_SKIP_KINDS`|`invalid_request`| Comma-separated failure kinds that abort the chain instead of falling through. Known kinds: `invalid_request`, `model_rejected`, `context_length`, `authentication`, `permission`, `quota`, `rate_limit`, `overloaded`, `timeout`, `upstream`, `unavailable`. Since 6.46.0 `invalid_request` means only a 400 whose own message says the request is *malformed*; every other 400 is `model_rejected` and falls through. Set `FALLBACK_SKIP_KINDS=invalid_request,model_rejected,context_length` to restore the pre-5.43.0 behaviour of giving up on any `400`. `quota` is deliberately absent from the default: an account out of credits says nothing about the request, and the next key or the next model may well answer it. |
173
+
|`FALLBACK_SKIP_KINDS`|`invalid_request`| Comma-separated failure kinds that abort the chain instead of falling through. Known kinds: `invalid_request`, `model_rejected`, `context_length`, `authentication`, `permission`, `quota`, `rate_limit`, `overloaded`, `timeout`, `upstream`, `unavailable`, `free_tier`. Since 6.46.0 `invalid_request` means only a 400 whose own message says the request is *malformed*; every other 400 is `model_rejected` and falls through. Set `FALLBACK_SKIP_KINDS=invalid_request,model_rejected,context_length` to restore the pre-5.43.0 behaviour of giving up on any `400`. `quota` is deliberately absent from the default: an account out of credits says nothing about the request, and the next key or the next model may well answer it. |
174
174
175
175
**Thinking is not answering.** A reasoning model that streams its thoughts and never writes an answer used to commit the route on its very first thought: from that moment no other model could take over, the stall guard never fired because thoughts kept arriving, and the request ran until the whole budget ended it. Measured across 21 days of real traffic, 44 of 499 budget exhaustions were a stream that had only reasoned, and 490 of the 499 never left the first model on the chain.
[#49723](https://github.com/anomalyco/opencode/issues/49723)). Adding a
2695
+
catalogue MCC cannot honour, to a request the client it names would not have
2696
+
added one to, would be a worse lie than the one being refused.
2697
+
2698
+
Such a refusal is now its own failure kind, `free_tier`, instead of
2699
+
`authentication`. It does not bench the key (the key is fine), it does not
2700
+
bench the proxy (the same account is refused from every address), and the
2701
+
route falls through to the next model.
2702
+
2703
+
**Expect this to break again.** The vendor tightened this gate three times in
2704
+
48 hours and has said on the record that the free tier is harness-locked
2705
+
policy. Everything above is written to be re-measured — one mapping, one
2706
+
predicate, three settings — rather than to be clever. The durable paths remain
2707
+
a paid Zen key or OpenCode Go.
2708
+
2647
2709
**OpenCode Go is unverified.** The vendor said on 2026-09-03 that Go requests
2648
2710
must carry the conversation header and began enforcing it on 2026-09-06. MCC
2649
2711
sends it, under the same rule as Zen. Both live Go probes were answered
@@ -4734,6 +4796,9 @@ Only the keys whose value or meaning moved in 6.0.0–6.8.0. Everything else in
4734
4796
|`HARNESS_TIER_ALIASES`|`true`|**New in 6.38.0.** Lists `mcc/cyber`, `mcc/best`, `mcc/good`, `mcc/medium`, `mcc/cheap` and `mcc/vision` at the top of every coding agent's generated picker, each a name for one of MCC's own routes rather than a model of its own. Off keeps those pickers to concrete refs; the router still resolves an alias a client sends anyway, so an agent already configured on one keeps working. Per-agent chains live in `~/.mcc/harness_tiers.json`, written by the **Coding agents** page. See [Tiers for every other coding agent](#tiers-for-every-other-coding-agent). |
4735
4797
|`OPENCODE_CLIENT_IDENTITY`|`opencode`|**New in 6.69.0.** Which client MCC identifies as to OpenCode Zen and OpenCode Go, both of which read identity headers off every request. `opencode` sends the official client's user-agent and client id, which is what the free tier's limiter recognises; `mcc` sends `my-claude-code` and this version instead. The conversation, request and project headers go either way. See [OpenCode Zen and OpenCode Go: what MCC sends about itself](#opencode-zen-and-opencode-go-what-mcc-sends-about-itself). |
4736
4798
|`OPENCODE_CLIENT_VERSION`|*(empty)*|**New in 6.69.0.** Pins the OpenCode release named in that user-agent. Empty reads it from the `opencode-ai` package installed on this machine, and falls back to the release this build was verified against. Only used when `OPENCODE_CLIENT_IDENTITY` is `opencode`. |
4799
+
|`OPENCODE_CLIENT_AI_SDK_VERSION`|*(empty)*|**New in 7.28.0.** The middle segment of the user-agent the real OpenCode client sends — `ai-sdk/provider-utils/<this>`. Its own HTTP transport appends it, so unlike the release above it cannot be read off this machine; empty sends the version captured from the client this release was built against. Only used when `OPENCODE_CLIENT_IDENTITY` is `opencode`. |
4800
+
|`OPENCODE_CLIENT_RUNTIME`|*(empty)*|**New in 7.28.0.** The last user-agent segment, written `<runtime>/<version>` and sent as `runtime/<that>` — `bun/1.3.14` on the captured client. Empty sends the captured value. Only used when `OPENCODE_CLIENT_IDENTITY` is `opencode`. |
4801
+
|`OPENCODE_FREE_TIER_MODELS`|`big-pickle`|**New in 7.28.0.** Comma-separated Zen/Go model ids that are on the free tier without saying so in their name. On these — and on any id ending `-free` or `:free`, and any model the catalogue prices at zero here — MCC sends OpenCode's own tool-name spellings and translates the model's calls back, because that tier answers `403` to any other catalogue. Every other model keeps the request it has always been sent. See [The free tier now reads your tool names](#the-free-tier-now-reads-your-tool-names). |
4737
4802
|`SERVER_STALE_SERVER_ACTION`|`report`|**New in 6.72.2.** What the server does about other My Claude Code servers it finds at start. `report` names each one in the server log — pid, session, recorded port, start time, last heartbeat, and the files it holds open — and stops nothing. `stop` also stops the ones this install can prove are finished: a heartbeat silent past `SERVER_STALE_SESSION_SECONDS` whose recorded port is now served by a different MCC, or a launcher whose server process is gone. A server is never stopped merely for owning no listening socket. |
4738
4803
|`SERVER_STALE_SESSION_SECONDS`|`900`|**New in 6.72.2.** How long another server's heartbeat must be silent before the word "stale" is available for it. A running server checks in every 30 s, so the default is thirty missed beats. Silence alone never stops anything. Range 60–86400. |
4739
4804
|`SERVER_PORT_TAKEOVER`|`always`|**New in 6.59.0.** What happens when the server starts and its port is already held. `always` stops the holder and takes the port; a holder that is not MCC is named in one `WARNING` line first. Setting it to mcc-only stops only processes this install can identify as its own; never is the pre-6.59.0 behaviour — name the holder and refuse to start. Identification is by process, never by the HTTP answer. |
Copy file name to clipboardExpand all lines: packaging/npm/package.json
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
{
2
2
"name": "@firedmosquito831/my-claude-code",
3
-
"version": "7.27.0",
3
+
"version": "7.28.0",
4
4
"description": "My Claude Code (MCC): a local multi-provider LLM proxy, model router and control plane for Claude Code, Codex, OpenCode, Gemini CLI and other AI coding agents, with 57 providers, fallback routing, credential health, a native web-search tool proxy, and analytics with cost provenance. This npm package installs and launches the Python server.",
Copy file name to clipboardExpand all lines: pyproject.toml
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
5
5
[project]
6
6
name = "my-claude-code"
7
-
version = "7.27.0"
7
+
version = "7.28.0"
8
8
description = "Local multi-provider LLM proxy, model router and control plane for Claude Code, Codex, OpenCode, Gemini CLI and other AI coding agents: 57 providers, fallback routing, credential health, a native web-search tool proxy, and analytics with cost provenance"
0 commit comments