Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
fix(errors): name an unsupported model and a wrong-plan key in the hint
Jack Rudenkofa09cb7eb85b
diff --git a/packages/cli/src/handlers/composed-handler.ts b/packages/cli/src/handlers/composed-handler.tsindex 6211eb14..b1d5922a 100644--- a/packages/cli/src/handlers/composed-handler.ts+++ b/packages/cli/src/handlers/composed-handler.ts@@ -36,6 +36,7 @@ import { getBehaviorEngine } from "../behavior/index.js";import { getLogLevel, log, logStderr, logStructured, truncateContent } from "../logger.js";import { GeminiThoughtSignatureMiddleware, MiddlewareManager } from "../middleware/index.js";import { deepMergeParams } from "../model-params.js";+import { describeSiblingKeys, getProviderByName } from "../providers/provider-definitions.js";import { isTerminal429 } from "../providers/transport/openai.js";import {type OpenAIImageBlock,@@ -924,7 +925,13 @@ export class ComposedHandler implements ModelHandler {response.status,errorText,this.provider.displayName,- transportTerminal+ transportTerminal,+ // The INTERNAL name, beside the display name: the catalog is keyed by+ // it, and an auth failure on a vendor with sibling-tier keys needs+ // that lookup to say which other key exists. A transport whose name+ // is not a catalog entry (a custom endpoint) simply finds nothing and+ // gets today's sentence unchanged.+ this.provider.name);let parsedErrorBody: any;try {@@ -1726,12 +1733,21 @@ export class ComposedHandler implements ModelHandler {* heuristics below, which are pattern-matching prose and cannot tell a spent* plan from a per-minute throttle when the provider phrases both identically.* `undefined` — every transport without the hook — keeps the original behaviour.+ *+ * `providerUid` is the INTERNAL provider name (`ProviderTransport.name`, e.g.+ * `qwen-token-plan`), not the display name, because it is what the provider+ * catalog is keyed by. It is optional and every branch below is unchanged+ * without it: it only lets the auth branch look up whether this vendor ships a+ * SECOND, non-interchangeable key for another tier (`siblingKeyEnvVars`).+ * Nothing is inferred from the credential itself — see the branch for why the+ * key's own bytes are deliberately not read.*/export function getRecoveryHint(status: number,errorText: string,providerName: string,- transportTerminal429?: boolean+ transportTerminal429?: boolean,+ providerUid?: string): string {const lower = errorText.toLowerCase();@@ -1806,6 +1822,31 @@ export function getRecoveryHint(if (hasActionableLink(errorText)) {return "Provider rejected the request and gave a specific fix — follow the link in the message below.";}+ // Reached only when the credential really is the most likely cause. For a+ // vendor that sells the SAME models under several plans, "check your key"+ // is still not the whole story: the plans' keys are isolated and rejected+ // by each other's hosts with a near-identical 401, so "right key, wrong+ // silo" is at least as likely as "bad key". Measured 2026-09-17 with one+ // real Alibaba Token Plan key: 200 on `token-plan…`, 401 `invalid access+ // token or token expired` on `coding-intl…`, 401 `Incorrect API key+ // provided` on `dashscope-intl…`.+ //+ // Driven by `siblingKeyEnvVars`, so it is a property of any vendor that+ // declares one (`opencode-zen-go` does today) rather than an Alibaba+ // special case — and the variable names come from the catalog via+ // `describeSiblingKeys`, the same sentence `describeMissingCredential`+ // emits, so the two cannot drift into saying different things about one+ // pair of keys.+ //+ // What this deliberately does NOT do is look at the key. A Token Plan key+ // can match `sk-sp-`, which Alibaba's own Coding Plan docs call their+ // format, so a prefix hint would confidently mislabel a working+ // credential. The key's bytes are never read, which also keeps a failed+ // secret operation out of a status line.+ const siblingNote = providerUid ? describeSiblingKeys(getProviderByName(providerUid)) : "";+ if (siblingNote) {+ return `Check API key / OAuth credentials. This vendor sells several plans whose keys are isolated, so a 401 can also mean the right key on the wrong plan's host.${siblingNote}`;+ }return "Check API key / OAuth credentials.";}if (status === 404) {@@ -1831,6 +1872,19 @@ export function getRecoveryHint(if (isRequestShapeError(errorText)) {return "Wrong request shape for this endpoint — the provider named the parameter it rejected (see the message below). Nothing was too large; a shorter prompt will not help.";}+ // A model the provider does not carry also arrives as a 400 — Alibaba's+ // silos answer an id outside the plan with a bare `Model not exist`. Same+ // predicate the 401/403 branch above uses, for the same reason it exists:+ // one reading of "the MODEL is the problem", so the hint cannot say+ // something different depending on which status the provider chose.+ //+ // Placed AFTER `isRequestShapeError` (a provider that names a parameter has+ // stated the fact, and a heuristic must not talk over it) and BEFORE the+ // size test, which is a bare `includes("token")` and would otherwise claim+ // any model-unsupported body that happens to spell "tokens".+ if (hasModelUnsupportedWording(errorText)) {+ return "Model not supported by this provider. Verify model name.";+ }if (lower.includes("context") || lower.includes("too long") || lower.includes("token")) {return "Input too large. Reduce message history or use a larger-context model.";}diff --git a/packages/cli/src/handlers/shared/model-unsupported.blackbox.test.ts b/packages/cli/src/handlers/shared/model-unsupported.blackbox.test.tsnew file mode 100644index 00000000..22d95ca8--- /dev/null+++ b/packages/cli/src/handlers/shared/model-unsupported.blackbox.test.ts@@ -0,0 +1,49 @@+/**+ * BLACK-BOX. Written by `gpt-6-astra` from the spec and a body-stripped `.d.ts`,+ * with no access to this implementation. See+ * `ai-docs/reports/blackbox-tests-alibaba/blackbox-results.md`.+ *+ * DO NOT edit an assertion to make it pass. Its value is that its author had+ * never read the code; a repaired assertion is a regression test, not evidence.+ * Adaptation on integration: import path only.+ */+import { describe, expect, test } from "bun:test";+import { useBlackboxEnv } from "../../test-helpers/blackbox-env.js";+import { hasActionableLink, hasModelUnsupportedWording } from "./model-unsupported.js";++useBlackboxEnv();++describe("unsupported models and invalid keys require different remedies", () => {+ for (const body of [+ "Model not exist",+ JSON.stringify({ error: { message: "Model not exist" } }),+ "Model deepseek-v4-pro-0813 is not supported",+ ]) {+ test(`E1 unsupported wording survives its error envelope: ${body}`, () => {+ expect(hasModelUnsupportedWording(body)).toBe(true);+ });+ }+ for (const body of [+ "InvalidApiKey",+ "invalid access token or token expired",+ "Incorrect API key provided",+ ]) {+ test(`E2 the measured credential rejection is not model exclusion: ${body}`, () => {+ expect(hasModelUnsupportedWording(body)).toBe(false);+ });+ }+ test("E3 a vendor action URL is recognized so a generic key hint need not contradict it", () => {+ const body = JSON.stringify({+ error: {+ type: "RegionError",+ message:+ "The latest version of this model is only available hosted in China and requires explicit opt in: https://opencode.ai/workspace/qa/go",+ },+ });+ expect(hasActionableLink(body)).toBe(true);+ expect(hasModelUnsupportedWording(body)).toBe(false);+ });+ test("E4 a credential error without a link does not pretend to contain an action URL", () => {+ expect(hasActionableLink("Incorrect API key provided")).toBe(false);+ });+});diff --git a/packages/cli/src/handlers/shared/model-unsupported.ts b/packages/cli/src/handlers/shared/model-unsupported.tsindex e16126e5..fe1f5ace 100644--- a/packages/cli/src/handlers/shared/model-unsupported.ts+++ b/packages/cli/src/handlers/shared/model-unsupported.ts@@ -49,6 +49,18 @@ const UNSUPPORTED_PHRASES = ["model not found","model_not_found","unknown model",+ // Alibaba's wording, and it is NOT a typo on our side: the Token Plan and+ // PAYG hosts answer an id their silo does not serve with a bare+ // `400 Model not exist` (measured 2026-09-17; `qwen-alibaba.md` records the+ // dead end it produced). It matched none of the phrases above — not "model+ // not found", not "does not exist" — so the one hint claudish could give was+ // "Request format may be incompatible with provider", which sends the reader+ // to audit a payload that is fine.+ //+ // Recognised for the MESSAGE only. `FallbackHandler.isRetryableError` keeps+ // its own 400 phrase list and deliberately does not carry this one, so the+ // chain still stops on it rather than advancing.+ "model not exist","no such model",] as const;diff --git a/packages/cli/src/providers/provider-definitions.ts b/packages/cli/src/providers/provider-definitions.tsindex d288d0c1..3ad167a0 100644--- a/packages/cli/src/providers/provider-definitions.ts+++ b/packages/cli/src/providers/provider-definitions.ts@@ -1487,8 +1487,15 @@ export function describeMissingCredential(providerName: string): string {* is already in the catalog as `apiKeyEnvVar`. A variable no provider claims* (a rename, a removal) degrades to the bare name instead of asserting a* provider that no longer exists.+ *+ * Exported because the SECOND place a user meets this fact is a 401 — they set+ * the sibling key, and the vendor's other host rejected it with wording that+ * attributes nothing (`invalid access token or token expired`). The recovery+ * hint in `composed-handler.ts` appends this same sentence there, rather than+ * writing a second one, so the "no key" copy and the "wrong key" copy can never+ * disagree about which variable belongs to which plan.*/-function describeSiblingKeys(def: ProviderDefinition | undefined): string {+export function describeSiblingKeys(def: ProviderDefinition | undefined): string {const vars = def?.siblingKeyEnvVars ?? [];if (vars.length === 0) return "";const all = getAllProviders();diff --git a/packages/cli/src/test-helpers/blackbox-env.ts b/packages/cli/src/test-helpers/blackbox-env.tsnew file mode 100644index 00000000..774df595--- /dev/null+++ b/packages/cli/src/test-helpers/blackbox-env.ts@@ -0,0 +1,114 @@+/**+ * Isolation harness for the BLACK-BOX behaviour suite (`*.blackbox.test.ts`).+ *+ * Those files were written by an external model that never saw this repository's+ * implementation — only the spec, the acceptance criteria and `.d.ts` contracts+ * with every body stripped. This module is the only part of that delivery that+ * was rewritten on integration, and it was rewritten for one reason: the+ * original relocated `HOME` and replaced `globalThis.fetch` at MODULE LOAD and+ * restored them only at `process.once("exit")`.+ *+ * That is correct inside a sandbox holding seven files and wrong inside a+ * 231-file suite. Bun's test runner shares one process across every test file —+ * the same property that makes `mock.module()` bleed here — so a process-wide+ * `HOME` swap changes what every LATER file sees, and several modules snapshot+ * their paths at module scope (`profile-config.ts:18`,+ * `all-models-cache.ts:102`), so the swap would also be invisible to the very+ * readers it was meant to redirect. A permanently throwing `fetch` would take+ * the live-API tests with it.+ *+ * So the isolation is FILE-SCOPED: `useBlackboxEnv()` installs in `beforeAll`+ * and uninstalls in `afterAll`. The writer's two guarantees are kept intact —+ * no real user state, and a fail-closed network tripwire whose `afterEach`+ * check catches even an implementation that swallows the rejection.+ *+ * Config reads are isolated through the repo's own seam+ * (`setConfigFileOverride`) rather than through `HOME`, because the module-level+ * snapshot above means a relocated `HOME` cannot reach `loadConfig()` at all.+ */+import { afterAll, afterEach, beforeAll, expect } from "bun:test";+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++/** A cold, generated HOME. Never the developer's. */+export const sandboxHome = mkdtempSync(join(tmpdir(), "claudish-blackbox-home-"));+mkdirSync(join(sandboxHome, ".claudish"), { recursive: true });++/**+ * The writer's contract also named a variable that switched off an on-disk+ * store of the dynamic models catalog. It is deliberately NOT here: that store+ * was deleted in `fe8722e`, and the variable with it.+ */+const RELOCATED: Record<string, string> = {+ HOME: sandboxHome,+ USERPROFILE: sandboxHome,+ XDG_CONFIG_HOME: join(sandboxHome, ".config"),+ CLAUDISH_DISABLE_KEYCHAIN: "1",+ CLAUDISH_DISABLE_OP: "1",+};++const saved = new Map<string, string | undefined>();+let realFetch: typeof globalThis.fetch | null = null;+const attemptedFetches: string[] = [];++function install(): void {+ if (realFetch) return;+ for (const [name, value] of Object.entries(RELOCATED)) {+ saved.set(name, process.env[name]);+ process.env[name] = value;+ }+ realFetch = globalThis.fetch;+ const tripwire = async (input: unknown) => {+ const url =+ typeof input === "string"+ ? input+ : input instanceof URL+ ? input.href+ : ((input as { url?: string })?.url ?? "unknown");+ attemptedFetches.push(`Unexpected network access: ${url}`);+ throw new Error("Black-box QA forbids network access");+ };+ // `preconnect` is a Bun/undici extension on the real `fetch`; carry it over so+ // the replacement is structurally a `fetch` and nothing downstream throws on a+ // missing property before the tripwire can record the attempt.+ tripwire.preconnect = realFetch.preconnect;+ globalThis.fetch = tripwire as unknown as typeof fetch;+}++function uninstall(): void {+ if (!realFetch) return;+ globalThis.fetch = realFetch;+ realFetch = null;+ for (const [name, value] of saved) restoreEnv(name, value);+ saved.clear();+}++/**+ * Install the isolation for the CALLING test file. Call it once, at the top of+ * the file, before any `describe`.+ */+export function useBlackboxEnv(): void {+ beforeAll(install);+ afterEach(() => {+ const attempts = attemptedFetches.splice(0);+ expect(attempts).toEqual([]);+ });+ afterAll(uninstall);+}++process.once("exit", () => {+ uninstall();+ rmSync(sandboxHome, { recursive: true, force: true });+});++/** A fresh scratch directory under the sandbox HOME. */+export function scratchDirectory(label: string): string {+ return mkdtempSync(join(sandboxHome, `${label}-`));+}++/** Put one environment variable back exactly as it was, absent included. */+export function restoreEnv(name: string, value: string | undefined): void {+ if (value === undefined) delete process.env[name];+ else process.env[name] = value;+}