@sayknow-cli/ai 0.2.2

package/src/utils/oauth/xai.ts

@@ -0,0 +1,246 @@
+/** xAI OAuth flow (Grok account login). */
+import { OAuthCallbackFlow, type OAuthCallbackFlowOptions } from "./callback-server";
+import { generatePKCE } from "./pkce";
+import type { OAuthController, OAuthCredentials } from "./types";
+
+const XAI_OAUTH_ISSUER = "https://auth.x.ai";
+export const XAI_OAUTH_DISCOVERY_URL = `${XAI_OAUTH_ISSUER}/.well-known/openid-configuration`;
+export const XAI_OAUTH_CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828";
+export const XAI_OAUTH_SCOPE = "openid profile email offline_access grok-cli:access api:access";
+const XAI_OAUTH_CALLBACK_PORT = 56121;
+const XAI_OAUTH_CALLBACK_PATH = "/callback";
+const XAI_OAUTH_REFRESH_SKEW_MS = 2 * 60 * 1000;
+const TOKEN_REQUEST_TIMEOUT_MS = 30_000;
+
+interface XaiDiscovery {
+	authorizationEndpoint: string;
+	tokenEndpoint: string;
+}
+
+interface XaiDiscoveryPayload {
+	authorization_endpoint?: unknown;
+	token_endpoint?: unknown;
+}
+
+interface XaiTokenPayload {
+	access_token?: unknown;
+	refresh_token?: unknown;
+	expires_in?: unknown;
+	id_token?: unknown;
+	token_type?: unknown;
+}
+
+export interface XaiOAuthFlowOptions {
+	extraAuthorizeParams?: Readonly<Record<string, string>>;
+}
+
+export interface XaiOAuthRefreshOptions {
+	signal?: AbortSignal;
+	extraTokenParams?: Readonly<Record<string, string>>;
+}
+
+interface XaiJwtPayload {
+	sub?: unknown;
+	email?: unknown;
+	[key: string]: unknown;
+}
+
+function requestSignal(signal: AbortSignal | undefined): AbortSignal {
+	const timeoutSignal = AbortSignal.timeout(TOKEN_REQUEST_TIMEOUT_MS);
+	return signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+}
+
+function addNonOverridingParams(
+	target: URLSearchParams | Record<string, string>,
+	params: Readonly<Record<string, string>>,
+): void {
+	for (const [key, value] of Object.entries(params)) {
+		if (key.length === 0 || value.length === 0) continue;
+		if (target instanceof URLSearchParams) {
+			if (!target.has(key)) target.set(key, value);
+		} else if (!(key in target)) {
+			target[key] = value;
+		}
+	}
+}
+
+function isAbortSignal(value: AbortSignal | XaiOAuthRefreshOptions | undefined): value is AbortSignal {
+	return value instanceof AbortSignal;
+}
+
+function resolveRefreshOptions(options: AbortSignal | XaiOAuthRefreshOptions | undefined): XaiOAuthRefreshOptions {
+	return isAbortSignal(options) ? { signal: options } : (options ?? {});
+}
+
+function validateXaiEndpoint(rawUrl: string): string {
+	const parsed = new URL(rawUrl);
+	const host = parsed.hostname.toLowerCase();
+	if (parsed.protocol !== "https:" || (host !== "x.ai" && !host.endsWith(".x.ai"))) {
+		throw new Error(`xAI OAuth discovery returned an unexpected endpoint: ${rawUrl}`);
+	}
+	return parsed.toString();
+}
+
+export async function discoverXaiOAuthEndpoints(signal?: AbortSignal): Promise<XaiDiscovery> {
+	const response = await fetch(XAI_OAUTH_DISCOVERY_URL, {
+		headers: { Accept: "application/json" },
+		signal: requestSignal(signal),
+	});
+	if (!response.ok) {
+		throw new Error(`xAI OAuth discovery failed: ${response.status} ${await response.text()}`);
+	}
+
+	const payload = (await response.json()) as XaiDiscoveryPayload;
+	if (typeof payload.authorization_endpoint !== "string" || typeof payload.token_endpoint !== "string") {
+		throw new Error("xAI OAuth discovery response missing authorization/token endpoints");
+	}
+
+	return {
+		authorizationEndpoint: validateXaiEndpoint(payload.authorization_endpoint),
+		tokenEndpoint: validateXaiEndpoint(payload.token_endpoint),
+	};
+}
+
+function decodeJwtPayload(token: string): XaiJwtPayload | undefined {
+	const parts = token.split(".");
+	const payload = parts[1];
+	if (parts.length !== 3 || !payload) return undefined;
+	try {
+		return JSON.parse(Buffer.from(payload, "base64url").toString("utf8")) as XaiJwtPayload;
+	} catch {
+		return undefined;
+	}
+}
+
+function getTokenIdentity(accessToken: string, idToken: string | undefined): { accountId?: string; email?: string } {
+	const payload = (idToken ? decodeJwtPayload(idToken) : undefined) ?? decodeJwtPayload(accessToken);
+	const accountId = typeof payload?.sub === "string" && payload.sub.length > 0 ? payload.sub : undefined;
+	const email =
+		typeof payload?.email === "string" && payload.email.length > 0 ? payload.email.toLowerCase() : undefined;
+	return { accountId, email };
+}
+
+async function postXaiToken(
+	tokenEndpoint: string,
+	body: Record<string, string>,
+	signal?: AbortSignal,
+): Promise<XaiTokenPayload> {
+	const response = await fetch(tokenEndpoint, {
+		method: "POST",
+		headers: {
+			Accept: "application/json",
+			"Content-Type": "application/x-www-form-urlencoded",
+		},
+		body: new URLSearchParams(body).toString(),
+		signal: requestSignal(signal),
+	});
+	if (!response.ok) {
+		throw new Error(`xAI token request failed: ${response.status} ${await response.text()}`);
+	}
+	return (await response.json()) as XaiTokenPayload;
+}
+
+function credentialsFromTokenPayload(payload: XaiTokenPayload, refreshFallback = ""): OAuthCredentials {
+	if (typeof payload.access_token !== "string" || payload.access_token.length === 0) {
+		throw new Error("xAI token response did not include an access token");
+	}
+	const refresh =
+		typeof payload.refresh_token === "string" && payload.refresh_token.length > 0
+			? payload.refresh_token
+			: refreshFallback;
+	if (!refresh) {
+		throw new Error("xAI token response did not include a refresh token");
+	}
+	const expiresIn =
+		typeof payload.expires_in === "number" && Number.isFinite(payload.expires_in) ? payload.expires_in : 3600;
+	const idToken = typeof payload.id_token === "string" ? payload.id_token : undefined;
+	const { accountId, email } = getTokenIdentity(payload.access_token, idToken);
+	return {
+		refresh,
+		access: payload.access_token,
+		expires: Date.now() + expiresIn * 1000 - XAI_OAUTH_REFRESH_SKEW_MS,
+		accountId,
+		email,
+	};
+}
+
+export class XaiOAuthFlow extends OAuthCallbackFlow {
+	#verifier = "";
+	#discovery: XaiDiscovery | undefined;
+	#extraAuthorizeParams: Readonly<Record<string, string>>;
+
+	constructor(ctrl: OAuthController, options: XaiOAuthFlowOptions = {}) {
+		super(ctrl, {
+			preferredPort: XAI_OAUTH_CALLBACK_PORT,
+			callbackPath: XAI_OAUTH_CALLBACK_PATH,
+			callbackHostname: "127.0.0.1",
+			callbackBindHostname: "127.0.0.1",
+			redirectUri: `http://127.0.0.1:${XAI_OAUTH_CALLBACK_PORT}${XAI_OAUTH_CALLBACK_PATH}`,
+		} satisfies OAuthCallbackFlowOptions);
+		this.#extraAuthorizeParams = options.extraAuthorizeParams ?? {};
+	}
+
+	async generateAuthUrl(state: string, redirectUri: string): Promise<{ url: string; instructions?: string }> {
+		const pkce = await generatePKCE();
+		this.#verifier = pkce.verifier;
+		this.#discovery = await discoverXaiOAuthEndpoints(this.ctrl.signal);
+		const params = new URLSearchParams({
+			response_type: "code",
+			client_id: XAI_OAUTH_CLIENT_ID,
+			redirect_uri: redirectUri,
+			scope: XAI_OAUTH_SCOPE,
+			code_challenge: pkce.challenge,
+			code_challenge_method: "S256",
+			state,
+			nonce: crypto.randomUUID(),
+		});
+		addNonOverridingParams(params, this.#extraAuthorizeParams);
+		return {
+			url: `${this.#discovery.authorizationEndpoint}?${params.toString()}`,
+			instructions:
+				"Complete xAI/Grok login in your browser. If the browser cannot reach this machine, paste the final redirect URL or authorization code when prompted.",
+		};
+	}
+
+	async exchangeToken(code: string, _state: string, redirectUri: string): Promise<OAuthCredentials> {
+		if (!this.#verifier) {
+			throw new Error("xAI OAuth PKCE verifier was not initialized");
+		}
+		const discovery = this.#discovery ?? (await discoverXaiOAuthEndpoints(this.ctrl.signal));
+		const tokenPayload = await postXaiToken(
+			discovery.tokenEndpoint,
+			{
+				grant_type: "authorization_code",
+				client_id: XAI_OAUTH_CLIENT_ID,
+				code,
+				redirect_uri: redirectUri,
+				code_verifier: this.#verifier,
+			},
+			this.ctrl.signal,
+		);
+		return credentialsFromTokenPayload(tokenPayload);
+	}
+}
+
+export async function loginXai(ctrl: OAuthController, options?: XaiOAuthFlowOptions): Promise<OAuthCredentials> {
+	return new XaiOAuthFlow(ctrl, options).login();
+}
+
+export async function refreshXaiToken(
+	refreshToken: string,
+	options?: AbortSignal | XaiOAuthRefreshOptions,
+): Promise<OAuthCredentials> {
+	if (!refreshToken) {
+		throw new Error("xAI credentials are expired and do not include a refresh token");
+	}
+	const { signal, extraTokenParams = {} } = resolveRefreshOptions(options);
+	const discovery = await discoverXaiOAuthEndpoints(signal);
+	const body = {
+		grant_type: "refresh_token",
+		client_id: XAI_OAUTH_CLIENT_ID,
+		refresh_token: refreshToken,
+	};
+	addNonOverridingParams(body, extraTokenParams);
+	const tokenPayload = await postXaiToken(discovery.tokenEndpoint, body, signal);
+	return credentialsFromTokenPayload(tokenPayload, refreshToken);
+}

package/src/utils/oauth/xiaomi.ts

@@ -0,0 +1,199 @@
+/**
+ * Xiaomi MiMo login flow.
+ *
+ * Xiaomi MiMo provides OpenAI-compatible models via
+ * https://api.xiaomimimo.com/v1.
+ *
+ * Standard Xiaomi login opens the pay-as-you-go API key console. Token Plan
+ * login opens plan management so users copy the regional `tp-...` key.
+ */
+
+import type { FetchImpl } from "../../types";
+import type { OAuthController } from "./types";
+
+const PROVIDER_ID = "xiaomi";
+const PROVIDER_NAME = "Xiaomi MiMo";
+const STANDARD_AUTH_URL = "https://platform.xiaomimimo.com/#/console/api-keys";
+const TOKEN_PLAN_AUTH_URL = "https://platform.xiaomimimo.com/console/plan-manage";
+const STANDARD_API_BASE_URL = "https://api.xiaomimimo.com/v1";
+const TOKEN_PLAN_KEY_PREFIX = "tp-";
+const STANDARD_VALIDATION_MODEL = "mimo-v2-flash";
+const TOKEN_PLAN_VALIDATION_MODEL = "mimo-v2.5";
+const TOKEN_PLAN_SGP_API_BASE_URL = "https://token-plan-sgp.xiaomimimo.com/v1";
+const TOKEN_PLAN_AMS_API_BASE_URL = "https://token-plan-ams.xiaomimimo.com/v1";
+const TOKEN_PLAN_CN_API_BASE_URL = "https://token-plan-cn.xiaomimimo.com/v1";
+
+/** Region codes accepted by the Xiaomi Token Plan login flow. */
+export type XiaomiTokenPlanRegion = "sgp" | "ams" | "cn";
+
+type XiaomiValidationEndpoint = {
+	baseUrl: string;
+	model: string;
+};
+
+const TOKEN_PLAN_VALIDATION_ENDPOINTS: Record<XiaomiTokenPlanRegion, XiaomiValidationEndpoint> = {
+	sgp: { baseUrl: TOKEN_PLAN_SGP_API_BASE_URL, model: TOKEN_PLAN_VALIDATION_MODEL },
+	ams: { baseUrl: TOKEN_PLAN_AMS_API_BASE_URL, model: TOKEN_PLAN_VALIDATION_MODEL },
+	cn: { baseUrl: TOKEN_PLAN_CN_API_BASE_URL, model: TOKEN_PLAN_VALIDATION_MODEL },
+};
+
+const TOKEN_PLAN_REGION_NAMES: Record<XiaomiTokenPlanRegion, string> = {
+	sgp: "Singapore",
+	ams: "Europe",
+	cn: "China",
+};
+
+function isTokenPlanKey(apiKey: string): boolean {
+	return apiKey.startsWith(TOKEN_PLAN_KEY_PREFIX);
+}
+
+const VALIDATION_TIMEOUT_MS = 15_000;
+
+async function validateXiaomiApiKey(
+	apiKey: string,
+	tokenPlanRegion: XiaomiTokenPlanRegion | undefined,
+	signal?: AbortSignal,
+	fetchOverride?: FetchImpl,
+): Promise<void> {
+	const fetchImpl = fetchOverride ?? fetch;
+	// Region-specific Token Plan logins must validate against the selected
+	// cluster. Generic Xiaomi login keeps the historical SGP → AMS → CN fallback.
+	const endpoints = tokenPlanRegion
+		? [TOKEN_PLAN_VALIDATION_ENDPOINTS[tokenPlanRegion]]
+		: isTokenPlanKey(apiKey)
+			? [
+					TOKEN_PLAN_VALIDATION_ENDPOINTS.sgp,
+					TOKEN_PLAN_VALIDATION_ENDPOINTS.ams,
+					TOKEN_PLAN_VALIDATION_ENDPOINTS.cn,
+				]
+			: [{ baseUrl: STANDARD_API_BASE_URL, model: STANDARD_VALIDATION_MODEL }];
+
+	let lastError: Error | null = null;
+
+	for (const ep of endpoints) {
+		// Fresh timeout per endpoint so SGP→AMS fallback works after a regional
+		// timeout: a shared AbortSignal.timeout would stay aborted and instantly
+		// abort the AMS fetch.
+		const timeoutSignal = AbortSignal.timeout(VALIDATION_TIMEOUT_MS);
+		const requestSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+		try {
+			const response = await fetchImpl(`${ep.baseUrl}/chat/completions`, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					Authorization: `Bearer ${apiKey}`,
+				},
+				body: JSON.stringify({
+					model: ep.model,
+					max_tokens: 1,
+					messages: [{ role: "user", content: "ping" }],
+				}),
+				signal: requestSignal,
+			});
+
+			if (response.ok) {
+				return;
+			}
+
+			// 401 means this endpoint didn't accept the key; try the next one
+			if (response.status === 401) {
+				let details = "";
+				try {
+					details = (await response.text()).trim();
+				} catch {
+					// ignore body parse errors, status is enough
+				}
+				lastError = new Error(
+					details
+						? `${PROVIDER_NAME} API key validation failed (${response.status}): ${details}`
+						: `${PROVIDER_NAME} API key validation failed (${response.status})`,
+				);
+				continue;
+			}
+
+			// Non-auth errors are real failures
+			let details = "";
+			try {
+				details = (await response.text()).trim();
+			} catch {
+				// ignore body parse errors, status is enough
+			}
+			const message = details
+				? `${PROVIDER_NAME} API key validation failed (${response.status}): ${details}`
+				: `${PROVIDER_NAME} API key validation failed (${response.status})`;
+			throw new Error(message);
+		} catch (e) {
+			// Only re-throw AbortError when the caller explicitly cancelled.
+			// Timeout aborts (from AbortSignal.timeout) should fall through to
+			// the next endpoint so SGP→AMS fallback works during regional outages.
+			if (e instanceof DOMException && e.name === "AbortError" && signal?.aborted) {
+				throw e;
+			}
+			lastError = e instanceof Error ? e : new Error(String(e));
+		}
+	}
+	throw lastError ?? new Error(`${PROVIDER_NAME} API key validation failed`);
+}
+
+/**
+ * Login to Xiaomi MiMo.
+ *
+ * Opens browser to API keys page, prompts user to paste their API key.
+ * Returns the API key directly (not OAuthCredentials - this isn't OAuth).
+ */
+export async function loginXiaomi(options: OAuthController): Promise<string> {
+	const fetchImpl = options.fetch ?? fetch;
+	if (!options.onPrompt) {
+		throw new Error(`${PROVIDER_NAME} login requires onPrompt callback`);
+	}
+	options.onAuth?.({
+		url: STANDARD_AUTH_URL,
+		instructions: "Copy your API key from the Xiaomi MiMo console",
+	});
+	const apiKey = await options.onPrompt({
+		message: "Paste your Xiaomi API key (sk-... or token-plan tp-...)",
+		placeholder: "sk-... or tp-...",
+	});
+	if (options.signal?.aborted) {
+		throw new Error("Login cancelled");
+	}
+	const trimmed = apiKey.trim();
+	if (!trimmed) {
+		throw new Error("API key is required");
+	}
+
+	options.onProgress?.(`Validating ${PROVIDER_ID} API key...`);
+	await validateXiaomiApiKey(trimmed, undefined, options.signal, fetchImpl);
+	return trimmed;
+}
+
+/**
+ * Login to a regional Xiaomi Token Plan endpoint.
+ *
+ * Prompts for a token-plan API key and validates it against the selected region.
+ */
+export async function loginXiaomiTokenPlan(options: OAuthController, region: XiaomiTokenPlanRegion): Promise<string> {
+	const fetchImpl = options.fetch ?? fetch;
+	if (!options.onPrompt) {
+		throw new Error(`Xiaomi Token Plan (${TOKEN_PLAN_REGION_NAMES[region]}) login requires onPrompt callback`);
+	}
+	options.onAuth?.({
+		url: TOKEN_PLAN_AUTH_URL,
+		instructions: `Copy your token-plan API key for the ${TOKEN_PLAN_REGION_NAMES[region]} region`,
+	});
+	const apiKey = await options.onPrompt({
+		message: `Paste your Xiaomi Token Plan ${TOKEN_PLAN_REGION_NAMES[region]} API key (tp-...)`,
+		placeholder: "tp-...",
+	});
+	if (options.signal?.aborted) {
+		throw new Error("Login cancelled");
+	}
+	const trimmed = apiKey.trim();
+	if (!trimmed) {
+		throw new Error("API key is required");
+	}
+
+	options.onProgress?.(`Validating Xiaomi Token Plan (${TOKEN_PLAN_REGION_NAMES[region]}) API key...`);
+	await validateXiaomiApiKey(trimmed, region, options.signal, fetchImpl);
+	return trimmed;
+}

package/src/utils/oauth/zai.ts

@@ -0,0 +1,60 @@
+/**
+ * Z.AI login flow.
+ *
+ * Z.AI is a platform that provides access to GLM models through an OpenAI-compatible API.
+ * API docs: https://docs.z.ai/guides/overview/quick-start
+ *
+ * This is not OAuth - it's a simple API key flow:
+ * 1. User gets their API key from https://z.ai/settings/api-keys
+ * 2. User pastes the API key into the CLI
+ */
+
+import { validateOpenAICompatibleApiKey } from "./api-key-validation";
+import type { OAuthController } from "./types";
+
+const AUTH_URL = "https://z.ai/manage-apikey/apikey-list";
+const API_BASE_URL = "https://api.z.ai/api/coding/paas/v4";
+const VALIDATION_MODEL = "glm-4.7";
+
+/**
+ * Login to Z.AI.
+ *
+ * Opens browser to API keys page, prompts user to paste their API key.
+ * Returns the API key directly (not OAuthCredentials - this isn't OAuth).
+ */
+export async function loginZai(options: OAuthController): Promise<string> {
+	if (!options.onPrompt) {
+		throw new Error("Z.AI login requires onPrompt callback");
+	}
+
+	// Open browser to API keys page
+	options.onAuth?.({
+		url: AUTH_URL,
+		instructions: "Copy your API key from the dashboard",
+	});
+
+	// Prompt user to paste their API key
+	const apiKey = await options.onPrompt({
+		message: "Paste your Z.AI API key",
+		placeholder: "sk-...",
+	});
+
+	if (options.signal?.aborted) {
+		throw new Error("Login cancelled");
+	}
+
+	const trimmed = apiKey.trim();
+	if (!trimmed) {
+		throw new Error("API key is required");
+	}
+
+	options.onProgress?.("Validating API key...");
+	await validateOpenAICompatibleApiKey({
+		provider: "Z.AI",
+		apiKey: trimmed,
+		baseUrl: API_BASE_URL,
+		model: VALIDATION_MODEL,
+		signal: options.signal,
+	});
+	return trimmed;
+}

package/src/utils/oauth/zenmux.ts

@@ -0,0 +1,15 @@
+/** ZenMux login flow (API key paste, validated via /models). */
+import { createApiKeyLogin } from "./api-key-login";
+
+export const loginZenMux = createApiKeyLogin({
+	providerLabel: "ZenMux",
+	authUrl: "https://zenmux.ai/settings/keys",
+	instructions: "Create or copy your ZenMux API key",
+	promptMessage: "Paste your ZenMux API key",
+	placeholder: "sk-...",
+	validation: {
+		kind: "models-endpoint",
+		provider: "ZenMux",
+		modelsUrl: "https://zenmux.ai/api/v1/models",
+	},
+});

package/src/utils/overflow.ts

@@ -0,0 +1,137 @@
+import type { AssistantMessage } from "../types";
+
+/**
+ * Regex patterns to detect context overflow errors from different providers.
+ *
+ * These patterns match error messages returned when the input exceeds
+ * the model's context window.
+ *
+ * Provider-specific patterns (with example error messages):
+ *
+ * - Anthropic: "prompt is too long: 213462 tokens > 200000 maximum"
+ * - OpenAI: "Your input exceeds the context window of this model"
+ * - Google: "The input token count (1196265) exceeds the maximum number of tokens allowed (1048575)"
+ * - xAI: "This model's maximum prompt length is 131072 but the request contains 537812 tokens"
+ * - Groq: "Please reduce the length of the messages or completion"
+ * - OpenRouter: "This endpoint's maximum context length is X tokens. However, you requested about Y tokens"
+ * - llama.cpp: "the request exceeds the available context size, try increasing it"
+ * - LM Studio: "tokens to keep from the initial prompt is greater than the context length"
+ * - GitHub Copilot: "prompt token count of X exceeds the limit of Y"
+ * - MiniMax: "invalid params, context window exceeds limit"
+ * - Kimi For Coding: "Your request exceeded model token limit: X (requested: Y)"
+ * - Anthropic 413: "request_too_large" / "Request exceeds the maximum size" (payload too large)
+ * - HTTP 413 variants: "Payload Too Large" / "Request Entity Too Large"
+ * - z.ai / GLM: Returns finish_reason: "model_context_window_exceeded" mapped to error message
+ * - z.ai: Does NOT error, accepts overflow silently - handled via usage.input > contextWindow
+ * - Ollama: Silently truncates input - not detectable via error message
+ */
+const OVERFLOW_PATTERNS = [
+	/prompt is too long/i, // Anthropic
+	/input is too long for requested model/i, // Amazon Bedrock
+	/exceeds the context window/i, // OpenAI (Completions & Responses API)
+	/input token count.*exceeds the maximum/i, // Google (Gemini)
+	/maximum prompt length is \d+/i, // xAI (Grok)
+	/reduce the length of the messages/i, // Groq
+	/maximum context length is \d+ tokens/i, // OpenRouter (all backends)
+	/exceeds the limit of \d+/i, // GitHub Copilot
+	/exceeds the available context size/i, // llama.cpp server
+	/requested tokens?.*exceed.*context (window|length|size)/i, // llama.cpp / OpenAI-compatible local servers
+	/context (window|length|size).*(exceeded|overflow|too small)/i, // Generic local server variants
+	/(prompt|input).*(too long|too large).*(context|n_ctx)/i, // llama.cpp phrasing variants
+	/requested tokens?.*(exceeds?|greater than).*(n_ctx|context)/i, // llama.cpp n_ctx variants
+	/greater than the context length/i, // LM Studio
+	/context window exceeds limit/i, // MiniMax
+	/exceeded model token limit/i, // Kimi For Coding
+	/context[_ ]length[_ ]exceeded/i, // Generic fallback
+	/too many tokens/i, // Generic fallback
+	/token limit exceeded/i, // Generic fallback
+	/request_too_large/i, // Anthropic 413 (request body too large)
+	/request exceeds the maximum size/i, // Anthropic 413 variant
+	/payload too large/i, // Generic HTTP 413 variant
+	/entity too large/i, // Generic HTTP 413 variant
+	/\b413\b.*\b(request|payload|entity)\b.*\btoo large\b/i, // "413 Request Entity Too Large" variants
+	/model_context_window_exceeded/i, // z.ai non-standard finish_reason surfaced as error text
+];
+/**
+ * Check if an assistant message represents a context overflow error.
+ *
+ * This handles two cases:
+ * 1. Error-based overflow: Most providers return stopReason "error" with a
+ *    specific error message pattern.
+ * 2. Silent overflow: Some providers accept overflow requests and return
+ *    successfully. For these, we check if usage.input exceeds the context window.
+ *
+ * ## Reliability by Provider
+ *
+ * **Reliable detection (returns error with detectable message):**
+ * - Anthropic: "prompt is too long: X tokens > Y maximum"
+ * - OpenAI (Completions & Responses): "exceeds the context window"
+ * - Google Gemini: "input token count exceeds the maximum"
+ * - xAI (Grok): "maximum prompt length is X but request contains Y"
+ * - Groq: "reduce the length of the messages"
+ * - Cerebras: 400/413 status code (no body)
+ * - Mistral: 400/413 status code (no body)
+ * - HTTP 413 payload/entity-too-large variants
+ * - OpenRouter (all backends): "maximum context length is X tokens"
+ * - llama.cpp: "exceeds the available context size"
+ * - LM Studio: "greater than the context length"
+ * - Kimi For Coding: "exceeded model token limit: X (requested: Y)"
+ * - Anthropic 413: "request_too_large" (request body exceeds size limit)
+ * - HTTP 413: "Payload Too Large" / "Request Entity Too Large"
+ *
+ * **Unreliable detection:**
+ * - z.ai: Sometimes accepts overflow silently (detectable via usage.input > contextWindow),
+ *   sometimes returns rate limit errors. Pass contextWindow param to detect silent overflow.
+ * - Ollama: Silently truncates input without error. Cannot be detected via this function.
+ *   The response will have usage.input < expected, but we don't know the expected value.
+ *
+ * ## Custom Providers
+ *
+ * If you've added custom models via settings.json, this function may not detect
+ * overflow errors from those providers. To add support:
+ *
+ * 1. Send a request that exceeds the model's context window
+ * 2. Check the errorMessage in the response
+ * 3. Create a regex pattern that matches the error
+ * 4. The pattern should be added to OVERFLOW_PATTERNS in this file, or
+ *    check the errorMessage yourself before calling this function
+ *
+ * @param message - The assistant message to check
+ * @param contextWindow - Optional context window size for detecting silent overflow (z.ai)
+ * @returns true if the message indicates a context overflow
+ */
+export function isContextOverflow(message: AssistantMessage, contextWindow?: number): boolean {
+	// Case 1: Check error message patterns
+	if (message.stopReason === "error" && message.errorMessage) {
+		// Check known patterns
+		if (OVERFLOW_PATTERNS.some(p => p.test(message.errorMessage!))) {
+			return true;
+		}
+
+		// Cerebras and Mistral return 400/413 with no body for context overflow.
+		// Proxy providers (e.g. api.synthetic.new) wrap upstream 400/413 no-body
+		// responses in a JSON envelope, so the status code phrase may appear
+		// anywhere in the message rather than at its start.
+		// Note: 429 is rate limiting (requests/tokens per time), NOT context overflow
+		if (/\b4(00|13)\s*(status code)?\s*\(no body\)/i.test(message.errorMessage)) {
+			return true;
+		}
+	}
+
+	// Case 2: Usage-based overflow (silent or provider-specific)
+	if (contextWindow) {
+		const inputTokens = message.usage.input + message.usage.cacheRead + message.usage.cacheWrite;
+		if (inputTokens > contextWindow) {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+/**
+ * Get the overflow patterns for testing purposes.
+ */
+export function getOverflowPatterns(): RegExp[] {
+	return [...OVERFLOW_PATTERNS];
+}