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
/**
* Which tool shape a gated request must carry, learned from the upstream's refusals.
*
* The upstream accepts a request whose instructions say "Never use tools" only with no tools,
* and any other request only with tools (measured 2026-09-18, both surfaces). The request
* contract used to fill an empty `tools` array unconditionally, so the first kind was refused.
* Rather than match a prompt, the executor replays a refused request once in the other shape
* and remembers which one worked (see `withRequestShapeRetry`).
*
* State lives here, keyed by the identity of the request body the executor was handed
* (`WeakMap`), never on the executor: it is a shared instance and requests overlap.
*/
import { createHash } from "node:crypto";
import { isOpencodeFreeTierRefusal, isOpencodeQuotaShapeRefusal } from "./opencodeGeoBlock.ts";
import type { ExecuteInput, ExecutorExecuteResult } from "./base.ts";
import type { FreeTierOutcome } from "./opencodeFreeTierContract.ts";
export type RequestShape = "tools" | "bare";
/** What `prepareFreeTierRequest` decided for one request, kept until its outcome is known. */
export interface InjectionContext {
readonly shape: RequestShape;
/** The prompt class this request belongs to (see `shapeKeyOf`). */
readonly key: string;
/** False when a refusal is final for this request: its outcome is noted as it happens. */
readonly probe: boolean;
/**
* Replays the outcome note that was deferred while a replay was still possible. The
* verdict travels with the note, so a refusal that says something about the borrowed
* tools still counts once no replay can rescue it.
*/
readonly replayNote: (verdict: FreeTierOutcome) => void;
}
/** Prompt classes that the upstream accepts bare. Bounded; least recently confirmed goes first. */
const MAX_CLASSES = 64;
const bareClasses = new Set<string>();
/** Both shapes were refused: no replay for this class until the stamp passes. */
const PAUSE_MS = 60_000;
const pausedUntil = new Map<string, number>();
let now: () => number = () => Date.now();
const forced = new WeakMap<object, RequestShape>();
const contexts = new WeakMap<object, InjectionContext>();
/** What the contract decided for a request, kept until the request is over (see `forget`). */
const attempts = new WeakMap<object, object>();
const isObject = (value: unknown): value is object => typeof value === "object" && value !== null;
function textOf(content: unknown): string {
if (typeof content === "string") return content;
if (content === null || content === undefined) return "";
if (Array.isArray(content)) {
const text = content
.map((part) => (part as { text?: unknown } | null)?.text)
.filter((t): t is string => typeof t === "string")
.join("");
if (text) return text;
}
// Not plain text: hash its structure, so it is a class of its own rather than "no prompt".
try {
return JSON.stringify(content);
} catch {
return String(content);
}
}
/**
* The class a request belongs to: provider, model and a digest of its prompt.
*
* Responses bodies carry the prompt as `instructions`, Chat Completions bodies as the first
* system or developer message. A request with no prompt hashes the empty string: it is a class
* like any other, so a remembered shape and the replay bookkeeping apply to it too.
*/
export function shapeKeyOf(provider: string, model: string, body: unknown): string {
const record = isObject(body) ? (body as Record<string, unknown>) : {};
let prompt = typeof record.instructions === "string" ? record.instructions : "";
if (!prompt && Array.isArray(record.messages)) {
const first = (record.messages as Array<Record<string, unknown>>).find(
(m) => m && (m.role === "system" || m.role === "developer")
);
prompt = textOf(first?.content);
}
const digest = createHash("sha1").update(prompt).digest("hex");
return `${provider}|${model}|${digest}`;
}
/** Which shape this request goes out in, and whether a refusal may still be replayed. */
export function planShape(origin: object, key: string): { shape: RequestShape; probe: boolean } {
const imposed = forced.get(origin);
if (imposed) return { shape: imposed, probe: false };
return { shape: bareClasses.has(key) ? "bare" : "tools", probe: !isPaused(key) };
}
function isPaused(key: string): boolean {
const until = pausedUntil.get(key);
if (until === undefined) return false;
if (until > now()) return true;
pausedUntil.delete(key);
return false;
}
function pause(key: string): void {
pausedUntil.delete(key);
pausedUntil.set(key, now() + PAUSE_MS);
while (pausedUntil.size > MAX_CLASSES) {
const oldest = pausedUntil.keys().next();
if (oldest.done) break;
pausedUntil.delete(oldest.value);
}
}
function rememberBare(key: string): void {
bareClasses.delete(key);
bareClasses.add(key);
while (bareClasses.size > MAX_CLASSES) {
const oldest = bareClasses.values().next();
if (oldest.done) break;
bareClasses.delete(oldest.value);
}
}
export function rememberAttempt(origin: object, attempt: object): void {
attempts.set(origin, attempt);
}
export function recallAttempt<T extends object>(origin: unknown): T | null {
return isObject(origin) ? ((attempts.get(origin) as T | undefined) ?? null) : null;
}
export function forgetAttempt(origin: object): void {
attempts.delete(origin);
}
export function recordInjection(origin: object, ctx: InjectionContext): void {
contexts.set(origin, ctx);
}
function responseOf(result: ExecutorExecuteResult): Response | null {
if (result instanceof Response) return result;
return result && "response" in result && result.response ? result.response : null;
}
async function readVerdict(response: Response, log: ExecuteInput["log"]): Promise<FreeTierOutcome> {
const status = response.status;
if (status !== 403 && status !== 451) return { ok: false, status, bodyText: null };
try {
return { ok: false, status, bodyText: await response.clone().text() };
} catch {
// Unreadable body: treated as "not a shape refusal", so the response is returned as-is.
log?.debug?.("OPENCODE", "refusal body unreadable, no replay");
return { ok: false, status, bodyText: null };
}
}
async function isShapeRefusal(verdict: FreeTierOutcome): Promise<boolean> {
if (verdict.status !== 403 && verdict.status !== 451) return false;
if (verdict.bodyText === null) return false;
return (
isOpencodeFreeTierRefusal(verdict.status, verdict.bodyText) ||
isOpencodeQuotaShapeRefusal(verdict.status, verdict.bodyText)
);
}
/**
* Run one execution and, when the upstream refuses a request whose tool shape we chose,
* replay it once in the other shape.
*
* Only a refusal of the request itself counts: a 429, a 5xx or a network error says nothing about the
* shape. A request whose tools the client declared is never touched (no context recorded).
*/
/** What a replay taught: the shape that worked is remembered, two refusals pause the class. */
function learnFromReplay(ctx: InjectionContext, accepted: boolean, verdict: FreeTierOutcome): void {
if (!accepted) {
pause(ctx.key);
ctx.replayNote(verdict);
} else if (ctx.shape === "tools") {
rememberBare(ctx.key);
} else {
bareClasses.delete(ctx.key);
}
}
/** Release the refused response, send the request again in the other shape, learn from it. */
async function replayInOtherShape(
input: ExecuteInput,
run: (i: ExecuteInput) => Promise<ExecutorExecuteResult>,
ctx: InjectionContext,
refused: Response,
origin: object,
verdict: FreeTierOutcome
): Promise<ExecutorExecuteResult> {
await refused.body?.cancel().catch(() => undefined);
forced.set(origin, ctx.shape === "bare" ? "tools" : "bare");
let second: ExecutorExecuteResult;
try {
second = await run(input);
} catch (error) {
ctx.replayNote(verdict);
throw error;
}
learnFromReplay(ctx, responseOf(second)?.ok === true, verdict);
return second;
}
function forget(origin: unknown): void {
if (!isObject(origin)) return;
forced.delete(origin);
contexts.delete(origin);
attempts.delete(origin);
}
export async function withRequestShapeRetry(
input: ExecuteInput,
run: (i: ExecuteInput) => Promise<ExecutorExecuteResult>
): Promise<ExecutorExecuteResult> {
const origin = input.body;
try {
const first = await run(input);
const ctx = isObject(origin) ? contexts.get(origin) : undefined;
const response = responseOf(first);
if (!ctx || !isObject(origin) || !response || response.ok || !ctx.probe) return first;
const verdict = await readVerdict(response, input.log);
if (input.signal?.aborted || !(await isShapeRefusal(verdict))) {
ctx.replayNote(verdict);
return first;
}
return await replayInOtherShape(input, run, ctx, response, origin, verdict);
} finally {
forget(origin);
}
}
export function _resetShapeMemoForTests(): void {
bareClasses.clear();
pausedUntil.clear();
}
export function _setShapeClockForTests(clock: () => number): void {
now = clock;
}