@sayknow-cli/coding-agent 0.6.6 → 0.6.8

package/src/session/agent-session.ts

@@ -366,6 +366,7 @@ import { buildNamedToolChoice, buildNamedToolChoiceResult } from "../utils/tool-
 import { buildWorkflowIntentDiff, WORKFLOW_INTENT_DIFF_CUSTOM_TYPE } from "../workflow/workflow-intent-diff";
 import { buildWorkspaceTree, type WorkspaceTree } from "../workspace-tree";
 import type { AuthStorage } from "./auth-storage";
+import { autoFallbackSelectors, selectorProvider } from "./auto-fallback";
 import {
 	DefaultModelSelectionRecoveryError,
 	type DefaultModelSelectionResult,
@@ -378,6 +379,7 @@ import {
 	effectiveFallbackDelay,
 	FallbackChainController,
 } from "./fallback-chain-controller";
+import { buildResponseLanguageReminder, detectResponseLanguage } from "./response-language";
 
 export { DefaultModelSelectionRecoveryError } from "./default-model-selection";
 
@@ -868,6 +870,14 @@ const KIMI_CODE_FIRST_EVENT_TIMEOUT_MESSAGES = {
 	]),
 } as const;
 
+/**
+ * Configured default-chain origins that mean "exactly this model": a subagent call
+ * composed by the task router, and an explicit `--model` at startup. These never get
+ * `fallback.models` or automatic entries appended. (A temporary pick installs its own
+ * runtime controller and never reaches the configured-chain path at all.)
+ */
+const EXACT_FALLBACK_CHAIN_ORIGINS: ReadonlySet<string> = new Set(["subagent", "startup-override"]);
+
 const ALIBABA_TOKEN_PLAN_PROVIDER = "alibaba-token-plan";
 const ALIBABA_TOKEN_PLAN_FIRST_EVENT_TIMEOUT_MESSAGES = {
 	"openai-responses": new Set([
@@ -7832,6 +7842,7 @@ export class AgentSession {
 			const eagerTodoPrelude =
 				!options?.synthetic && !hasPendingUserDirective ? this.#createEagerTodoPrelude(expandedText) : undefined;
 			const uiSkillPrelude = options?.synthetic ? undefined : this.#createUiSkillPrelude(expandedText);
+			const languagePrelude = options?.synthetic ? undefined : this.#createResponseLanguagePrelude(expandedText);
 
 			const userContent: (TextContent | ImageContent)[] = [{ type: "text", text: expandedText }];
 			if (options?.images) {
@@ -7861,8 +7872,9 @@ export class AgentSession {
 				await this.#promptWithMessage(message, expandedText, {
 					...options,
 					prependMessages:
-						eagerTodoPrelude || uiSkillPrelude
+						eagerTodoPrelude || uiSkillPrelude || languagePrelude
 							? [
+									...(languagePrelude ? [languagePrelude] : []),
 									...(uiSkillPrelude ? [uiSkillPrelude] : []),
 									...(eagerTodoPrelude ? [eagerTodoPrelude.message] : []),
 								]
@@ -12136,6 +12148,21 @@ export class AgentSession {
 	 * routing and therefore costs nothing extra. The patterns stay in front of it: when
 	 * they match, the model is never asked.
 	 */
+	/**
+	 * Name the user's language at the start of the turn when their message is clearly in a
+	 * non-Latin script, so the final report after long English tool output stays in it.
+	 */
+	#createResponseLanguagePrelude(promptText: string): AgentMessage | undefined {
+		const language = detectResponseLanguage(promptText);
+		if (!language) return undefined;
+		return {
+			role: "developer",
+			content: [{ type: "text", text: buildResponseLanguageReminder(language) }],
+			attribution: "agent",
+			timestamp: Date.now(),
+		};
+	}
+
 	#createUiSkillPrelude(promptText: string): AgentMessage | undefined {
 		if (this.#planModeState?.enabled) return undefined;
 		const matched = buildUiSkillActivationContext(promptText);
@@ -13903,10 +13930,28 @@ export class AgentSession {
 			controller.seedResolution(activeIndex, [...controller.skips, ...resolution.skips]);
 		}
 		if (!resolution.model) throw new Error(this.#fallbackExhaustionError(controller));
+		if ((controller.chain.appendedFrom ?? controller.chain.entries.length) < 2) {
+			// A one-model configuration is a chain only through appended fallbacks. With its
+			// model usable and the session not sitting on an appended fallback, leave the live
+			// model alone exactly as before anything was appended: a context promotion or a
+			// temporary scope stays, and an unchanged model is not re-set (which would close
+			// provider sessions such as the Codex websocket on every prompt).
+			if (activeIndex === resolutionStart && !this.#isOnAppendedFallback(controller)) return;
+			if (this.model && modelsAreEqual(this.model, resolution.model)) return;
+		}
 		this.#setModelAuthoritatively(resolution.model, "restore");
 		this.setThinkingLevel(resolution.explicitThinkingLevel ? resolution.thinkingLevel : this.thinkingLevel);
 	}
 
+	/** True when the live model is one of the entries appended after the configured chain. */
+	#isOnAppendedFallback(controller: FallbackChainController): boolean {
+		const model = this.model;
+		const appendedFrom = controller.chain.appendedFrom;
+		if (!model || appendedFrom === undefined) return false;
+		const key = `${model.provider}/${model.id}`;
+		return controller.chain.entries.slice(appendedFrom).some(entry => entry === key || entry.startsWith(`${key}:`));
+	}
+
 	/**
 	 * Materialize the default controller from the persisted configured-chain
 	 * metadata. Consumers seed only resolution state; role/origin/identity stay
@@ -13925,11 +13970,12 @@ export class AgentSession {
 		if (materializeSettingsChain) {
 			this.setConfiguredModelChain("default", settingsEntries, "modelRoles");
 		}
-		const chain: ConfiguredFallbackChain = materializeSettingsChain
+		const configured: ConfiguredFallbackChain = materializeSettingsChain
 			? { role: "default", entries: settingsEntries, origin: "modelRoles", explicitHead: true }
 			: configuredChain
 				? { ...configuredChain, entries: [...configuredChain.entries] }
 				: { role: "default", entries: settingsEntries, origin: "session", explicitHead: true };
+		const chain = this.#withFallbackExtras(configured);
 		const existing = this.#defaultFallbackController;
 		if (
 			existing &&
@@ -13943,6 +13989,76 @@ export class AgentSession {
 		return this.#defaultFallbackController;
 	}
 
+	/**
+	 * Append what runs after the configured chain when it is blocked: the user's
+	 * `fallback.models`, then (with `fallback.auto`) one model from each other
+	 * logged-in provider. Extras live only in the controller; the configured chain
+	 * the session persists is untouched. Temporary picks, subagent calls and an
+	 * explicit `--model` stay exactly what was asked for.
+	 */
+	#withFallbackExtras(chain: ConfiguredFallbackChain): ConfiguredFallbackChain {
+		if (EXACT_FALLBACK_CHAIN_ORIGINS.has(chain.origin)) return chain;
+		const entries = [...chain.entries];
+		const seen = new Set(entries);
+		const push = (selector: string): void => {
+			const trimmed = selector.trim();
+			if (!trimmed || seen.has(trimmed)) return;
+			seen.add(trimmed);
+			entries.push(trimmed);
+		};
+		for (const selector of this.settings.get("fallback.models")) push(selector);
+		// Automatic picks stay out of an `enabledModels` allow-list (a deliberate scope) and
+		// out of an explicit `retry.enabled: false` (the user asked for failures to surface).
+		if (
+			this.settings.get("fallback.auto") &&
+			this.settings.get("retry.enabled") !== false &&
+			this.settings.get("enabledModels").length === 0
+		) {
+			// Depends only on configured intent (never the live model), so the chain stays
+			// stable while a fallback is active and when the primary comes back.
+			const excludeProviders = new Set<string>();
+			for (const entry of entries) {
+				const provider = selectorProvider(entry);
+				if (provider) excludeProviders.add(provider);
+			}
+			for (const selector of this.#autoFallbackTail(excludeProviders)) push(selector);
+		}
+		return entries.length === chain.entries.length
+			? chain
+			: { ...chain, entries, appendedFrom: chain.entries.length };
+	}
+
+	#autoFallbackTail(excludeProviders: ReadonlySet<string>): string[] {
+		try {
+			const registry = this.#modelRegistry;
+			return autoFallbackSelectors({
+				available: registry.getAvailable(),
+				hasCredentials: provider => registry.authStorage.hasAuth(provider),
+				excludeProviders,
+				usageOrder: this.settings.getStorage()?.getModelUsageOrder(),
+			});
+		} catch (error) {
+			logger.debug("Automatic model fallback candidates unavailable", {
+				error: error instanceof Error ? error.message : String(error),
+			});
+			return [];
+		}
+	}
+
+	/**
+	 * The default fallback chain the next prompt walks, automatic entries included,
+	 * and the position currently in use.
+	 */
+	getDefaultFallbackChain(): { entries: readonly string[]; activeIndex: number; appendedFrom: number } {
+		const controller = this.#defaultFallbackChain();
+		const entries = [...controller.chain.entries];
+		return {
+			entries,
+			activeIndex: controller.activeIndex,
+			appendedFrom: controller.chain.appendedFrom ?? entries.length,
+		};
+	}
+
 	async #handleManagedAttemptOutcome(outcome: ManagedAttemptOutcome): Promise<ManagedAttemptDecision> {
 		if (outcome.type === "run_terminal") {
 			this.#defaultFallbackChain().resetAttemptBudget();

package/src/session/auth-storage-discovery.ts

@@ -9,6 +9,7 @@
  */
 import { getAgentDbPath, getAgentDir } from "@sayknow-cli/utils";
 import { resolveConfigValue } from "../config/resolve-config-value";
+import type { Settings } from "../config/settings";
 import { resolveAuthBrokerConfig } from "./auth-broker-config";
 import { AuthBrokerClient, AuthStorage, RemoteAuthCredentialStore } from "./auth-storage";
 
@@ -25,7 +26,7 @@ import { AuthBrokerClient, AuthStorage, RemoteAuthCredentialStore } from "./auth
  */
 export async function discoverAuthStorage(agentDir: string = getAgentDir()): Promise<AuthStorage> {
 	const brokerConfig = await resolveAuthBrokerConfig();
-	const credentialRankingMode = resolveCredentialRankingMode();
+	const credentialRankingMode = credentialRankingModeFromEnv();
 	if (brokerConfig) {
 		const client = new AuthBrokerClient({ url: brokerConfig.url, token: brokerConfig.token });
 		const initialResult = await client.fetchSnapshot();
@@ -70,14 +71,28 @@ export async function discoverAuthStorage(agentDir: string = getAgentDir()): Pro
 }
 
 /**
- * Opt-in multi-account credential ranking mode, read from the
- * `SKC_CREDENTIAL_RANKING_MODE` env var. Unset/unknown → `undefined`, leaving
- * {@link AuthStorage}'s default (`balanced`) untouched. `earliest-reset`
- * switches to earliest-expiry-first selection so soon-to-reset tumbling-window
- * quota is drained before it is lost.
+ * Per-machine multi-account ranking override from `SKC_CREDENTIAL_RANKING_MODE`.
+ * Unset/unknown → `undefined`, so the `auth.credentialRankingMode` setting (or
+ * {@link AuthStorage}'s `balanced` default) decides. `earliest-reset` switches to
+ * earliest-expiry-first selection so soon-to-reset tumbling-window quota is
+ * drained before it is lost.
  */
-function resolveCredentialRankingMode(): "balanced" | "earliest-reset" | undefined {
+export function credentialRankingModeFromEnv(): "balanced" | "earliest-reset" | undefined {
 	const raw = process.env.SKC_CREDENTIAL_RANKING_MODE?.trim();
 	if (raw === "balanced" || raw === "earliest-reset") return raw;
 	return undefined;
 }
+
+/**
+ * Apply the `auth.credentialRankingMode` setting to a credential store. The env
+ * var still wins, so a machine that pins a mode keeps it whatever config says.
+ * Returns the mode now in effect.
+ */
+export function applyCredentialRankingModeSetting(
+	storage: Pick<AuthStorage, "setCredentialRankingMode">,
+	settings: Pick<Settings, "get">,
+): "balanced" | "earliest-reset" {
+	const mode = credentialRankingModeFromEnv() ?? settings.get("auth.credentialRankingMode");
+	storage.setCredentialRankingMode(mode);
+	return mode;
+}

package/src/session/auto-fallback.ts

@@ -0,0 +1,59 @@
+import type { Api, Model } from "@sayknow-cli/ai";
+import { defaultModelPerProvider } from "../config/model-resolver";
+
+/**
+ * How many other providers the automatic tail may add. Each entry can cost up to
+ * `fallback.maxAttempts` tries before the chain moves on, so the tail stays short.
+ */
+export const AUTO_FALLBACK_PROVIDER_LIMIT = 3;
+
+/** Provider of a `provider/model[:level]` selector, or undefined for bare aliases. */
+export function selectorProvider(selector: string): string | undefined {
+	const slash = selector.indexOf("/");
+	return slash > 0 ? selector.slice(0, slash) : undefined;
+}
+
+export interface AutoFallbackInput {
+	/** Models whose provider has auth configured (`ModelRegistry.getAvailable()`). */
+	available: readonly Model<Api>[];
+	/** True when the provider has a stored credential or API key (keyless local providers do not count). */
+	hasCredentials: (provider: string) => boolean;
+	/** Providers already in the chain; the tail adds a different provider or nothing. */
+	excludeProviders: ReadonlySet<string>;
+	/** Most-recently-used `provider/id` keys, newest first. */
+	usageOrder?: readonly string[];
+	limit?: number;
+}
+
+/**
+ * One model per other logged-in provider, for the automatic tail of the default
+ * fallback chain. Within a provider the model the user used most recently wins,
+ * then the provider's curated default; a provider with neither is skipped rather
+ * than guessed, because catalog order would land on an old model. Providers used
+ * recently come first, then the rest in curated-default order.
+ */
+export function autoFallbackSelectors(input: AutoFallbackInput): string[] {
+	const limit = input.limit ?? AUTO_FALLBACK_PROVIDER_LIMIT;
+	if (limit <= 0) return [];
+	const availableKeys = new Set(input.available.map(model => `${model.provider}/${model.id}`));
+	const picked = new Map<string, { selector: string; rank: number }>();
+	const eligible = (provider: string): boolean =>
+		!picked.has(provider) && !input.excludeProviders.has(provider) && input.hasCredentials(provider);
+
+	const usageOrder = input.usageOrder ?? [];
+	usageOrder.forEach((key, index) => {
+		const provider = selectorProvider(key);
+		if (!provider || !availableKeys.has(key) || !eligible(provider)) return;
+		picked.set(provider, { selector: key, rank: index });
+	});
+	Object.entries(defaultModelPerProvider).forEach(([provider, modelId], index) => {
+		const key = `${provider}/${modelId}`;
+		if (!availableKeys.has(key) || !eligible(provider)) return;
+		picked.set(provider, { selector: key, rank: usageOrder.length + index });
+	});
+
+	return [...picked.values()]
+		.sort((left, right) => left.rank - right.rank)
+		.slice(0, limit)
+		.map(entry => entry.selector);
+}

package/src/session/fallback-chain-controller.ts

@@ -7,6 +7,11 @@ export interface ConfiguredFallbackChain {
 	origin: string;
 	identity?: string;
 	explicitHead: boolean;
+	/**
+	 * Index of the first entry appended at runtime after the configured intent
+	 * (`fallback.models`, then automatic picks). Absent when nothing was appended.
+	 */
+	appendedFrom?: number;
 }
 
 export interface FallbackFailure {

package/src/session/response-language.ts

@@ -0,0 +1,71 @@
+/**
+ * Which language to answer in, detected from the script of the user's message.
+ *
+ * Long tool-heavy turns drift into English: tool output, logs, skill text and context
+ * summaries are English, and the final report follows them. The system prompt states
+ * the rule once; this adds a one-line reminder at the start of each turn, naming the
+ * language, when the message is clearly written in a non-Latin script. Latin-script
+ * languages (English, Spanish, French, German, …) cannot be told apart by script alone,
+ * so they get no reminder and rely on the system prompt rule.
+ */
+
+export interface DetectedLanguage {
+	/** BCP 47 code. */
+	code: string;
+	/** English name, as used in the reminder. */
+	name: string;
+}
+
+/** Scripts that name one language well enough for a reminder. Kana wins over Han: Japanese mixes both. */
+const SCRIPTS: ReadonlyArray<{ pattern: RegExp; language: DetectedLanguage }> = [
+	{ pattern: /\p{Script=Hangul}/gu, language: { code: "ko", name: "Korean" } },
+	{ pattern: /[\p{Script=Hiragana}\p{Script=Katakana}]/gu, language: { code: "ja", name: "Japanese" } },
+	{ pattern: /\p{Script=Han}/gu, language: { code: "zh", name: "Chinese" } },
+	{ pattern: /\p{Script=Cyrillic}/gu, language: { code: "ru", name: "Russian" } },
+	{ pattern: /\p{Script=Arabic}/gu, language: { code: "ar", name: "Arabic" } },
+	{ pattern: /\p{Script=Hebrew}/gu, language: { code: "he", name: "Hebrew" } },
+	{ pattern: /\p{Script=Thai}/gu, language: { code: "th", name: "Thai" } },
+	{ pattern: /\p{Script=Devanagari}/gu, language: { code: "hi", name: "Hindi" } },
+	{ pattern: /\p{Script=Greek}/gu, language: { code: "el", name: "Greek" } },
+];
+
+/** Code, quoted output and links say nothing about the language the user writes in. */
+function proseOnly(text: string): string {
+	return text
+		.replace(/```[\s\S]*?```/g, " ")
+		.replace(/`[^`\n]*`/g, " ")
+		.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, " ")
+		.replace(/https?:\/\/\S+/g, " ")
+		.split("\n")
+		.filter(line => !/^\s*>/.test(line))
+		.join("\n");
+}
+
+/**
+ * The language of `text` when its prose is clearly in a non-Latin script, else
+ * undefined. "Clearly": at least two characters of the script, and — since one CJK
+ * character carries about a word — at least a quarter as many as Latin letters, so a
+ * pasted English log with one Korean word does not count.
+ */
+export function detectResponseLanguage(text: string): DetectedLanguage | undefined {
+	const prose = proseOnly(text);
+	const latin = prose.match(/\p{Script=Latin}/gu)?.length ?? 0;
+	const kana = prose.match(SCRIPTS[1]!.pattern)?.length ?? 0;
+	for (const { pattern, language } of SCRIPTS) {
+		let count = prose.match(pattern)?.length ?? 0;
+		if (language.code === "zh" && kana > 0) continue;
+		// Japanese needs kana to be told from Chinese; with it, its kanji count too.
+		if (language.code === "ja" && kana > 0) count += prose.match(/\p{Script=Han}/gu)?.length ?? 0;
+		if (count >= 2 && count * 4 >= latin) return language;
+	}
+	return undefined;
+}
+
+/** The per-turn reminder for a detected language. */
+export function buildResponseLanguageReminder(language: DetectedLanguage): string {
+	return [
+		"<system-reminder>",
+		`The user wrote in ${language.name}. Write every user-facing message this turn in ${language.name} — progress notes and the final report after tool work included — unless they asked for another language. Keep code, commands, paths and identifiers as they are.`,
+		"</system-reminder>",
+	].join("\n");
+}

package/src/setup/model-onboarding-guidance.ts

@@ -1,8 +1,11 @@
 import { formatProviderCredentialHint } from "@sayknow-cli/ai/stream";
+import { getOAuthProviders } from "@sayknow-cli/ai/utils/oauth";
+import { formatProviderPresetChoices } from "./provider-onboarding";
 
 export const MODEL_ONBOARDING_API_PROVIDER_COMMAND =
 	"/provider add --compat <openai|anthropic> --provider <id> --base-url <url> --api-key-env <ENV> --model <model>";
-export const MODEL_ONBOARDING_PROVIDER_PRESET_COMMAND = "/provider add --preset <minimax|minimax-cn|glm>";
+/** Built from the bundled preset catalog, so a new preset shows up here without editing copy. */
+export const MODEL_ONBOARDING_PROVIDER_PRESET_COMMAND = `/provider add --preset <${formatProviderPresetChoices()}>`;
 
 export const MODEL_ONBOARDING_SETUP_COMMAND = "skc setup provider";
 export const MODEL_ONBOARDING_OAUTH_COMMAND = "/provider login [provider-id] or /login [provider-id]";
@@ -11,40 +14,52 @@ export const MODEL_ONBOARDING_OAUTH_COMMAND = "/provider login [provider-id] or
  * user learns it exists is from the surfaces where they go to add credentials.
  */
 export const MODEL_ONBOARDING_TYPESAFE_COMMAND = "/provider typesafe";
+/** Where the models tried after a blocked one are shown and edited. */
+export const MODEL_ONBOARDING_FALLBACK_COMMAND = "/fallback";
 
 export function formatModelOnboardingGuidance(): string {
 	return [
 		"Model selection only shows configured providers.",
 		"Assignment targets are DEFAULT plus the SKC role agents: EXECUTOR, ARCHITECT, PLANNER, and CRITIC.",
 		"Legacy model-role aliases are compatibility-only and are not shown as assignment targets.",
+		`OAuth/subscription providers: ${MODEL_ONBOARDING_OAUTH_COMMAND}.`,
 		`Provider presets: ${MODEL_ONBOARDING_PROVIDER_PRESET_COMMAND} (or ${MODEL_ONBOARDING_SETUP_COMMAND} --preset <preset>).`,
 		`API-compatible custom providers: ${MODEL_ONBOARDING_API_PROVIDER_COMMAND}.`,
-		`OAuth/subscription providers: ${MODEL_ONBOARDING_OAUTH_COMMAND}.`,
 		`Typed decisions (not a chat model): ${MODEL_ONBOARDING_TYPESAFE_COMMAND} adds a TypeSafe key.`,
-		"Then run /model to select a configured model or assign it to a target.",
+		`Then run /model to select a configured model or assign it to a target, and ${MODEL_ONBOARDING_FALLBACK_COMMAND} to see what runs when it is blocked.`,
 	].join("\n");
 }
 
 export function formatModelOnboardingInlineHint(): string {
-	return `Add MiniMax/GLM presets with ${MODEL_ONBOARDING_PROVIDER_PRESET_COMMAND}; custom API providers with ${MODEL_ONBOARDING_API_PROVIDER_COMMAND} (or ${MODEL_ONBOARDING_SETUP_COMMAND}); OAuth/subscription with ${MODEL_ONBOARDING_OAUTH_COMMAND}; TypeSafe typed decisions with ${MODEL_ONBOARDING_TYPESAFE_COMMAND}; then run /model for DEFAULT, EXECUTOR, ARCHITECT, PLANNER, and CRITIC.`;
+	return `Log in with ${MODEL_ONBOARDING_OAUTH_COMMAND}; presets with ${MODEL_ONBOARDING_PROVIDER_PRESET_COMMAND}; custom API providers with ${MODEL_ONBOARDING_API_PROVIDER_COMMAND} (or ${MODEL_ONBOARDING_SETUP_COMMAND}); TypeSafe typed decisions with ${MODEL_ONBOARDING_TYPESAFE_COMMAND}; then run /model for DEFAULT, EXECUTOR, ARCHITECT, PLANNER, and CRITIC, and ${MODEL_ONBOARDING_FALLBACK_COMMAND} for what runs when a model is blocked.`;
 }
 
 export function formatNoModelOnboardingError(): string {
 	return `No model selected.\n\n${formatModelOnboardingGuidance()}`;
 }
 
+/**
+ * Missing credentials for the provider the session tried to call. The fix for that
+ * provider comes first; the ways to add a different provider follow as alternatives.
+ */
 export function formatNoCredentialOnboardingError(providerId: string): string {
-	const lines = [
-		`No credentials found for ${providerId}.`,
-		"",
-		`For MiniMax/GLM presets, configure credentials with ${MODEL_ONBOARDING_PROVIDER_PRESET_COMMAND} (or ${MODEL_ONBOARDING_SETUP_COMMAND} --preset <preset>).`,
-		`For custom API-compatible providers, use ${MODEL_ONBOARDING_API_PROVIDER_COMMAND}.`,
-		`For OAuth/subscription providers, use ${MODEL_ONBOARDING_OAUTH_COMMAND} (interactive; not available in headless/print mode).`,
-	];
-	const headlessHint = formatProviderCredentialHint(providerId);
-	if (headlessHint) lines.push(headlessHint);
+	const lines = [`No credentials found for ${providerId}.`, ""];
+	const canLogIn = getOAuthProviders().some(provider => provider.id === providerId);
+	const credentialHint = formatProviderCredentialHint(providerId);
+	if (canLogIn) {
+		lines.push(`Log in to ${providerId}: /login ${providerId} (interactive; not available in headless/print mode).`);
+	}
+	if (credentialHint) lines.push(credentialHint);
+	if (!canLogIn && !credentialHint) {
+		lines.push(`Add an API key for ${providerId} (the env var or apiKey its models.yml entry names).`);
+	}
 	lines.push(
-		"Then run /model to select a configured model or assign it to DEFAULT, EXECUTOR, ARCHITECT, PLANNER, or CRITIC.",
+		"",
+		"Or use another provider:",
+		`- OAuth/subscription: ${MODEL_ONBOARDING_OAUTH_COMMAND} (interactive; not available in headless/print mode).`,
+		`- Presets: ${MODEL_ONBOARDING_PROVIDER_PRESET_COMMAND} (or ${MODEL_ONBOARDING_SETUP_COMMAND} --preset <preset>).`,
+		`- API-compatible: ${MODEL_ONBOARDING_API_PROVIDER_COMMAND}.`,
+		`Then run /model to select a configured model or assign it to DEFAULT, EXECUTOR, ARCHITECT, PLANNER, or CRITIC. With another provider logged in, a blocked model falls back automatically (${MODEL_ONBOARDING_FALLBACK_COMMAND}).`,
 	);
 	return lines.join("\n");
 }

package/src/setup/provider-onboarding.ts

@@ -103,6 +103,11 @@ export function formatProviderPresetList(): string {
 		.join("\n");
 }
 
+/** `minimax|minimax-cn|…` — the preset ids for a `--preset <…>` usage line, in catalog order. */
+export function formatProviderPresetChoices(): string {
+	return PROVIDER_PRESETS.map(preset => preset.id).join("|");
+}
+
 export function parseModelList(values: readonly string[]): string[] {
 	const models = values
 		.flatMap(value => value.split(","))

package/src/slash-commands/builtin-registry.ts

@@ -45,6 +45,7 @@ import { formatSessionImportSummary, runSessionImportCommand } from "../session-
 import { formatModelOnboardingGuidance } from "../setup/model-onboarding-guidance";
 import {
 	addApiCompatibleProvider,
+	formatProviderPresetChoices,
 	formatProviderPresetList,
 	formatProviderSetupResult,
 	parseProviderCompatibility,
@@ -207,6 +208,102 @@ async function updateSessionStar(
 	return commandConsumed();
 }
 
+const FALLBACK_USAGE =
+	"Usage: /fallback [add <model> | remove <number|model> | clear | auto on|off]\n" +
+	"Models listed here run, in order, after the default model when it is blocked (no login, quota, auth or server errors).";
+
+/** Show or edit what runs when the default model is blocked. */
+async function handleFallbackCommand(
+	command: ParsedSlashCommand,
+	runtime: SlashCommandRuntime,
+): Promise<SlashCommandResult> {
+	const { verb, rest } = parseSubcommand(command.args);
+	const added = runtime.settings.get("fallback.models");
+	const save = async (models: string[], message: string): Promise<SlashCommandResult> => {
+		runtime.settings.set("fallback.models", models);
+		await runtime.notifyConfigChanged?.();
+		await runtime.output(`${message}\n\n${formatFallbackChain(runtime)}`);
+		return commandConsumed();
+	};
+	switch (verb) {
+		case "":
+		case "show":
+		case "list":
+			await runtime.output(formatFallbackChain(runtime));
+			return commandConsumed();
+		case "add": {
+			if (!rest) return usage(FALLBACK_USAGE, runtime);
+			const resolution = await resolveModelCommandSelection(runtime, rest);
+			if (!resolution.ok) return usage(resolution.failure.message, runtime);
+			const { model, thinkingLevel } = resolution.selection;
+			const selector = formatModelSelectorValue(`${model.provider}/${model.id}`, thinkingLevel);
+			if (added.includes(selector)) {
+				await runtime.output(`${selector} is already a fallback.\n\n${formatFallbackChain(runtime)}`);
+				return commandConsumed();
+			}
+			return save([...added, selector], `Added fallback: ${selector}`);
+		}
+		case "remove":
+		case "rm": {
+			const index = /^\d+$/.test(rest) ? Number(rest) - 1 : added.indexOf(rest);
+			const target = added[index];
+			if (!rest || target === undefined) {
+				return usage(
+					added.length === 0
+						? "No fallback models are set. Add one with /fallback add <model>."
+						: `Remove by number (1-${added.length}) or exact selector: ${added.join(", ")}`,
+					runtime,
+				);
+			}
+			return save(
+				added.filter((_, position) => position !== index),
+				`Removed fallback: ${target}`,
+			);
+		}
+		case "clear":
+			return save([], "Cleared fallback models.");
+		case "auto": {
+			const value = rest.toLowerCase();
+			if (value !== "on" && value !== "off") return usage("Usage: /fallback auto on|off", runtime);
+			runtime.settings.set("fallback.auto", value === "on");
+			await runtime.notifyConfigChanged?.();
+			await runtime.output(`Automatic fallback ${value}.\n\n${formatFallbackChain(runtime)}`);
+			return commandConsumed();
+		}
+		default:
+			return usage(FALLBACK_USAGE, runtime);
+	}
+}
+
+function formatFallbackChain(runtime: SlashCommandRuntime): string {
+	const auto = runtime.settings.get("fallback.auto");
+	const added = new Set(runtime.settings.get("fallback.models"));
+	const { entries, activeIndex, appendedFrom } = runtime.session.getDefaultFallbackChain();
+	const width = Math.max(0, ...entries.map(entry => entry.length));
+	const lines = [`Model fallback (automatic: ${auto ? "on" : "off"})`];
+	if (entries.length === 0) lines.push("  (no default model)");
+	entries.forEach((entry, index) => {
+		const source = index < appendedFrom ? (index === 0 ? "default" : "chain") : added.has(entry) ? "added" : "auto";
+		const inUse = index === activeIndex ? "  ← in use" : "";
+		lines.push(`  ${index + 1}. ${entry.padEnd(width)}  ${source}${inUse}`);
+	});
+	if (entries.length === 1) {
+		lines.push(
+			auto
+				? "  Nothing to fall back to yet: log in to another provider (/login) or add one with /fallback add <model>."
+				: "  Nothing to fall back to: add a model with /fallback add <model> or turn on /fallback auto on.",
+		);
+	}
+	if (auto && runtime.settings.get("enabledModels").length > 0) {
+		lines.push("  enabledModels restricts this session, so automatic picks are off; added models still apply.");
+	}
+	lines.push(
+		`Each model gets ${runtime.settings.get("fallback.maxAttempts")} tries; a blocked or exhausted account first hands over to the provider's next logged-in account (order: ${runtime.session.modelRegistry.authStorage.getCredentialRankingMode()}).`,
+		"/fallback add <model> · remove <n> · clear · auto on|off",
+	);
+	return lines.join("\n");
+}
+
 function parseProviderSetupSlashArgs(args: string): {
 	preset?: string;
 	compat?: string;
@@ -273,8 +370,7 @@ function parseProviderSetupSlashArgs(args: string): {
 function providerSetupUsage(): string {
 	return [
 		"Provider onboarding",
-		"Presets: /provider add --preset <minimax|minimax-cn|glm> [--force]",
-		"Aliases: /provider add minimax, /provider add minimax-cn, /provider add glm, /provider add zai (writes glm-proxy)",
+		`Presets: /provider add --preset <${formatProviderPresetChoices()}> [--force]`,
 		"API providers: /provider add --compat <openai|anthropic> --provider <id> --base-url <url> --api-key-env <ENV> --model <model> [--force]",
 		`Available presets:\n${formatProviderPresetList()}`,
 		"OAuth/subscription providers: /provider login [provider-id] or /login [provider-id]",
@@ -931,6 +1027,20 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 			runtime.ctx.editor.setText("");
 		},
 	},
+	{
+		name: "fallback",
+		description: "Show or edit the models tried when the default model is blocked",
+		inlineHint: "[add <model> | remove <n> | clear | auto on|off]",
+		acpInputHint: "[add <model> | remove <n> | clear | auto on|off]",
+		subcommands: [
+			{ name: "add", description: "Add a fallback model after the default chain" },
+			{ name: "remove", description: "Remove an added fallback by number or selector" },
+			{ name: "clear", description: "Remove every added fallback" },
+			{ name: "auto", description: "Turn automatic fallback to other logged-in providers on or off" },
+		],
+		allowArgs: true,
+		handle: handleFallbackCommand,
+	},
 	{
 		name: "effort",
 		description: "Show or set model reasoning effort",

package/src/tools/index.ts

@@ -47,6 +47,7 @@ import { FindTool } from "./find";
 import { GithubTool } from "./gh";
 import { IrcTool } from "./irc";
 import { JobTool } from "./job";
+import { LocateTool } from "./locate";
 import { MonitorTool } from "./monitor";
 import { wrapToolWithMetaNotice } from "./output-meta";
 import { ReadTool } from "./read";
@@ -88,6 +89,7 @@ export * from "./gh";
 export * from "./image-gen";
 export * from "./irc";
 export * from "./job";
+export * from "./locate";
 export * from "./monitor";
 export * from "./read";
 export * from "./recipe";
@@ -473,6 +475,7 @@ export const BUILTIN_TOOLS: Record<string, ToolFactory> = {
 	github: GithubTool.createIf,
 	find: s => new FindTool(s),
 	search: s => new SearchTool(s),
+	locate: LocateTool.createIf,
 	lsp: LspTool.createIf,
 	browser: s => new BrowserTool(s),
 	...(isComputerLoadablePlatform() ? { computer: ComputerTool.createIf } : {}),