Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
fix(mcp): probe preflight hops in chain order until one serves
Jack Rudenkob138f00d453a
diff --git a/packages/cli/src/mcp-server.ts b/packages/cli/src/mcp-server.tsindex d3f02990..b5514881 100644--- a/packages/cli/src/mcp-server.ts+++ b/packages/cli/src/mcp-server.ts@@ -19,7 +19,6 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotimport { searchCatalogModels } from "./adapters/model-catalog.js";import { prehydrateCredentialsForSpawn } from "./auth/credentials/prehydrate.js";import { setCredentialPromptRole } from "./auth/credentials/prompt-role.js";-import { isSubscriptionProvider } from "./handlers/shared/remote-provider-types.js";import { loadHooksOnce } from "./hooks/index.js";import { type ProtocolStdout, isolateProtocolStdout } from "./hooks/output-capture.js";import { initLogger, log } from "./logger.js";@@ -60,11 +59,15 @@ import {import { findAvailablePort } from "./port-manager.js";import { ensureEndpointsRegistered } from "./providers/endpoint-registration.js";import { compareByReleaseDateDesc } from "./providers/model-ordering.js";-import { isLocalProviderName } from "./providers/model-parser.js";-import { NATIVE_NOT_PROBED, nativeRouteFor } from "./providers/native-route.js";+import { nativeRouteFor } from "./providers/native-route.js";import { renderOpFailureBlock } from "./providers/onepassword.js";-import { isReadyState, probeLink } from "./providers/probe-live.js";-import { route } from "./providers/routing-rules.js";+import {+ type PreflightModelResult,+ preflightModel,+ renderPreflightReport,+} from "./providers/preflight-chain.js";+import { probeLink } from "./providers/probe-live.js";+import type { ProbeTarget } from "./providers/probe-runner.js";import { createProxyServer } from "./proxy-server.js";import { nativeShortcutForVendor, renderRecommendedMarkdown } from "./recommended-listing.js";import { sanitizeForReport } from "./redact.js";@@ -470,46 +473,9 @@ export const NEXT_STEP: Record<FailureReason, string> = {"count this slot as a vote",};-/**- * The Details cell of a preflight "no route" row: the reason, then EVERY line- * of the plan's hint — for a missing credential that is the same login- * instruction `--probe` prints. Without it the row read only `No credentials- * configured for "meta-muse-code".`, which an agent cannot act on.- *- * Hints come in two shapes. Most are one remedy sentence (explicit-not-served,- * catalog-unreadable, …), kept whole. `buildCredentialHint`'s is a header- * (`No credentials found for "<model>". Options:`) and one line per option.- * Only a line that REPEATS the reason is dropped, and that header is one: it- * restates the reason's "no credentials" before the options.- *- * One table cell, so the kept lines are joined with ` · ` (a space after a- * line ending in `:`), whitespace runs collapse, and a `|` is escaped.- */-export function noRouteCell(reason: string, hint?: string): string {- const flat = (s: string) => s.replace(/\s+/g, " ").trim();- const lines = (hint ?? "")- .split("\n")- .map(flat)- .filter((line) => line && !repeatsNoRouteReason(line, flat(reason)));- // A line ending in ":" introduces the next, so it joins with a space.- const joined = lines.reduce(- (acc, line, i) => (i === 0 ? line : `${acc}${lines[i - 1].endsWith(":") ? " " : " · "}${line}`),- ""- );- const cell = joined ? `${reason} ${joined}` : reason;- return cell.replace(/\|/g, "\\|");-}--/** A hint line that restates the reason: the same text, or the credential hint's header. */-function repeatsNoRouteReason(line: string, reason: string): boolean {- if (line === reason) return true;- return (- // "No credentials configured for …" and "No credentialed providers in …".- reason.startsWith("No credential") &&- line.startsWith("No credentials found for ") &&- line.endsWith("Options:")- );-}+// The preflight "no route" cell moved to `providers/preflight-chain.ts` with the+// rest of the preflight report; re-exported for existing importers.+export { noRouteCell } from "./providers/preflight-chain.js";/** `18864` → `18.4KB`. */function fmtSize(n: number): string {@@ -1248,7 +1214,9 @@ function defineTools(sessionManager: SessionManager, nested: boolean): ToolDefin},timeout_ms: {type: "number",- description: "Per-model probe timeout in ms (default 20000).",+ description:+ "Probe timeout in ms PER HOP (default 20000). A model whose first hop fails is " ++ "probed down its routing chain until a hop serves, so it can take hops × this.",},},required: ["models"],@@ -1288,141 +1256,38 @@ function defineTools(sessionManager: SessionManager, nested: boolean): ToolDefin// Sync, latched, config-only. Free after the first call.ensureEndpointsRegistered();- const rows: string[] = [];- const readyModels: string[] = [];- const failedModels: string[] = [];- const nativeModels: string[] = [];- let subCount = 0;- let meteredCount = 0;-- for (const model of models) {- ctx.reportProgress(`preflight: ${model}`);-- // A bare Claude name never reaches route(): the proxy serves it on the- // harness's own auth and checks for that BEFORE routing. route() cannot- // see that path — `native-anthropic` has no credential store, so its- // filter drops it and the chain degrades to OpenRouter — and preflight- // was reporting subscription models as "no route" / "metered".- const native = nativeRouteFor(model);- if (native) {- // Deliberately NOT probed. The native handler authenticates by forwarding- // the INBOUND request's Claude Code header (native-handler.ts) and only- // falls back to ANTHROPIC_API_KEY. A synthetic probe from this process- // carries neither, so it fails "x-api-key header is required" for a- // healthy model and a typo alike — measured on the built bundle. That- // result is noise, and reporting it drove the very "drop your own- // model" advice this guard exists to stop. Counted in its own bucket,- // neither ready nor failed: the proxy will serve it on the session's- // auth, and that is all this process can say.- nativeModels.push(model);- rows.push(- `| \`${model}\` | ${native.displayName} | native | ${NATIVE_NOT_PROBED} | \`${native.modelSpec}\` |`- );- continue;- }-- let plan: Awaited<ReturnType<typeof route>>;- try {- plan = await route(model);- } catch (err) {- failedModels.push(model);- rows.push(- `| \`${model}\` | — | — | ❌ route error | ${err instanceof Error ? err.message : String(err)} |`- );- continue;- }-- if (plan.kind === "no-route") {- // No credentialed provider can serve this at all. Reported as a FAILURE- // rather than omitted, because "none of your credentials reaches this model" is the- // single most useful thing to learn before the run rather than during it.- failedModels.push(model);- rows.push(- `| \`${model}\` | — | — | ❌ no route | ${noRouteCell(plan.reason, plan.hint)} |`- );- continue;- }-- const primary = plan.primary;- // Billing mode is a property of the PROVIDER, not the model — the same- // model can be flat-rate through a plan and metered through a vendor API,- // and which one a bare name lands on is exactly what a caller cannot see.- const billing = isLocalProviderName(primary.provider)- ? "local"- : isSubscriptionProvider(primary.provider)- ? "SUB"- : "metered";- if (billing === "SUB") subCount++;- else if (billing === "metered") meteredCount++;-- let status = "not probed";- let ok = true;- if (proxy) {- try {- const result = await probeLink(+ // Each model is judged by its ROUTING CHAIN (`preflight-chain.ts`): kept hops+ // in chain order, each probed until one serves, a failed hop followed by the+ // runtime's own advance/stop rule. A native Claude name is never probed (the+ // native handler forwards the inbound Claude Code header, which this process+ // does not have), and counts as neither ready nor failed. `timeout_ms` is per+ // hop. Metered hops are probed too: the runtime would use them.+ const probe = proxy+ ? (target: ProbeTarget) =>+ probeLink(proxy.url,- {- provider: primary.provider,- // route() already credential-filtered, so a miss here would be a- // routing bug, not a missing key.- modelSpec: primary.modelSpec,- hasCredentials: true,- },+ // A kept hop passed the credential filter, so a miss here would be a+ // routing bug, not a missing key.+ { provider: target.provider, modelSpec: target.probeSpec, hasCredentials: true },timeoutMs- );- ok = isReadyState(result.state);- status = ok- ? `✅ ${result.state}`- : `❌ ${result.state}${result.errorMessage ? ` — ${result.errorMessage}` : ""}`;- } catch (err) {- ok = false;- status = `❌ probe error — ${err instanceof Error ? err.message : String(err)}`;- }- }+ )+ : null;- if (ok) readyModels.push(model);- else failedModels.push(model);-- const fallbacks = plan.fallbacks.length > 0 ? ` (+${plan.fallbacks.length} fallback)` : "";- rows.push(- `| \`${model}\` | ${primary.displayName}${fallbacks} | ${billing} | ${status} | \`${primary.modelSpec}\` |`- );- }-- const lines = [- `# Preflight — ${models.length} model${models.length === 1 ? "" : "s"}`,- "",- `**Ready: ${readyModels.length}** · **Failed: ${failedModels.length}** · ` +- (nativeModels.length > 0 ? `native (not probed): ${nativeModels.length} · ` : "") +- `subscription: ${subCount} · metered: ${meteredCount}`,- "",- "| Model | Provider | Billing | Status | Wire id |",- "|---|---|---|---|---|",- ...rows,- ];-- if (failedModels.length > 0) {- lines.push(- "",- `⚠️ Drop or replace before running: ${failedModels.map((m) => `\`${m}\``).join(", ")}`- );- }- if (meteredCount > 0) {- lines.push(- "",- `💸 ${meteredCount} model${meteredCount === 1 ? "" : "s"} will be billed PER TOKEN. ` +- "A bare name can land on a metered provider when the subscription that covers it " +- "has no credential configured — name the provider explicitly to pin it."- );- }- if (!doProbe) {- lines.push(- "",- "ℹ️ `probe: false` — routing and billing only. Reachability was NOT checked."+ const results: PreflightModelResult[] = [];+ for (const model of models) {+ ctx.reportProgress(`preflight: ${model}`);+ results.push(+ await preflightModel(model, {+ probe,+ // The heartbeat names what it is waiting on.+ onHop: (hop, total) =>+ ctx.reportProgress(`preflight: ${model} · hop ${hop.index}/${total}`),+ }));}- return { content: [{ type: "text" as const, text: lines.join("\n") }] };+ const text = renderPreflightReport(results, { probed: doProbe });+ return { content: [{ type: "text" as const, text }] };},});diff --git a/packages/cli/src/providers/preflight-chain.ts b/packages/cli/src/providers/preflight-chain.tsnew file mode 100644index 00000000..d87d4981--- /dev/null+++ b/packages/cli/src/providers/preflight-chain.ts@@ -0,0 +1,342 @@+/**+ * Preflight judges a model by its ROUTING CHAIN, not by its first hop.+ *+ * The MCP `preflight` tool used to plan with `route(model)` and probe only the primary,+ * so a model whose hop 1 failed got "❌" and "Drop or replace before running" even when a+ * later hop would serve it (model-failures-2026-10-21.md, D6). Since 14.0.0 a rejected+ * subscription key advances the chain, which made that wrong more often.+ *+ * {@link preflightModel} walks the kept hops in chain order (`explainRoute` →+ * `probeTargets`, the chain `--probe` shows) and probes each until one serves. A failed+ * hop is followed by the runtime's own decision (`ProbeResult.chainAction`, from+ * `decideHopFailure`, shared with `FallbackHandler`): advance to the next hop, or stop+ * here because a real request would stop here too. Metered hops are probed like any+ * other (a configured key is consent, and the runtime would use that hop); the report+ * names each hop's billing. A native Claude name is never probed (CLAUDE.md: the third+ * outcome). Pure apart from the injected probe.+ */+import { isSubscriptionProvider } from "../handlers/shared/remote-provider-types.js";+import { redactSecrets } from "../redact.js";+import { isLocalProviderName } from "./model-parser.js";+import { NATIVE_NOT_PROBED, nativeRouteFor } from "./native-route.js";+import { type ProbeChainReason, type ProbeResult, describeProbeState } from "./probe-live.js";+import { type ProbeTarget, probeTargets } from "./probe-runner.js";+import { type NoRouteCause, type RouteExplanation, explainRoute } from "./routing-rules.js";++/** How a hop bills. */+export type HopBilling = "subscription" | "metered" | "local";++/** Why the walker moved on or stopped at a failed hop. */+export type WalkerReason =+ | ProbeChainReason+ /** A non-live result with no `chainAction` (key-missing, any future state): stop. */+ | "no-decision"+ /** The injected probe threw: stop. */+ | "probe-error";++/** One kept hop of a model's routing chain, and what probing it found. */+export interface PreflightHop {+ provider: string;+ displayName: string;+ /** The model spec the probe sends (`provider@wire id`, or the explicit spec as typed). */+ probeSpec: string;+ wireId: string;+ position: "candidate" | "fallback";+ billing: HopBilling;+ /** 1-based position among the kept hops. */+ index: number;+ /** Absent when the hop was not probed; synthesized when the probe threw. */+ result?: ProbeResult;+ /** Set on every failed hop. */+ action?: "advance" | "stop";+ reason?: WalkerReason;+}++export type PreflightModelResult =+ | { kind: "native"; model: string; displayName: string; modelSpec: string }+ | { kind: "no-route"; model: string; cause: NoRouteCause; reason: string; hint?: string }+ /** Routing itself threw. */+ | { kind: "route-error"; model: string; message: string }+ /** `probe: false`: the chain, unprobed. */+ | { kind: "planned"; model: string; hops: PreflightHop[] }+ | {+ kind: "served";+ model: string;+ served: PreflightHop;+ failed: PreflightHop[];+ untried: number;+ total: number;+ }+ | {+ kind: "failed";+ model: string;+ failed: PreflightHop[];+ /** The hop where the chain stops; absent when every hop advanced. */+ heldAt?: PreflightHop;+ untried: number;+ total: number;+ };++export interface PreflightDeps {+ /** null = `probe: false`: plan only, send nothing. */+ probe: ((target: ProbeTarget) => Promise<ProbeResult>) | null;+ /** Default `explainRoute`. */+ explain?: (model: string) => Promise<RouteExplanation>;+ /** Called before each hop is probed (progress reporting). */+ onHop?: (hop: PreflightHop, total: number) => void;+}++/** How a provider bills: local, subscription (`isSubscriptionProvider`), else metered. */+export function hopBilling(provider: string): HopBilling {+ if (isLocalProviderName(provider)) return "local";+ return isSubscriptionProvider(provider) ? "subscription" : "metered";+}++function toHop(target: ProbeTarget, index: number): PreflightHop {+ return {+ provider: target.provider,+ displayName: target.displayName,+ probeSpec: target.probeSpec,+ wireId: target.wireId,+ position: target.position,+ billing: hopBilling(target.provider),+ index,+ };+}++/** Walk one model's routing chain, probing hops in order until one serves. */+export async function preflightModel(+ model: string,+ deps: PreflightDeps+): Promise<PreflightModelResult> {+ const native = nativeRouteFor(model);+ if (native) {+ return {+ kind: "native",+ model,+ displayName: native.displayName,+ modelSpec: native.modelSpec,+ };+ }++ let explanation: RouteExplanation;+ try {+ explanation = await (deps.explain ?? explainRoute)(model);+ } catch (err) {+ return {+ kind: "route-error",+ model,+ message: redactSecrets(err instanceof Error ? err.message : String(err)),+ };+ }+ const { outcome } = explanation;+ if (outcome.kind === "no-route") {+ return {+ kind: "no-route",+ model,+ cause: outcome.cause,+ reason: outcome.reason,+ ...(outcome.hint !== undefined ? { hint: outcome.hint } : {}),+ };+ }++ const targets = probeTargets(explanation);+ const hops = targets.map((target, i) => toHop(target, i + 1));+ const total = hops.length;+ if (!deps.probe) return { kind: "planned", model, hops };++ const failed: PreflightHop[] = [];+ for (let i = 0; i < hops.length; i++) {+ const hop = hops[i];+ deps.onHop?.(hop, total);+ let result: ProbeResult;+ try {+ result = await deps.probe(targets[i]);+ } catch (err) {+ // The probe itself failed: nothing says a later hop serves, so stop.+ hop.result = {+ state: "network-error",+ latencyMs: 0,+ errorMessage: redactSecrets(err instanceof Error ? err.message : String(err)),+ };+ hop.action = "stop";+ hop.reason = "probe-error";+ failed.push(hop);+ return { kind: "failed", model, failed, heldAt: hop, untried: total - hop.index, total };+ }+ hop.result = result;+ if (result.state === "live") {+ return { kind: "served", model, served: hop, failed, untried: total - hop.index, total };+ }+ if (result.chainAction === "advance") {+ hop.action = "advance";+ hop.reason = result.chainReason;+ failed.push(hop);+ continue;+ }+ // "stop", or no decision at all: stopping never claims a later hop serves on+ // evidence the runtime's rule did not produce.+ hop.action = "stop";+ hop.reason = result.chainAction === "stop" ? result.chainReason : "no-decision";+ failed.push(hop);+ return { kind: "failed", model, failed, heldAt: hop, untried: total - hop.index, total };+ }+ return { kind: "failed", model, failed, untried: 0, total };+}++// ── Rendering ────────────────────────────────────────────────────────────────++/**+ * The Details cell of a preflight "no route" row: the reason, then EVERY line+ * of the plan's hint — for a missing credential that is the same login+ * instruction `--probe` prints. Without it the row read only `No credentials+ * configured for "meta-muse-code".`, which an agent cannot act on.+ *+ * Hints come in two shapes. Most are one remedy sentence (explicit-not-served,+ * catalog-unreadable, …), kept whole. `buildCredentialHint`'s is a header+ * (`No credentials found for "<model>". Options:`) and one line per option.+ * Only a line that REPEATS the reason is dropped, and that header is one: it+ * restates the reason's "no credentials" before the options.+ *+ * One table cell, so the kept lines are joined with ` · ` (a space after a+ * line ending in `:`), whitespace runs collapse, and a `|` is escaped.+ */+export function noRouteCell(reason: string, hint?: string): string {+ const flat = (s: string) => s.replace(/\s+/g, " ").trim();+ const lines = (hint ?? "")+ .split("\n")+ .map(flat)+ .filter((line) => line && !repeatsNoRouteReason(line, flat(reason)));+ // A line ending in ":" introduces the next, so it joins with a space.+ const joined = lines.reduce(+ (acc, line, i) => (i === 0 ? line : `${acc}${lines[i - 1].endsWith(":") ? " " : " · "}${line}`),+ ""+ );+ const cell = joined ? `${reason} ${joined}` : reason;+ return cell.replace(/\|/g, "\\|");+}++/** A hint line that restates the reason: the same text, or the credential hint's header. */+function repeatsNoRouteReason(line: string, reason: string): boolean {+ if (line === reason) return true;+ return (+ // "No credentials configured for …" and "No credentialed providers in …".+ reason.startsWith("No credential") &&+ line.startsWith("No credentials found for ") &&+ line.endsWith("Options:")+ );+}++/** One table cell: no newline, `|` escaped. */+function cellText(text: string): string {+ return text.replace(/\s+/g, " ").trim().replace(/\|/g, "\\|");+}++function untriedSuffix(untried: number): string {+ return untried > 0 ? ` (+${untried} untried)` : "";+}++/** What a failed hop's line ends with: where the chain went from there. */+function hopOutcomePhrase(hop: PreflightHop, total: number): string {+ if (hop.reason === "probe-error") return "❌ probe error · chain stops here";+ if (hop.reason === "no-decision") return "chain stops here (no hop decision)";+ if (hop.action !== "advance") return "chain stops here";+ return hop.index < total ? `moved to hop ${hop.index + 1}` : "no hop left";+}++function failedHopLine(model: string, hop: PreflightHop, total: number): string {+ const head = `- \`${model}\` hop ${hop.index}/${total} \`${hop.probeSpec}\` (${hop.billing}): `;+ if (hop.reason === "probe-error") {+ const message = hop.result?.errorMessage ? ` — ${hop.result.errorMessage}` : "";+ return cellText(`${head}${hopOutcomePhrase(hop, total)}${message}`);+ }+ const state = hop.result ? describeProbeState(hop.result) : "not probed";+ return cellText(`${head}❌ ${state} — ${hopOutcomePhrase(hop, total)}`);+}++/** The table row for one model. */+function rowFor(r: PreflightModelResult): string {+ switch (r.kind) {+ case "native":+ return `| \`${r.model}\` | ${r.displayName} | native | ${NATIVE_NOT_PROBED} | \`${r.modelSpec}\` |`;+ case "no-route":+ return `| \`${r.model}\` | — | — | ❌ no route | ${noRouteCell(r.reason, r.hint)} |`;+ case "route-error":+ return `| \`${r.model}\` | — | — | ❌ route error | ${cellText(r.message)} |`;+ case "planned": {+ const first = r.hops[0];+ return `| \`${r.model}\` | ${first.displayName} | ${first.billing} | not probed · hop 1/${r.hops.length} | \`${first.probeSpec}\` |`;+ }+ case "served": {+ const s = r.served;+ return `| \`${r.model}\` | ${s.displayName} | ${s.billing} | ✅ live · hop ${s.index}/${r.total}${untriedSuffix(r.untried)} | \`${s.probeSpec}\` |`;+ }+ case "failed": {+ const status = r.heldAt+ ? `❌ ${r.heldAt.reason === "probe-error" ? "probe error" : cellText(describeProbeState(r.heldAt.result as ProbeResult))} · chain stops at hop ${r.heldAt.index}/${r.total}${untriedSuffix(r.untried)}`+ : `❌ every hop failed (${r.total})`;+ return `| \`${r.model}\` | — | — | ${status} | — |`;+ }+ }+}++/** The billing a model counts under: the serving hop, or the first hop when not probed. */+function countedBilling(r: PreflightModelResult): HopBilling | undefined {+ if (r.kind === "served") return r.served.billing;+ if (r.kind === "planned") return r.hops[0]?.billing;+ return undefined;+}++/** The Markdown report `preflight` returns. */+export function renderPreflightReport(+ results: PreflightModelResult[],+ opts: { probed: boolean }+): string {+ const ready = results.filter((r) => r.kind === "served" || r.kind === "planned").length;+ const dropped = results.filter(+ (r) => r.kind === "failed" || r.kind === "no-route" || r.kind === "route-error"+ );+ const native = results.filter((r) => r.kind === "native").length;+ const billings = results.map(countedBilling);+ const subCount = billings.filter((b) => b === "subscription").length;+ const meteredCount = billings.filter((b) => b === "metered").length;++ const lines = [+ `# Preflight — ${results.length} model${results.length === 1 ? "" : "s"}`,+ "",+ `**Ready: ${ready}** · **Failed: ${dropped.length}** · ` ++ (native > 0 ? `native (not probed): ${native} · ` : "") ++ `subscription: ${subCount} · metered: ${meteredCount}`,+ "",+ "| Model | Provider | Billing | Status | Model spec |",+ "|---|---|---|---|---|",+ ...results.map(rowFor),+ ];++ const failedHopLines = results.flatMap((r) =>+ r.kind === "served" || r.kind === "failed"+ ? r.failed.map((hop) => failedHopLine(r.model, hop, r.total))+ : []+ );+ if (failedHopLines.length > 0) lines.push("", "Failed hops:", ...failedHopLines);++ if (dropped.length > 0) {+ lines.push(+ "",+ `⚠️ Drop or replace before running: ${dropped.map((r) => `\`${r.model}\``).join(", ")}`+ );+ }+ if (meteredCount > 0) {+ lines.push(+ "",+ `💸 ${meteredCount} model${meteredCount === 1 ? "" : "s"} will be billed PER TOKEN. ` ++ "A bare name can land on a metered provider when the subscription that covers it " ++ "has no credential configured, or when an earlier hop fails — name the provider " ++ "explicitly to pin it."+ );+ }+ if (!opts.probed) {+ lines.push("", "ℹ️ `probe: false` — routing and billing only. Reachability was NOT checked.");+ }+ return lines.join("\n");+}