Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

fix(routing): name an unknown provider shortcut instead of no credential

Jack Rudenko66180b6935d3
diff --git a/packages/cli/src/handlers/advisor-route-plan.ts b/packages/cli/src/handlers/advisor-route-plan.ts
index e2c182d6..c793c350 100644
--- a/packages/cli/src/handlers/advisor-route-plan.ts
+++ b/packages/cli/src/handlers/advisor-route-plan.ts
@@ -333,6 +333,7 @@ export const SKIPPED_PHRASE: Readonly<Record<Exclude<CandidateOutcome, "kept">,
"not-served": "the account does not serve it",
"excluded-by-membership": "not in the plan's membership",
"excluded-by-content-use": "content-use opt-in id only",
+ "unknown-provider": "unknown provider shortcut",
};
/**
diff --git a/packages/cli/src/providers/probe-runner.ts b/packages/cli/src/providers/probe-runner.ts
index 8ab19e52..7eb0c2f8 100644
--- a/packages/cli/src/providers/probe-runner.ts
+++ b/packages/cli/src/providers/probe-runner.ts
@@ -30,6 +30,7 @@ export const DROPPED_LABEL: Record<DroppedOutcome, string> = {
"not-served": "account does not serve it",
"excluded-by-membership": "not in the plan's membership",
"excluded-by-content-use": "contributor id: content-use opt-in, type it exactly to use it",
+ "unknown-provider": "unknown provider shortcut",
};
/**
diff --git a/packages/cli/src/providers/routing-rules.ts b/packages/cli/src/providers/routing-rules.ts
index 133eb195..a7a8a835 100644
--- a/packages/cli/src/providers/routing-rules.ts
+++ b/packages/cli/src/providers/routing-rules.ts
@@ -25,6 +25,11 @@ import {
gatherRouteCandidates,
} from "./route-candidates.js";
import { buildCredentialHint } from "./routing-hints.js";
+import {
+ describeUnknownShortcut,
+ isKnownProviderName,
+ typedShortcutOf,
+} from "./unknown-shortcut.js";
export interface RoutingRuleSources {
globalRules: RoutingRules;
@@ -502,7 +507,12 @@ export type CandidateOutcome =
* The provider maps the model only through a content-use opt-in wire id, which
* claudish never chooses; typed exactly (`provider@<id>`), it is sent.
*/
- | "excluded-by-content-use";
+ | "excluded-by-content-use"
+ /**
+ * An explicit spec's shortcut names no claudish provider (`isKnownProviderName`).
+ * Decided before any credential is read.
+ */
+ | "unknown-provider";
/** One route candidate, where the chain placed it, and what became of it. */
export interface ExplainedCandidate {
@@ -550,6 +560,8 @@ export type NoRouteCause =
| "no-credential"
/** The account's dynamic models catalog denied every credentialed candidate. */
| "not-served"
+ /** An explicit spec's shortcut names no claudish provider (`describeUnknownShortcut`). */
+ | "explicit-unknown-shortcut"
/** An explicit spec's provider has no credential. */
| "explicit-no-credential"
/** An explicit spec's plan membership excludes the model, so no route could be built. */
@@ -685,6 +697,14 @@ async function explainExplicitSpec(
provider: string,
cachePath?: string
): Promise<RouteExplanation> {
+ // FIRST, ahead of every credential read: a shortcut that names no provider is
+ // answered as unknown, never as "no credentials". No authority lookup, readiness
+ // probe or 1Password attempt runs for a name that cannot exist (D9). This check
+ // must stay ahead of any credential read added to this function later.
+ if (!isKnownProviderName(provider)) {
+ return explainUnknownShortcut(requestedModel, modelSpec, model, provider, cachePath);
+ }
+
const credentialed = await hasCredentialsForProvider(provider);
// The one candidate is built whatever the credential says, so a display can
@@ -748,6 +768,44 @@ async function explainExplicitSpec(
return explanation;
}
+/**
+ * An explicit spec whose shortcut names no claudish provider. The one candidate
+ * names what was typed, with no tier and no catalog lookup; the outcome carries
+ * `describeUnknownShortcut`'s wording, which every surface prints verbatim.
+ */
+function explainUnknownShortcut(
+ requestedModel: string,
+ modelSpec: string,
+ model: string,
+ provider: string,
+ cachePath?: string
+): RouteExplanation {
+ const { reason, hint } = describeUnknownShortcut(
+ typedShortcutOf(modelSpec),
+ model,
+ cachePath,
+ modelSpec
+ );
+ return {
+ requestedModel,
+ routedModel: model,
+ source: "explicit",
+ via: "model-spec",
+ candidates: [
+ {
+ provider,
+ displayName: provider,
+ modelSpec,
+ wireId: model,
+ position: "candidate",
+ outcome: "unknown-provider",
+ },
+ ],
+ outcome: { kind: "no-route", cause: "explicit-unknown-shortcut", reason, hint },
+ warnings: [],
+ };
+}
+
/**
* The provider that occupies the LAST hop, or null when the user disabled it.
*
@@ -1635,6 +1693,7 @@ const DROPPED_FALLBACK_PHRASE: Record<Exclude<CandidateOutcome, "kept">, string>
"not-served": "does not serve it",
"excluded-by-membership": "is outside its plan's membership",
"excluded-by-content-use": "maps it only through a contributor (content-use opt-in) id",
+ "unknown-provider": "is not a known provider shortcut",
};
/**
diff --git a/packages/cli/src/providers/unknown-shortcut.ts b/packages/cli/src/providers/unknown-shortcut.ts
new file mode 100644
index 00000000..3ef2604e
--- /dev/null
+++ b/packages/cli/src/providers/unknown-shortcut.ts
@@ -0,0 +1,145 @@
+/**
+ * An explicit spec whose provider shortcut names no claudish provider.
+ *
+ * `parseModelSpec` passes an unknown shortcut through as the provider name, so before
+ * this module `[email protected]` (`go@` was removed in v7.36.0) reached the credential
+ * filter and was answered `No credentials configured for "go"`: a credential hunt for a
+ * name that cannot exist (model-failures-2026-10-21.md, D9). Routing, the proxy and
+ * every display built on `explainRoute` (preflight, `--probe`, the config TUI) now ask
+ * {@link isKnownProviderName} first and print {@link describeUnknownShortcut}'s two
+ * strings, so the same spec is never worded two ways.
+ *
+ * The suggestions come from the route candidates gathered for the model, spelled as the
+ * shortcut table spells them. No model id and no provider name is hardcoded here, and
+ * no alias is added for a removed shortcut (CLAUDE.md, static values).
+ */
+import { loadConfig } from "../profile-config.js";
+import { ensureEndpointsRegistered } from "./endpoint-registration.js";
+import { PREDEFINED_ENDPOINTS } from "./predefined-catalog.js";
+import { getProviderByName, getShortcuts, getShortestPrefix } from "./provider-definitions.js";
+import { gatherRouteCandidates } from "./route-candidates.js";
+import { hopLabel } from "./routing-rules.js";
+
+/** The raw-URL provider `parseModelSpec` produces for `http(s)://…`; it has no definition. */
+const CUSTOM_URL_PROVIDER = "custom-url";
+
+/**
+ * A name claudish can route an explicit spec to, whether or not it holds a credential:
+ * a builtin or runtime-registered provider, a bundled endpoint (known even with no key,
+ * so it keeps the credential message), a `customEndpoints` key in the global config
+ * (known even when its registration failed, so the recorded reason still wins), or
+ * `custom-url`.
+ */
+export function isKnownProviderName(name: string): boolean {
+ const lower = name.toLowerCase();
+ if (lower === CUSTOM_URL_PROVIDER) return true;
+ // Latched and config-only; routing calls it on the same path.
+ ensureEndpointsRegistered();
+ if (getProviderByName(lower)) return true;
+ if (PREDEFINED_ENDPOINTS.some((endpoint) => endpoint.name === lower)) return true;
+ const custom = loadConfig().customEndpoints;
+ return custom !== undefined && Object.keys(custom).some((key) => key.toLowerCase() === lower);
+}
+
+/** One provider that serves the model, as a user would type it. */
+export interface ShortcutSuggestion {
+ /** The shortcut the picker emits for the provider (`getShortestPrefix`). */
+ shortcut: string;
+ /** claudish provider. */
+ provider: string;
+ displayName: string;
+ /** The tier words `--probe` shows (`hopLabel`). */
+ label: string;
+}
+
+/**
+ * Providers that serve `model`, in routing-chain order: the catalog's connections and
+ * the namespace claims (`gatherRouteCandidates`). No credential filter: the question is
+ * what the user meant, not what they can pay for. Every gathered provider, no cap.
+ */
+export function suggestProviderShortcuts(model: string, cachePath?: string): ShortcutSuggestion[] {
+ const seen = new Set<string>();
+ const out: ShortcutSuggestion[] = [];
+ for (const candidate of gatherRouteCandidates(model, cachePath).candidates) {
+ if (seen.has(candidate.provider)) continue;
+ seen.add(candidate.provider);
+ out.push({
+ shortcut: getShortestPrefix(candidate.provider),
+ provider: candidate.provider,
+ displayName: getProviderByName(candidate.provider)?.displayName ?? candidate.provider,
+ label: hopLabel({ tier: candidate.tier }),
+ });
+ }
+ return out;
+}
+
+/** Shortcuts one edit away from `typed`, for a model nothing was gathered for. */
+function nearbyShortcuts(typed: string): string[] {
+ const lower = typed.toLowerCase();
+ return Object.keys(getShortcuts())
+ .filter((shortcut) => shortcut !== lower && withinOneEdit(shortcut, lower))
+ .sort();
+}
+
+/** Levenshtein distance ≤ 1, without building the matrix. */
+function withinOneEdit(a: string, b: string): boolean {
+ if (Math.abs(a.length - b.length) > 1) return false;
+ let i = 0;
+ let j = 0;
+ let edits = 0;
+ while (i < a.length && j < b.length) {
+ if (a[i] === b[j]) {
+ i++;
+ j++;
+ continue;
+ }
+ if (++edits > 1) return false;
+ if (a.length > b.length) i++;
+ else if (a.length < b.length) j++;
+ else {
+ i++;
+ j++;
+ }
+ }
+ return edits + (a.length - i) + (b.length - j) <= 1;
+}
+
+const EVERY_SHORTCUT = "Every shortcut: claudish --help.";
+
+/**
+ * The ONE wording for an unknown shortcut. Every surface prints exactly these strings.
+ *
+ * @param typed the shortcut as the user wrote it (the spec before its first `@`)
+ * @param model the model part, which the suggestions are spelled with
+ * @param spec the whole spec as typed, markers included (`[email protected]+pro`);
+ * defaults to `typed@model`
+ */
+export function describeUnknownShortcut(
+ typed: string,
+ model: string,
+ cachePath?: string,
+ spec = `${typed}@${model}`
+): { reason: string; hint: string } {
+ const reason = `Unknown provider shortcut "${typed}" in "${spec}".`;
+ const suggestions = suggestProviderShortcuts(model, cachePath);
+ if (suggestions.length > 0) {
+ const list = suggestions
+ .map((s) => `${s.shortcut}@${model} (${s.displayName}, ${s.label})`)
+ .join(" · ");
+ return { reason, hint: `Providers that serve ${model}: ${list}. ${EVERY_SHORTCUT}` };
+ }
+ const near = nearbyShortcuts(typed);
+ if (near.length > 0) {
+ return {
+ reason,
+ hint: `Shortcuts close to "${typed}": ${near.map((s) => `${s}@`).join(", ")}. ${EVERY_SHORTCUT}`,
+ };
+ }
+ return { reason, hint: EVERY_SHORTCUT };
+}
+
+/** The shortcut as typed: the part of the original spec before its first `@`. */
+export function typedShortcutOf(originalSpec: string): string {
+ const at = originalSpec.indexOf("@");
+ return at < 0 ? originalSpec : originalSpec.slice(0, at);
+}
diff --git a/packages/cli/src/tui/components/RoutingContent.tsx b/packages/cli/src/tui/components/RoutingContent.tsx
index 802028c5..54804080 100644
--- a/packages/cli/src/tui/components/RoutingContent.tsx
+++ b/packages/cli/src/tui/components/RoutingContent.tsx
@@ -31,6 +31,7 @@ const DROPPED_TEXT: Record<DroppedOutcome, string> = {
"not-served": "the account does not serve it",
"excluded-by-membership": "not in the plan's membership",
"excluded-by-content-use": "contributor id: content-use opt-in, type it exactly to use it",
+ "unknown-provider": "unknown provider shortcut",
};
/**