Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors
TypeScript a2aai-agentsai-gatewayanthropicclaudeclaude-codeclinecodexcopilotcursordeepseekfree-aigeminikimillm-gatewaymcpopenaiopenai-proxyqwentoken-saver
/**
* OpenCode Zen free-tier request contract.
*
* Since 2026-09-17 the free tier answers 403 FreeTierError unless the request carries
* all four of: `stream: true`, a non-empty `tools` array, an `x-opencode-session` (or
* `x-session-id`) shaped `ses_` + 12 hex + 14 base62, and a `User-Agent` containing
* `opencode/<version >= 1.17>`. Removing any one of the four turns a 200 into a 403, and
* a version below 1.17 answers 426 instead.
*
* Measured again on 2026-09-18, and the tools condition is narrower than it first looked:
* the upstream inspects which names are declared. One made-up name, twelve made-up names
* and twelve plausible names borrowed from another vocabulary are all refused, while six,
* nine and twelve names from the official client pass; three of those same names are
* refused. What the upstream takes also differs by model and moves between days, which is
* why the placeholder is resolved at runtime rather than pinned here.
*
* `tool_choice` is never imposed on any surface: the upstream rejects every value but
* "auto" with a 400 invalid_request_error (`only "auto" is supported for tool_choice`).
*
* Paid models on the same host are not gated (one without tools answers 401), so the
* request contract applies to free-tier models only.
*
* Measured again on 2026-10-14: the free tier moved to https://opencode.ai/inference/v1
* (the base the client now takes from the models.dev catalog), and the very same request
* body is refused 403 on /zen/v1. On the new base the tools condition also narrows: a
* declared `read` or `bash` needs a non-empty parameter schema, while an empty schema on
* a name outside the quartet still passes.
*/
import { test } from "node:test";
import assert from "node:assert/strict";
import {
_setOpencodeFreeModelsForTests,
applyFreeTierRequestContract,
configuredPlaceholderToolNames,
DEFAULT_PLACEHOLDER_TOOL_NAME,
isPremiumOpencodeModel,
mergeClientToolsWithObserved,
noteFreeTierOutcome,
placeholderToolParameters,
prepareFreeTierRequest,
isGatedFreeTierRequest,
requiresFreeTierRequestContract,
surfaceFromBaseUrl,
} from "../../open-sse/executors/opencodeFreeTierContract.ts";
import {
_resetToolObservationForTests,
getObservedToolNames,
recordAcceptedToolNames,
resolvePlaceholderNames,
} from "../../open-sse/executors/opencodeToolObservation.ts";
import {
DEFAULT_OPENCODE_USER_AGENT,
clientSuppliedOpencodeSession,
forwardOpencodeClientHeaders,
isValidOpencodeSessionValue,
satisfiesOpencodeUserAgentContract,
} from "../../open-sse/utils/opencodeHeaders.ts";
import { OpencodeExecutor } from "../../open-sse/executors/opencode.ts";
/**
* The free tier validates the session *value* (the 12-hex time part must decode to the
* client's `Identifier.descending()` counter window `0xFC0–0xFFF`), not just its shape.
* Asserting `OPENCODE_SESSION_PATTERN` alone would accept an out-of-window counter that
* the upstream 403s, so every synthesized session is checked through the value-level
* validator instead.
*/
function assertDescendingSession(value: string | undefined, message?: string): void {
assert.equal(isValidOpencodeSessionValue(value), value, message);
}
const CHAT_BODY = () => ({
model: "nemotron-3.5-lightning-free",
messages: [{ role: "user", content: "hi" }],
});
const RESPONSES_BODY = () => ({
model: "muse-spark-1.3-contributor-free",
input: [{ role: "user", content: "hi" }],
});
test("the contract applies to free-tier models on the gated surface only", () => {
assert.equal(
requiresFreeTierRequestContract("zen", "opencode", "nemotron-3.5-lightning-free"),
true
);
assert.equal(requiresFreeTierRequestContract("zen", "opencode-zen", "big-pickle"), true);
assert.equal(
requiresFreeTierRequestContract("zen", "opencode-zen", "muse-spark-1.3-contributor-free"),
true
);
assert.equal(requiresFreeTierRequestContract("zen", "opencode-zen", "gpt-5.6-luna"), false);
// The other surface refuses a request that carries tools rather than one that does not
// (upstream anomalyco/opencode#44300 and #44382), so it is never brought up to this
// contract — including for a free model.
assert.equal(requiresFreeTierRequestContract("go", "opencode-go", "big-pickle"), false);
assert.equal(requiresFreeTierRequestContract("go", "opencode-go", "ox-alpha-free"), false);
assert.equal(requiresFreeTierRequestContract("other", "groq", "big-pickle"), false);
});
test("with the synced catalog pinned, only its ids count as free", () => {
// A model the catalog omits is premium even with a `-free` suffix (the upstream
// delisted it — the stale-table failure the catalog rule fixes); a listed id is free.
_setOpencodeFreeModelsForTests(["big-pickle", "nemotron-3.5-lightning-free"]);
try {
assert.equal(requiresFreeTierRequestContract("zen", "opencode", "big-pickle"), true);
assert.equal(
requiresFreeTierRequestContract("zen", "opencode", "nemotron-3.5-lightning-free"),
true
);
assert.equal(requiresFreeTierRequestContract("zen", "opencode", "delisted-model-free"), false);
} finally {
_setOpencodeFreeModelsForTests(null);
}
});
test("the surface is told apart by base url, so the `oc` alias needs no special case", () => {
assert.equal(surfaceFromBaseUrl("https://opencode.ai/zen/v1"), "zen");
assert.equal(surfaceFromBaseUrl("https://opencode.ai/zen/go/v1"), "go");
assert.equal(surfaceFromBaseUrl("https://api.groq.com/openai/v1"), "other");
assert.equal(surfaceFromBaseUrl(undefined), "other");
});
test("chat completions: the contract adds streaming and a placeholder tool, and no tool_choice", () => {
const body = applyFreeTierRequestContract(CHAT_BODY(), "openai") as Record<string, unknown>;
assert.equal(body.stream, true);
const tools = body.tools as Array<{ type: string; function: { name: string } }>;
assert.equal(tools.length, 1);
assert.equal(tools[0].type, "function");
assert.equal(tools[0].function.name, DEFAULT_PLACEHOLDER_TOOL_NAME);
// The upstream answers 400 `only "auto" is supported for tool_choice` (measured
// 2026-09-18 on the Chat Completions surface), so none is imposed here either.
assert.equal("tool_choice" in body, false);
});
test("the placeholder carries the names it is given, one entry each", () => {
const body = applyFreeTierRequestContract(CHAT_BODY(), "openai", [
"glob",
"grep",
"read",
]) as Record<string, unknown>;
const tools = body.tools as Array<{ function: { name: string; parameters: object } }>;
assert.deepEqual(
tools.map((t) => t.function.name),
["glob", "grep", "read"]
);
// Injected quartet members carry the minimal schema the gate accepts: since 2026-10-14 a
// declared `read` with `properties: {}` turns the request into a 403 on /inference/v1.
assert.deepEqual(tools[0].function.parameters, {
type: "object",
properties: { pattern: { type: "string" } },
required: ["pattern"],
});
assert.deepEqual(tools[2].function.parameters, {
type: "object",
properties: { filePath: { type: "string" } },
required: ["filePath"],
});
});
test("placeholderToolParameters: quartet members get a minimal schema, others stay empty", () => {
// Measured 2026-10-14 on /inference/v1: `read` + `bash` with `properties: {}` is refused
// 403, the same pair with `{command}` on `bash` passes, and a request with no
// property-bearing `read` is refused — while an empty schema on a name outside the
// quartet (`webfetch`, `_noop`) still passes.
assert.deepEqual(placeholderToolParameters("bash"), {
type: "object",
properties: { command: { type: "string" } },
required: ["command"],
});
for (const name of ["bash", "glob", "grep", "read"]) {
const schema = placeholderToolParameters(name) as { properties: Record<string, unknown> };
assert.ok(Object.keys(schema.properties).length > 0, name);
}
assert.deepEqual(placeholderToolParameters("_noop"), { type: "object", properties: {} });
assert.deepEqual(placeholderToolParameters("webfetch"), { type: "object", properties: {} });
});
test("responses: several placeholder names keep the flat shape and no tool_choice", () => {
const body = applyFreeTierRequestContract(RESPONSES_BODY(), "openai-responses", [
"glob",
"grep",
]) as Record<string, unknown>;
const tools = body.tools as Array<{ type: string; name: string }>;
assert.deepEqual(
tools.map((t) => t.name),
["glob", "grep"]
);
assert.equal("tool_choice" in body, false);
});
test("an empty tools array counts as no tools", () => {
// It is the exact shape the upstream refuses — the official client sends it on its own
// compaction path (upstream anomalyco/opencode#49433).
const body = applyFreeTierRequestContract({ ...CHAT_BODY(), tools: [] }, "openai") as Record<
string,
unknown
>;
assert.equal((body.tools as unknown[]).length, 1);
});
test("responses: the placeholder tool is flat and tool_choice stays absent", () => {
// The upstream Responses surface rejects tool_choice with a 400 invalid_request_error
// (measured on both "none" and {type:"none"}), so the contract must not send it there.
const body = applyFreeTierRequestContract(RESPONSES_BODY(), "openai-responses") as Record<
string,
unknown
>;
assert.equal(body.stream, true);
const tools = body.tools as Array<{ type: string; name: string }>;
assert.equal(tools.length, 1);
assert.equal(tools[0].type, "function");
assert.equal(tools[0].name, DEFAULT_PLACEHOLDER_TOOL_NAME);
assert.equal("tool_choice" in body, false);
});
test("client-supplied tools are never replaced, required placeholders are appended, and no tool_choice is imposed", () => {
const clientTools = [
{ type: "function", function: { name: "search", parameters: { type: "object" } } },
];
const body = applyFreeTierRequestContract(
{ ...CHAT_BODY(), tools: clientTools },
"openai"
) as Record<string, unknown>;
const tools = body.tools as Array<{ type: string; function?: { name: string } }>;
assert.equal(tools.length, 2);
assert.equal(tools[0].function?.name, "search");
assert.equal(tools[1].function?.name, DEFAULT_PLACEHOLDER_TOOL_NAME);
assert.equal("tool_choice" in body, false);
assert.equal(body.stream, true);
});
test("when client-supplied tools already include placeholder tools, nothing extra is added", () => {
const clientTools = [
{ type: "function", function: { name: "search", parameters: { type: "object" } } },
{
type: "function",
function: { name: DEFAULT_PLACEHOLDER_TOOL_NAME, parameters: { type: "object" } },
},
];
const body = applyFreeTierRequestContract(
{ ...CHAT_BODY(), tools: clientTools },
"openai"
) as Record<string, unknown>;
assert.deepEqual(body.tools, clientTools);
});
test("when client-supplied tools are present, multiple configured placeholders are appended", () => {
const clientTools = [
{ type: "function", function: { name: "run_code", parameters: { type: "object" } } },
];
const body = applyFreeTierRequestContract({ ...CHAT_BODY(), tools: clientTools }, "openai", [
"glob",
"grep",
"read",
"edit",
"write",
"bash",
]) as Record<string, unknown>;
const tools = body.tools as Array<{ type: string; function?: { name: string } }>;
assert.equal(tools.length, 7);
assert.equal(tools[0].function?.name, "run_code");
assert.deepEqual(
tools.slice(1).map((t) => t.function?.name),
["glob", "grep", "read", "edit", "write", "bash"]
);
});
test("a client tool_choice is preserved", () => {
const body = applyFreeTierRequestContract(
{ ...CHAT_BODY(), tool_choice: "auto" },
"openai"
) as Record<string, unknown>;
assert.equal(body.tool_choice, "auto");
});
test("applying the contract twice does not duplicate the placeholder tool", () => {
const once = applyFreeTierRequestContract(CHAT_BODY(), "openai");
const twice = applyFreeTierRequestContract(once, "openai") as Record<string, unknown>;
assert.equal((twice.tools as unknown[]).length, 1);
});
test("an unknown body format only gets the streaming flag", () => {
const body = applyFreeTierRequestContract(CHAT_BODY(), "claude") as Record<string, unknown>;
assert.equal(body.stream, true);
assert.equal("tools" in body, false);
assert.equal("tool_choice" in body, false);
});
test("the user-agent contract accepts a versioned opencode client and rejects the rest", () => {
assert.equal(satisfiesOpencodeUserAgentContract(DEFAULT_OPENCODE_USER_AGENT), true);
assert.equal(satisfiesOpencodeUserAgentContract("opencode/1.17.0"), true);
assert.equal(satisfiesOpencodeUserAgentContract("opencode/beta/1.18.31/cli"), true);
assert.equal(
satisfiesOpencodeUserAgentContract("opencode/1.18.14 ai-sdk/provider-utils/4.0.23"),
true
);
// Measured: 1.16.0 answers 426 UpgradeRequired, so it does not satisfy the contract.
assert.equal(satisfiesOpencodeUserAgentContract("opencode/1.16.0"), false);
assert.equal(satisfiesOpencodeUserAgentContract("opencode-cli/1.0.0"), false);
assert.equal(satisfiesOpencodeUserAgentContract("opencode"), false);
assert.equal(satisfiesOpencodeUserAgentContract("curl/8.5.0"), false);
assert.equal(satisfiesOpencodeUserAgentContract(undefined), false);
});
test("synthesized identity headers carry a canonical session and request id", () => {
const headers: Record<string, string> = {};
forwardOpencodeClientHeaders(
headers,
{},
{
cliDefaults: {
userAgent: DEFAULT_OPENCODE_USER_AGENT,
client: "desktop",
project: "global",
},
sessionBody: CHAT_BODY(),
}
);
assert.equal(headers["User-Agent"], DEFAULT_OPENCODE_USER_AGENT);
assertDescendingSession(headers["x-opencode-session"]);
assert.match(headers["x-opencode-request"] ?? "", /^msg_[0-9a-f]{12}[0-9A-Za-z]{14}$/);
});
test("the same conversation keeps the same session id, a different one does not", () => {
const sessionFor = (body: Record<string, unknown>) => {
const headers: Record<string, string> = {};
forwardOpencodeClientHeaders(
headers,
{},
{
cliDefaults: {
userAgent: DEFAULT_OPENCODE_USER_AGENT,
client: "desktop",
project: "global",
},
sessionBody: body,
}
);
return headers["x-opencode-session"];
};
const first = sessionFor(CHAT_BODY());
assert.equal(sessionFor(CHAT_BODY()), first, "conversation-stable, so upstream caching hits");
assert.notEqual(
sessionFor({ ...CHAT_BODY(), messages: [{ role: "user", content: "other" }] }),
first
);
});
test("a genuine descending client session (counter in window) is preserved", () => {
// A real client id mints `ses_` + ~(ts<<12|counter) hex + 14 base62, so the time part
// lands in the 0xFC0–0xFFF window (this one decodes to counter 1 → `ffe`).
const canonical = "ses_ecc5beb7cffe2U0aluUnb5nnpZ";
const headers: Record<string, string> = {};
forwardOpencodeClientHeaders(
headers,
{ "x-opencode-session": canonical },
{
cliDefaults: {
userAgent: DEFAULT_OPENCODE_USER_AGENT,
client: "desktop",
project: "global",
},
reencodeSession: true,
}
);
assert.equal(headers["x-opencode-session"], canonical);
});
test("a shape-valid session with an out-of-window counter is re-minted, not passed through", () => {
// Right shape (12 hex + 14 base62) but the time part `0123456789ab` does not decode to
// the descending counter window, so the upstream would 403 it. Value-level re-encode.
const foreign = "ses_0123456789abABCDEFGHIJKLMN";
const headers: Record<string, string> = {};
forwardOpencodeClientHeaders(
headers,
{ "x-opencode-session": foreign },
{
cliDefaults: {
userAgent: DEFAULT_OPENCODE_USER_AGENT,
client: "desktop",
project: "global",
},
reencodeSession: true,
}
);
assert.notEqual(headers["x-opencode-session"], foreign);
assertDescendingSession(headers["x-opencode-session"]);
});
test("an ungated surface (reencodeSession off) keeps the client's session unchanged", () => {
// opencode-go does not enforce the zen counter window, so the session round-trips as-is
// (#15311) — only the gated free-tier path validates and re-mints the value.
const session = "ses_00000000000000000000000000";
const headers: Record<string, string> = {};
forwardOpencodeClientHeaders(
headers,
{ "x-opencode-session": session },
{
cliDefaults: {
userAgent: DEFAULT_OPENCODE_USER_AGENT,
client: "desktop",
project: "global",
},
}
);
assert.equal(headers["x-opencode-session"], session);
});
test("a foreign client session is translated into the canonical shape, deterministically", () => {
const translate = () => {
const headers: Record<string, string> = {};
forwardOpencodeClientHeaders(
headers,
{ "x-opencode-session": "conv-42" },
{
cliDefaults: {
userAgent: DEFAULT_OPENCODE_USER_AGENT,
client: "desktop",
project: "global",
},
}
);
return headers["x-opencode-session"];
};
const translated = translate();
assertDescendingSession(translated);
assert.equal(translate(), translated, "same client session, same upstream session");
});
test("buildHeaders: a free-tier request accepts an event stream even when the client wants JSON", () => {
const executor = new OpencodeExecutor("opencode-zen");
const headers = executor.buildHeaders(null, false, null, "nemotron-3.5-lightning-free");
assert.equal(headers["Accept"], "text/event-stream");
assert.equal(headers["User-Agent"], DEFAULT_OPENCODE_USER_AGENT);
assertDescendingSession(headers["x-opencode-session"]);
});
test("buildHeaders: a paid model keeps the client's non-streaming expectation", () => {
const executor = new OpencodeExecutor("opencode-zen");
const headers = executor.buildHeaders(null, false, null, "gpt-5.6-luna");
assert.equal(headers["Accept"], undefined);
});
test("transformRequest: the contract is applied for a free model and skipped for a paid one", () => {
const executor = new OpencodeExecutor("opencode-zen");
const free = executor.transformRequest(
"nemotron-3.5-lightning-free",
CHAT_BODY(),
false,
null as never
) as Record<string, unknown>;
assert.equal(free.stream, true);
assert.equal((free.tools as unknown[]).length, 1);
const paid = executor.transformRequest(
"gpt-5.6-luna",
{ model: "gpt-5.6-luna", messages: [{ role: "user", content: "hi" }] },
false,
null as never
) as Record<string, unknown>;
assert.equal("tools" in paid, false);
assert.equal(paid.stream, undefined);
});
test("a JSON caller gets a JSON body back even though the upstream request was streamed", async () => {
// The contract forces streaming, so the executor owes every caller that asked for JSON a
// JSON body — handleChatCore can buffer an event stream, but the other consumers
// (compression judge, token counting) call execute() and read response.json() directly.
const executor = new OpencodeExecutor("opencode-zen");
const originalFetch = globalThis.fetch;
const seen: Array<Record<string, unknown>> = [];
globalThis.fetch = (async (_input: RequestInfo | URL, init?: RequestInit) => {
seen.push(JSON.parse(String(init?.body ?? "{}")));
const sse =
'data: {"id":"gen-1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"hi"},"finish_reason":null}]}\n\n' +
'data: {"id":"gen-1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}\n\n' +
"data: [DONE]\n\n";
return new Response(sse, {
status: 200,
headers: { "Content-Type": "text/event-stream" },
});
}) as typeof globalThis.fetch;
try {
const result = (await executor.execute({
model: "nemotron-3.5-lightning-free",
body: { model: "nemotron-3.5-lightning-free", messages: [{ role: "user", content: "hi" }] },
stream: false,
signal: null,
credentials: { apiKey: "k", accessToken: null, connectionId: "c" },
log: { debug() {}, info() {}, warn() {}, error() {} },
})) as { response: Response };
assert.equal(seen[0]?.stream, true, "the upstream request was streamed");
assert.equal((seen[0]?.tools as unknown[]).length, 1, "and carried the placeholder tool");
assert.match(result.response.headers.get("content-type") ?? "", /application\/json/);
const json = (await result.response.json()) as {
choices?: Array<{ message?: { content?: string } }>;
};
assert.equal(json.choices?.[0]?.message?.content, "hi");
} finally {
globalThis.fetch = originalFetch;
}
});
test("a streaming caller still receives the event stream untouched", async () => {
const executor = new OpencodeExecutor("opencode-zen");
const originalFetch = globalThis.fetch;
globalThis.fetch = (async () =>
new Response('data: {"choices":[{"delta":{"content":"hi"}}]}\n\n', {
status: 200,
headers: { "Content-Type": "text/event-stream" },
})) as typeof globalThis.fetch;
try {
const result = (await executor.execute({
model: "nemotron-3.5-lightning-free",
body: {
model: "nemotron-3.5-lightning-free",
messages: [{ role: "user", content: "hi" }],
stream: true,
},
stream: true,
signal: null,
credentials: { apiKey: "k", accessToken: null, connectionId: "c" },
log: { debug() {}, info() {}, warn() {}, error() {} },
})) as { response: Response };
assert.match(result.response.headers.get("content-type") ?? "", /text\/event-stream/);
await result.response.body?.cancel();
} finally {
globalThis.fetch = originalFetch;
}
});
test("a gated request repairs a stale configured user-agent, a non-gated one keeps it", () => {
// An operator still carrying the previous default in OPENCODE_USER_AGENT would otherwise
// keep sending `opencode`, which the free tier refuses. Outside the gate the configured
// value is still honoured verbatim (#5997).
const saved = process.env.OPENCODE_USER_AGENT;
process.env.OPENCODE_USER_AGENT = "opencode";
try {
const executor = new OpencodeExecutor("opencode-zen");
const gated = executor.buildHeaders(null, true, null, "nemotron-3.5-lightning-free");
assert.equal(gated["User-Agent"], DEFAULT_OPENCODE_USER_AGENT);
assert.ok(satisfiesOpencodeUserAgentContract(gated["User-Agent"]));
const paid = executor.buildHeaders(null, true, null, "gpt-5.6-luna");
assert.equal(paid["User-Agent"], "opencode");
} finally {
if (saved === undefined) delete process.env.OPENCODE_USER_AGENT;
else process.env.OPENCODE_USER_AGENT = saved;
}
});
test("responses: two conversations on the same model get different session ids", () => {
const executor = new OpencodeExecutor("opencode-zen");
executor._requestFormat = "openai-responses";
const sessionFor = (text: string) =>
executor.buildHeaders(null, true, null, "muse-spark-1.3-contributor-free", undefined, {
model: "muse-spark-1.3-contributor-free",
input: [{ role: "user", content: text }],
})["x-opencode-session"];
const first = sessionFor("first conversation");
assertDescendingSession(first);
assert.equal(sessionFor("first conversation"), first, "same conversation, same session");
assert.notEqual(
sessionFor("a completely different opening message"),
first,
"the Responses surface carries the conversation under input, not messages"
);
});
// ── The placeholder is resolved from what the upstream is currently accepting ──────────
test("the opt-out switches the body half off and leaves the scope predicate alone", () => {
const previous = process.env.OPENCODE_FREE_TIER_REQUEST_CONTRACT;
try {
process.env.OPENCODE_FREE_TIER_REQUEST_CONTRACT = "off";
assert.equal(
requiresFreeTierRequestContract("zen", "opencode", "nemotron-3.5-lightning-free"),
false
);
assert.equal(isGatedFreeTierRequest("zen", "opencode", "nemotron-3.5-lightning-free"), true);
const { body, attempt } = prepareFreeTierRequest(
CHAT_BODY(),
"openai",
"zen",
"opencode",
"nemotron-3.5-lightning-free"
);
assert.equal(attempt, null);
assert.equal("tools" in (body as Record<string, unknown>), false);
assert.equal("stream" in (body as Record<string, unknown>), false);
} finally {
if (previous === undefined) delete process.env.OPENCODE_FREE_TIER_REQUEST_CONTRACT;
else process.env.OPENCODE_FREE_TIER_REQUEST_CONTRACT = previous;
}
});
test("configured placeholder names are parsed, bad entries dropped, unset stays empty", () => {
const previous = process.env.OPENCODE_FREE_TIER_PLACEHOLDER_TOOLS;
try {
delete process.env.OPENCODE_FREE_TIER_PLACEHOLDER_TOOLS;
assert.deepEqual(configuredPlaceholderToolNames(), []);
process.env.OPENCODE_FREE_TIER_PLACEHOLDER_TOOLS = " glob , grep ,,9bad, glob ,ok-name";
assert.deepEqual(configuredPlaceholderToolNames(), ["glob", "grep", "ok-name"]);
} finally {
if (previous === undefined) delete process.env.OPENCODE_FREE_TIER_PLACEHOLDER_TOOLS;
else process.env.OPENCODE_FREE_TIER_PLACEHOLDER_TOOLS = previous;
}
});
test("with nothing observed and nothing configured, the built-in placeholder is used", () => {
_resetToolObservationForTests();
const { body, attempt } = prepareFreeTierRequest(
CHAT_BODY(),
"openai",
"zen",
"opencode",
"nemotron-3.5-lightning-free"
);
const tools = (body as Record<string, unknown>).tools as Array<{ function: { name: string } }>;
assert.deepEqual(
tools.map((t) => t.function.name),
[DEFAULT_PLACEHOLDER_TOOL_NAME]
);
// Nothing was borrowed, so a refusal here must not be charged against the store.
assert.equal(attempt?.borrowed, false);
});
test("an accepted request teaches the names it carried, and a later bare request borrows them", () => {
_resetToolObservationForTests();
const withTools = {
...CHAT_BODY(),
tools: [
{ type: "function", function: { name: "glob" } },
{ type: "function", function: { name: "grep" } },
],
};
const first = prepareFreeTierRequest(
withTools,
"openai",
"zen",
"opencode",
"nemotron-3.5-lightning-free"
);
assert.deepEqual(first.attempt?.clientToolNames, ["glob", "grep"]);
noteFreeTierOutcome(first.attempt, true);
assert.deepEqual(getObservedToolNames("opencode", "nemotron-3.5-lightning-free"), [
"glob",
"grep",
]);
const second = prepareFreeTierRequest(
CHAT_BODY(),
"openai",
"zen",
"opencode",
"nemotron-3.5-lightning-free"
);
const tools = (second.body as Record<string, unknown>).tools as Array<{
function: { name: string };
}>;
assert.deepEqual(
tools.map((t) => t.function.name),
["glob", "grep"]
);
assert.equal(second.attempt?.borrowed, true);
});
test("configured placeholder names take precedence over un-scoped observed tools for generic clients", () => {
_resetToolObservationForTests();
recordAcceptedToolNames("opencode", "big-pickle", undefined, ["run_code"]);
const resolved = resolvePlaceholderNames("opencode", "big-pickle", undefined, ["glob", "grep"]);
assert.deepEqual(resolved, ["glob", "grep"]);
});
test("what one model learns stays with that model", () => {
// Asserts an absence, so it stays green if the store is removed entirely — it guards
// against cross-model leakage, not against the mechanism disappearing.
_resetToolObservationForTests();
const learned = prepareFreeTierRequest(
{ ...CHAT_BODY(), tools: [{ type: "function", function: { name: "glob" } }] },
"openai",
"zen",
"opencode",
"nemotron-3.5-lightning-free"
);
noteFreeTierOutcome(learned.attempt, true);
assert.equal(getObservedToolNames("opencode", "big-pickle"), null);
assert.equal(getObservedToolNames("opencode-zen", "nemotron-3.5-lightning-free"), null);
});
test("a borrowed set is dropped after three refusals in a row, not after one", () => {
_resetToolObservationForTests();
const learned = prepareFreeTierRequest(
{ ...CHAT_BODY(), tools: [{ type: "function", function: { name: "glob" } }] },
"openai",
"zen",
"opencode",
"nemotron-3.5-lightning-free"
);
noteFreeTierOutcome(learned.attempt, true);
const borrow = () =>
prepareFreeTierRequest(CHAT_BODY(), "openai", "zen", "opencode", "nemotron-3.5-lightning-free")
.attempt;
// One refusal is not proof: the same body was refused and then accepted minutes apart on
// a free model (measured 2026-09-18), so a single verdict must not clear the entry.
// Only a refusal that says something about the tools counts: a bare verdict or a
// 429 leaves the entry alone.
const refused = () =>
noteFreeTierOutcome(borrow(), { ok: false, status: 403, bodyText: REFUSAL_BODY });
refused();
assert.deepEqual(getObservedToolNames("opencode", "nemotron-3.5-lightning-free"), ["glob"]);
refused();
assert.deepEqual(getObservedToolNames("opencode", "nemotron-3.5-lightning-free"), ["glob"]);
refused();
assert.equal(getObservedToolNames("opencode", "nemotron-3.5-lightning-free"), null);
});
test("an acceptance resets the refusal streak", () => {
_resetToolObservationForTests();
const withTools = {
...CHAT_BODY(),
tools: [{ type: "function", function: { name: "glob" } }],
};
const learned = prepareFreeTierRequest(
withTools,
"openai",
"zen",
"opencode",
"nemotron-3.5-lightning-free"
);
noteFreeTierOutcome(learned.attempt, true);
const borrow = () =>
prepareFreeTierRequest(CHAT_BODY(), "openai", "zen", "opencode", "nemotron-3.5-lightning-free")
.attempt;
const refused = () =>
noteFreeTierOutcome(borrow(), { ok: false, status: 403, bodyText: REFUSAL_BODY });
refused();
refused();
noteFreeTierOutcome(
prepareFreeTierRequest(withTools, "openai", "zen", "opencode", "nemotron-3.5-lightning-free")
.attempt,
true
);
noteFreeTierOutcome(borrow(), { ok: false, status: 403, bodyText: REFUSAL_BODY });
assert.deepEqual(getObservedToolNames("opencode", "nemotron-3.5-lightning-free"), ["glob"]);
});
test("a refusal on the caller's own tools never touches the store", () => {
_resetToolObservationForTests();
const withTools = {
...CHAT_BODY(),
tools: [{ type: "function", function: { name: "glob" } }],
};
noteFreeTierOutcome(
prepareFreeTierRequest(withTools, "openai", "zen", "opencode", "nemotron-3.5-lightning-free")
.attempt,
true
);
for (let i = 0; i < 5; i++) {
const own = prepareFreeTierRequest(
withTools,
"openai",
"zen",
"opencode",
"nemotron-3.5-lightning-free"
);
assert.equal(own.attempt?.borrowed, false);
noteFreeTierOutcome(own.attempt, false);
}
assert.deepEqual(getObservedToolNames("opencode", "nemotron-3.5-lightning-free"), ["glob"]);
});
test("the other surface is left alone entirely", () => {
// Scope guard only. That `/zen/go/v1` refuses a request carrying tools comes from
// upstream anomalyco/opencode#44300 and #44382, not from a measurement here: this
// installation exposes no model on that surface.
_resetToolObservationForTests();
const { body, attempt } = prepareFreeTierRequest(
CHAT_BODY(),
"openai",
"go",
"opencode-go",
"ox-alpha-free"
);
assert.equal(attempt, null);
assert.equal("tools" in (body as Record<string, unknown>), false);
assert.equal("stream" in (body as Record<string, unknown>), false);
});
// ── A conversation repairs its own service requests ───────────────────────────────────
const SES_A = "ses_0123456789abABCDEFGHIJKLMN";
const SES_B = "ses_fedcba987654ZYXWVUTSRQPONM";
test("a session's service request borrows the list its own build request declared", () => {
_resetToolObservationForTests();
// The official client sends its build requests with a full tool list and its title and
// compaction requests with none, on the same session (upstream
// anomalyco/opencode#49433). The second gets back what the first declared.
const build = prepareFreeTierRequest(
{
...CHAT_BODY(),
tools: [
{ type: "function", function: { name: "glob" } },
{ type: "function", function: { name: "grep" } },
],
},
"openai",
"zen",
"opencode",
"nemotron-3.5-lightning-free",
SES_A
);
noteFreeTierOutcome(build.attempt, true);
const title = prepareFreeTierRequest(
CHAT_BODY(),
"openai",
"zen",
"opencode",
"nemotron-3.5-lightning-free",
SES_A
);
const tools = (title.body as Record<string, unknown>).tools as Array<{
function: { name: string };
}>;
assert.deepEqual(
tools.map((t) => t.function.name),
["glob", "grep"]
);
assert.equal(title.attempt?.borrowed, true);
});
test("a session's own list wins over the shared one", () => {
_resetToolObservationForTests();
// Order matters: the session entry is recorded FIRST and the shared entry overwritten
// afterwards by another conversation, so a store keyed by model alone would answer
// "shared" here and this case would fail.
const own = prepareFreeTierRequest(
{ ...CHAT_BODY(), tools: [{ type: "function", function: { name: "own" } }] },
"openai",
"zen",
"opencode",
"nemotron-3.5-lightning-free",
SES_A
);
noteFreeTierOutcome(own.attempt, true);
const shared = prepareFreeTierRequest(
{ ...CHAT_BODY(), tools: [{ type: "function", function: { name: "shared" } }] },
"openai",
"zen",
"opencode",
"nemotron-3.5-lightning-free",
SES_B
);
noteFreeTierOutcome(shared.attempt, true);
const borrowed = prepareFreeTierRequest(
CHAT_BODY(),
"openai",
"zen",
"opencode",
"nemotron-3.5-lightning-free",
SES_A
);
const tools = (borrowed.body as Record<string, unknown>).tools as Array<{
function: { name: string };
}>;
assert.deepEqual(
tools.map((t) => t.function.name),
["own"]
);
});
test("a session that has declared nothing yet falls back to the shared entry", () => {
_resetToolObservationForTests();
noteFreeTierOutcome(
prepareFreeTierRequest(
{ ...CHAT_BODY(), tools: [{ type: "function", function: { name: "shared" } }] },
"openai",
"zen",
"opencode",
"nemotron-3.5-lightning-free",
SES_A
).attempt,
true
);
const fresh = prepareFreeTierRequest(
CHAT_BODY(),
"openai",
"zen",
"opencode",
"nemotron-3.5-lightning-free",
SES_B
);
const tools = (fresh.body as Record<string, unknown>).tools as Array<{
function: { name: string };
}>;
assert.deepEqual(
tools.map((t) => t.function.name),
["shared"]
);
});
test("a client session id is read case-insensitively, a synthesized one is not borrowed from", () => {
assert.equal(clientSuppliedOpencodeSession({ "X-OpenCode-Session": SES_A }), SES_A);
assert.equal(clientSuppliedOpencodeSession({ "x-session-id": SES_B }), SES_B);
assert.equal(clientSuppliedOpencodeSession({ "x-opencode-session": " " }), undefined);
assert.equal(clientSuppliedOpencodeSession({}), undefined);
assert.equal(clientSuppliedOpencodeSession(undefined), undefined);
});
test("mergeClientToolsWithObserved: keeps client tools first and appends missing observed names with empty schemas [free-tier-observed-tools]", () => {
_resetToolObservationForTests();
const body = {
...CHAT_BODY(),
tools: [
{ type: "function", function: { name: "glob", parameters: { type: "object" } } },
{ type: "function", function: { name: "read", parameters: { type: "object" } } },
],
};
const merged = mergeClientToolsWithObserved(body, "openai", "opencode", "big-pickle", undefined, [
"read",
"edit",
]);
const tools = (merged as Record<string, unknown>).tools as Array<{
function: { name: string; parameters: object };
}>;
assert.deepEqual(
tools.map((t) => t.function.name),
["glob", "read", "edit"]
);
// Appended entries are list entries, not callable tools; `edit` is outside the quartet,
// so it keeps the empty schema.
assert.deepEqual(tools[2].function.parameters, { type: "object", properties: {} });
});
test("mergeClientToolsWithObserved: an appended quartet member carries a non-empty schema [free-tier-observed-tools]", () => {
_resetToolObservationForTests();
const body = {
...CHAT_BODY(),
tools: [{ type: "function", function: { name: "Read", parameters: { type: "object" } } }],
};
const merged = mergeClientToolsWithObserved(body, "openai", "opencode", "big-pickle", undefined, [
"bash",
]);
const tools = (merged as Record<string, unknown>).tools as Array<{
function: { name: string; parameters: object };
}>;
assert.deepEqual(
tools.map((t) => t.function.name),
["Read", "bash"]
);
assert.deepEqual(tools[1].function.parameters, {
type: "object",
properties: { command: { type: "string" } },
required: ["command"],
});
});
test("mergeClientToolsWithObserved: leaves the body untouched when nothing observed [free-tier-observed-tools]", () => {
_resetToolObservationForTests();
const body = {
...CHAT_BODY(),
tools: [{ type: "function", function: { name: "glob", parameters: { type: "object" } } }],
};
assert.equal(
mergeClientToolsWithObserved(body, "openai", "opencode", "big-pickle", undefined, []),
body
);
});
// ── Only a refusal that says something about the tools counts ──────────────────
const REFUSAL_BODY = JSON.stringify({
error: {
type: "FreeTierError",
message:
"Error from provider (Console): OpenCode's free tier can only be used from within OpenCode",
},
});
function learnBorrowedNames(): void {
_resetToolObservationForTests();
const learned = prepareFreeTierRequest(
{ ...CHAT_BODY(), tools: [{ type: "function", function: { name: "glob" } }] },
"openai",
"zen",
"opencode",
"nemotron-3.5-lightning-free"
);
noteFreeTierOutcome(learned.attempt, true);
}
function borrowedAttempt() {
return prepareFreeTierRequest(
CHAT_BODY(),
"openai",
"zen",
"opencode",
"nemotron-3.5-lightning-free"
).attempt;
}
test("three 429 answers on a borrowed request keep the observed names", () => {
learnBorrowedNames();
for (let i = 0; i < 3; i++) {
noteFreeTierOutcome(borrowedAttempt(), {
ok: false,
status: 429,
bodyText: "Too many requests",
});
}
assert.deepEqual(getObservedToolNames("opencode", "nemotron-3.5-lightning-free"), ["glob"]);
});
test("three 503 answers on a borrowed request keep the observed names", () => {
learnBorrowedNames();
for (let i = 0; i < 3; i++) {
noteFreeTierOutcome(borrowedAttempt(), {
ok: false,
status: 503,
bodyText: "Service unavailable",
});
}
assert.deepEqual(getObservedToolNames("opencode", "nemotron-3.5-lightning-free"), ["glob"]);
});
test("three 403 answers carrying the refusal keep dropping the observed names", () => {
learnBorrowedNames();
const refused = () =>
noteFreeTierOutcome(borrowedAttempt(), { ok: false, status: 403, bodyText: REFUSAL_BODY });
refused();
assert.deepEqual(getObservedToolNames("opencode", "nemotron-3.5-lightning-free"), ["glob"]);
refused();
assert.deepEqual(getObservedToolNames("opencode", "nemotron-3.5-lightning-free"), ["glob"]);
refused();
assert.equal(getObservedToolNames("opencode", "nemotron-3.5-lightning-free"), null);
});
test("a 200 on a borrowed shape clears the streak without rewriting the entry", () => {
learnBorrowedNames();
const refused = () =>
noteFreeTierOutcome(borrowedAttempt(), { ok: false, status: 403, bodyText: REFUSAL_BODY });
refused();
refused();
noteFreeTierOutcome(borrowedAttempt(), { ok: true, status: 200, bodyText: null });
noteFreeTierOutcome(borrowedAttempt(), { ok: false, status: 403, bodyText: REFUSAL_BODY });
assert.deepEqual(getObservedToolNames("opencode", "nemotron-3.5-lightning-free"), ["glob"]);
});
test("refusals that say nothing about the tools never touch the observed names", () => {
learnBorrowedNames();
const bodies = [
JSON.stringify({ error: { type: "FreeTierError", message: "not available in your country" } }),
JSON.stringify({
error: { type: "FreeTierError", message: "[user_blocked] egress refused" },
}),
JSON.stringify({ error_code: 1010, error: { type: "FreeTierError" } }),
];
for (const bodyText of bodies) {
for (let i = 0; i < 3; i++) {
noteFreeTierOutcome(borrowedAttempt(), { ok: false, status: 403, bodyText });
}
}
assert.deepEqual(getObservedToolNames("opencode", "nemotron-3.5-lightning-free"), ["glob"]);
});
test("a deferred note without a verdict never touches the observed names", () => {
learnBorrowedNames();
for (let i = 0; i < 3; i++) {
noteFreeTierOutcome(borrowedAttempt(), false);
}
assert.deepEqual(getObservedToolNames("opencode", "nemotron-3.5-lightning-free"), ["glob"]);
});
test("buildHeaders re-mints a shape-valid foreign session on a gated free model", () => {
const foreign = "ses_0123456789abABCDEFGHIJKLMN";
const headers = new OpencodeExecutor("opencode-zen").buildHeaders(
null,
true,
{ "x-opencode-session": foreign },
"nemotron-3.5-lightning-free"
);
assert.notEqual(headers["x-opencode-session"], foreign);
assertDescendingSession(headers["x-opencode-session"]);
});
test("buildHeaders leaves an opencode-go session unchanged", () => {
const session = "ses_0123456789abABCDEFGHIJKLMN";
const headers = new OpencodeExecutor("opencode-go").buildHeaders(
null,
true,
{ "x-opencode-session": session },
"glm-5.2"
);
assert.equal(headers["x-opencode-session"], session);
});
test("an opencode-go synced catalog row is not in the free set", async () => {
// SQLITE_FILE is fixed when the db module loads, so this uses that test database
// and removes the rows afterwards. A later case must not inherit the synced set.
const core = await import("../../src/lib/db/core.ts");
const { saveModelsDevPricing, clearModelsDevPricing } =
await import("../../src/lib/modelsDevSync.ts");
const db = core.getDbInstance();
const insert = db.prepare(
"INSERT INTO key_value (namespace, key, value) VALUES ('syncedAvailableModels', ?, ?)"
);
const remove = db.prepare(
"DELETE FROM key_value WHERE namespace = 'syncedAvailableModels' AND key IN (?, ?, ?)"
);
try {
saveModelsDevPricing({
opencode: {
"zen-free": { input: 0, output: 0 },
"pickle-zen": { input: 0, output: 0 },
"big-pickle": { input: 0, output: 0 },
},
});
insert.run("opencode:conn", JSON.stringify([{ id: "zen-free" }]));
insert.run("opencode-zen:conn", JSON.stringify([{ id: "pickle-zen" }]));
insert.run("opencode-go:conn", JSON.stringify([{ id: "big-pickle" }]));
_setOpencodeFreeModelsForTests(null);
assert.equal(isPremiumOpencodeModel("zen-free", "opencode"), false);
assert.equal(isPremiumOpencodeModel("pickle-zen", "opencode-zen"), false);
assert.equal(isPremiumOpencodeModel("big-pickle", "opencode"), true);
} finally {
remove.run("opencode:conn", "opencode-zen:conn", "opencode-go:conn");
clearModelsDevPricing();
_setOpencodeFreeModelsForTests(null);
}
});
test("a deferred 403 verdict still counts against the borrowed names", () => {
learnBorrowedNames();
const first = borrowedAttempt();
assert.equal(first?.borrowed, true);
for (let i = 0; i < 3; i++) {
const attempt = borrowedAttempt();
noteFreeTierOutcome({ ...(attempt as object), probe: false } as typeof attempt, {
ok: false,
status: 403,
bodyText: REFUSAL_BODY,
});
}
assert.equal(getObservedToolNames("opencode", "nemotron-3.5-lightning-free"), null);
});