@gajae-code/ai 0.5.3 → 0.5.4

package/src/provider-models/openai-compat.ts

@@ -2,7 +2,7 @@ import { $env, $inheritedEnv } from "@gajae-code/utils";
 import type { ModelManagerOptions } from "../model-manager";
 import { Effort } from "../model-thinking";
 import { getBundledModels } from "../models";
-import type { Api, Model, ThinkingConfig } from "../types";
+import type { Api, FetchImpl, Model, Provider, ThinkingConfig } from "../types";
 import { isAnthropicOAuthToken, isRecord, toBoolean, toNumber, toPositiveNumber } from "../utils";
 import {
 	fetchOpenAICompatibleModels,
@@ -1414,64 +1414,99 @@ export function cloudflareAiGatewayModelManagerOptions(
 // ---------------------------------------------------------------------------
 // 20. Xiaomi
 // ---------------------------------------------------------------------------
+/** Region codes for Xiaomi Token Plan clusters exposed as separate login providers. */
+export type XiaomiTokenPlanRegion = "sgp" | "ams" | "cn";
 
+/** Configures Xiaomi standard or regional Token Plan OpenAI-compatible model discovery. */
 export interface XiaomiModelManagerConfig {
 	apiKey?: string;
 	baseUrl?: string;
+	fetch?: FetchImpl;
+	providerId?: Provider;
+	tokenPlanRegion?: XiaomiTokenPlanRegion;
+}
+const XIAOMI_TOKEN_PLAN_BASE_URLS: Record<XiaomiTokenPlanRegion, string> = {
+	sgp: "https://token-plan-sgp.xiaomimimo.com/v1",
+	ams: "https://token-plan-ams.xiaomimimo.com/v1",
+	cn: "https://token-plan-cn.xiaomimimo.com/v1",
+};
+
+const XIAOMI_TOKEN_PLAN_FALLBACK_BASE_URLS = [
+	XIAOMI_TOKEN_PLAN_BASE_URLS.sgp,
+	XIAOMI_TOKEN_PLAN_BASE_URLS.ams,
+	XIAOMI_TOKEN_PLAN_BASE_URLS.cn,
+];
+
+function inferXiaomiTokenPlanRegion(providerId: Provider): XiaomiTokenPlanRegion | undefined {
+	if (providerId === "xiaomi-token-plan-sgp") return "sgp";
+	if (providerId === "xiaomi-token-plan-ams") return "ams";
+	if (providerId === "xiaomi-token-plan-cn") return "cn";
+	return undefined;
 }
 
+/** Builds a Xiaomi model manager, preserving Token Plan region provider ids during discovery. */
 export function xiaomiModelManagerOptions(
 	config?: XiaomiModelManagerConfig,
 ): ModelManagerOptions<"openai-completions"> {
 	const apiKey = config?.apiKey;
-	// Xiaomi splits API keys across two backends: standard `sk-` keys hit
-	// api.xiaomimimo.com; "token plan" `tp-` keys hit either the SG or EU
-	// token-plan host. Try SGP first; if discovery fails, retry AMS.
-	const TOKEN_PLAN_SGP_BASE_URL = "https://token-plan-sgp.xiaomimimo.com/v1";
-	const TOKEN_PLAN_AMS_BASE_URL = "https://token-plan-ams.xiaomimimo.com/v1";
-	const defaultBaseUrl = apiKey?.startsWith("tp-") ? TOKEN_PLAN_SGP_BASE_URL : "https://api.xiaomimimo.com/v1";
-	// Token-plan keys always use the TP baseUrl; config?.baseUrl (from catalog)
+	const providerId = config?.providerId ?? "xiaomi";
+	const tokenPlanRegion = config?.tokenPlanRegion ?? inferXiaomiTokenPlanRegion(providerId);
+	const tokenPlanBaseUrls = tokenPlanRegion
+		? [XIAOMI_TOKEN_PLAN_BASE_URLS[tokenPlanRegion]]
+		: XIAOMI_TOKEN_PLAN_FALLBACK_BASE_URLS;
+	const XIAOMI_STANDARD_BASE_URL = "https://api.xiaomimimo.com/v1";
+	const isTokenPlanProvider = tokenPlanRegion !== undefined || providerId.startsWith("xiaomi-token-plan-");
+	const isTokenPlanKey = isTokenPlanProvider || apiKey?.startsWith("tp-");
+	// Token-plan keys always use a TP cluster; config?.baseUrl (from catalog)
 	// would incorrectly pin to the standard endpoint (api.xiaomimimo.com).
-	const baseUrl = apiKey?.startsWith("tp-") ? defaultBaseUrl : (config?.baseUrl ?? defaultBaseUrl);
+	const baseUrl = isTokenPlanKey ? tokenPlanBaseUrls[0] : (config?.baseUrl ?? XIAOMI_STANDARD_BASE_URL);
 	const references = createBundledReferenceMap<"openai-completions">("xiaomi");
+	const throwOnAuthStatus = (response: Response): Error | undefined => {
+		if (response.status === 401 || response.status === 403) {
+			return new Error(`Authentication failed (${response.status}) for ${response.url}`);
+		}
+		return undefined;
+	};
+	const fetchModels = (url: string) =>
+		fetchOpenAICompatibleModels({
+			api: "openai-completions",
+			provider: providerId,
+			baseUrl: url,
+			apiKey,
+			filterModel: (_entry, model) => !model.id.includes("-tts"),
+			mapModel: (entry, defaults) => {
+				const reference = references.get(defaults.id);
+				const model = mapWithBundledReference(entry, defaults, reference);
+				return {
+					...model,
+					api: "openai-completions",
+					provider: providerId,
+					baseUrl: defaults.baseUrl,
+					name: toModelName(entry.display_name, model.name),
+				};
+			},
+			fetch: config?.fetch,
+			throwOnStatus: throwOnAuthStatus,
+		});
 	return {
-		providerId: "xiaomi",
+		providerId,
 		...(apiKey && {
 			fetchDynamicModels: async () => {
-				const sgpResult = await fetchOpenAICompatibleModels({
-					api: "openai-completions",
-					provider: "xiaomi",
-					baseUrl,
-					apiKey,
-					filterModel: (_entry, model) => !model.id.includes("-tts"),
-					mapModel: (entry, defaults) => {
-						const reference = references.get(defaults.id);
-						const model = mapWithBundledReference(entry, defaults, reference);
-						return {
-							...model,
-							name: toModelName(entry.display_name, model.name),
-						};
-					},
-				});
-				if (sgpResult || !apiKey?.startsWith("tp-")) {
-					return sgpResult;
+				if (!isTokenPlanKey) {
+					return fetchModels(baseUrl);
 				}
-				// Token-plan discovery failed with SGP; retry with AMS
-				return fetchOpenAICompatibleModels({
-					api: "openai-completions",
-					provider: "xiaomi",
-					baseUrl: TOKEN_PLAN_AMS_BASE_URL,
-					apiKey,
-					filterModel: (_entry, model) => !model.id.includes("-tts"),
-					mapModel: (entry, defaults) => {
-						const reference = references.get(defaults.id);
-						const model = mapWithBundledReference(entry, defaults, reference);
-						return {
-							...model,
-							name: toModelName(entry.display_name, model.name),
-						};
-					},
-				});
+				for (const url of tokenPlanBaseUrls) {
+					try {
+						const result = await fetchModels(url);
+						if (result) return result;
+					} catch (error) {
+						// Auth errors (401/403) should fail fast, not retry other regions
+						const message = error instanceof Error ? error.message : String(error);
+						if (message.includes("Authentication failed")) throw error;
+						// Network/timeout errors: try next URL
+					}
+				}
+				return null;
 			},
 		}),
 	};
@@ -2166,9 +2201,37 @@ const MODELS_DEV_PROVIDER_DESCRIPTORS_CODING_PLANS: readonly ModelsDevProviderDe
 	// --- zAI ---
 	anthropicMessagesDescriptor("zai-coding-plan", "zai", "https://api.z.ai/api/anthropic"),
 	// --- Xiaomi ---
-	anthropicMessagesDescriptor("xiaomi", "xiaomi", "https://api.xiaomimimo.com/anthropic", {
+	openAiCompletionsDescriptor("xiaomi", "xiaomi", "https://api.xiaomimimo.com/v1", {
+		defaultContextWindow: 262144,
+		defaultMaxTokens: 8192,
+		compat: {
+			supportsStore: false,
+			thinkingFormat: "zai",
+		},
+	}),
+	openAiCompletionsDescriptor("xiaomi", "xiaomi-token-plan-sgp", "https://token-plan-sgp.xiaomimimo.com/v1", {
 		defaultContextWindow: 262144,
 		defaultMaxTokens: 8192,
+		compat: {
+			supportsStore: false,
+			thinkingFormat: "zai",
+		},
+	}),
+	openAiCompletionsDescriptor("xiaomi", "xiaomi-token-plan-ams", "https://token-plan-ams.xiaomimimo.com/v1", {
+		defaultContextWindow: 262144,
+		defaultMaxTokens: 8192,
+		compat: {
+			supportsStore: false,
+			thinkingFormat: "zai",
+		},
+	}),
+	openAiCompletionsDescriptor("xiaomi", "xiaomi-token-plan-cn", "https://token-plan-cn.xiaomimimo.com/v1", {
+		defaultContextWindow: 262144,
+		defaultMaxTokens: 8192,
+		compat: {
+			supportsStore: false,
+			thinkingFormat: "zai",
+		},
 	}),
 	// --- MiniMax Coding Plan ---
 	openAiCompletionsDescriptor("minimax-coding-plan", "minimax-code", "https://api.minimax.io/v1", {

package/src/stream.ts

@@ -194,6 +194,60 @@ export function listProvidersWithEnvKey(): string[] {
 	return Object.keys(serviceProviderMap);
 }
 
+/**
+ * Subscription-style providers whose "subscription" is delivered as an API key
+ * (created at https://opencode.ai/auth), not a separate OAuth/session token.
+ * Used to give OpenCode users an accurate headless auth diagnostic (#755).
+ */
+const OPENCODE_SUBSCRIPTION_PROVIDERS = new Set(["opencode-go", "opencode-zen"]);
+
+/**
+ * Provider-specific credential guidance appended to "no credential" errors.
+ *
+ * Headless GJC has no interactive `/login` TUI, so a bare "No API key" /
+ * "No credentials" error left users — OpenCode Go subscribers especially
+ * (#755) — unsure what signal GJC actually reads. OpenCode subscriptions are
+ * themselves API keys, so this names the env var GJC reads for the provider,
+ * warns that a project `.env` is intentionally ignored for provider
+ * credentials, and points OpenCode users at one-time interactive CLI credential capture.
+ *
+ * Returns an empty string when the provider has no env-var key and no special
+ * handling, so callers can append it unconditionally.
+ */
+export function formatProviderCredentialHint(provider: string): string {
+	const resolver = serviceProviderMap[provider];
+	const envVar = typeof resolver === "string" ? resolver : undefined;
+	const isOpenCodeSubscription = OPENCODE_SUBSCRIPTION_PROVIDERS.has(provider);
+	const parts: string[] = [];
+	if (isOpenCodeSubscription) {
+		parts.push(
+			"OpenCode subscriptions authenticate with an API key (created at https://opencode.ai/auth), not a separate session/OAuth token.",
+		);
+	}
+	if (envVar) {
+		parts.push(
+			`Headless GJC reads this provider's key from ${envVar} (exported in your shell or set in ~/.gjc/.env).`,
+		);
+		parts.push("A value set only in a project .env is intentionally ignored for provider credentials.");
+	}
+	if (isOpenCodeSubscription) {
+		parts.push(
+			`Or run \`gjc auth-broker login ${provider}\` once before headless/print mode to store the key interactively.`,
+		);
+	}
+	return parts.join(" ");
+}
+
+/**
+ * Build an actionable "missing API key" error for a provider, used by the
+ * low-level `stream`/`complete` entry points (#755).
+ */
+export function formatMissingApiKeyError(provider: string): string {
+	const base = `No API key for provider: ${provider}.`;
+	const hint = formatProviderCredentialHint(provider);
+	return hint ? `${base} ${hint}` : base;
+}
+
 export function stream<TApi extends Api>(
 	model: Model<TApi>,
 	context: Context,
@@ -208,7 +262,7 @@ export function stream<TApi extends Api>(
 	if (isGitLabDuoModel(model)) {
 		const apiKey = (options as StreamOptions | undefined)?.apiKey || getEnvApiKey(model.provider);
 		if (!apiKey) {
-			throw new Error(`No API key for provider: ${model.provider}`);
+			throw new Error(formatMissingApiKeyError(model.provider));
 		}
 		return streamGitLabDuo(model, context, {
 			...(options as SimpleStreamOptions | undefined),
@@ -226,7 +280,7 @@ export function stream<TApi extends Api>(
 
 	const apiKey = options?.apiKey || getEnvApiKey(model.provider);
 	if (!apiKey) {
-		throw new Error(`No API key for provider: ${model.provider}`);
+		throw new Error(formatMissingApiKeyError(model.provider));
 	}
 	const providerOptions = { ...options, apiKey };
 
@@ -410,7 +464,7 @@ export function streamSimple<TApi extends Api>(
 
 	const apiKey = options?.apiKey || getEnvApiKey(model.provider);
 	if (!apiKey) {
-		throw new Error(`No API key for provider: ${model.provider}`);
+		throw new Error(formatMissingApiKeyError(model.provider));
 	}
 
 	// GitLab Duo - wraps Anthropic/OpenAI behind GitLab AI Gateway direct access tokens

package/src/types.ts

@@ -141,6 +141,9 @@ export type KnownProvider =
 	| "venice"
 	| "vllm"
 	| "xiaomi"
+	| "xiaomi-token-plan-sgp"
+	| "xiaomi-token-plan-ams"
+	| "xiaomi-token-plan-cn"
 	| "zenmux"
 	| "lm-studio";
 export type Provider = KnownProvider | string;

package/src/utils/discovery/openai-compatible.ts

@@ -1,6 +1,6 @@
 import { UNK_CONTEXT_WINDOW, UNK_MAX_TOKENS } from "@gajae-code/ai";
 import * as z from "zod/v4";
-import type { Api, Model, Provider } from "../../types";
+import type { Api, FetchImpl, Model, Provider } from "../../types";
 
 const MODELS_PATH = "/models";
 
@@ -81,7 +81,9 @@ export interface FetchOpenAICompatibleModelsOptions<TApi extends Api> {
 	/** Optional AbortSignal for request cancellation. */
 	signal?: AbortSignal;
 	/** Optional fetch implementation override for testing/custom runtimes. */
-	fetch?: typeof globalThis.fetch;
+	fetch?: FetchImpl;
+	/** Optional HTTP status predicate for provider-specific hard failures. */
+	throwOnStatus?: (response: Response) => Error | undefined;
 	/**
 	 * Optional post-normalization filter.
 	 * Return false to skip a model.
@@ -133,6 +135,10 @@ export async function fetchOpenAICompatibleModels<TApi extends Api>(
 	}
 
 	if (!response.ok) {
+		const hardFailure = options.throwOnStatus?.(response);
+		if (hardFailure) {
+			throw hardFailure;
+		}
 		return null;
 	}
 

package/src/utils/oauth/index.ts

@@ -140,6 +140,21 @@ const builtInOAuthProviders: OAuthProviderInfo[] = [
 		name: "Xiaomi MiMo",
 		available: true,
 	},
+	{
+		id: "xiaomi-token-plan-sgp",
+		name: "Xiaomi Token Plan (Singapore)",
+		available: true,
+	},
+	{
+		id: "xiaomi-token-plan-ams",
+		name: "Xiaomi Token Plan (Europe)",
+		available: true,
+	},
+	{
+		id: "xiaomi-token-plan-cn",
+		name: "Xiaomi Token Plan (China)",
+		available: true,
+	},
 	{
 		id: "opencode-zen",
 		name: "OpenCode Zen",

package/src/utils/oauth/types.ts

@@ -50,6 +50,9 @@ export type OAuthProvider =
 	| "vllm"
 	| "xai"
 	| "xiaomi"
+	| "xiaomi-token-plan-sgp"
+	| "xiaomi-token-plan-ams"
+	| "xiaomi-token-plan-cn"
 	| "zenmux"
 	| "zai";
 
@@ -78,6 +81,7 @@ export interface OAuthController {
 	onManualCodeInput?(): Promise<string>;
 	onPrompt?(prompt: OAuthPrompt): Promise<string>;
 	signal?: AbortSignal;
+	fetch?: typeof globalThis.fetch;
 }
 
 export interface OAuthLoginCallbacks extends OAuthController {

package/src/utils/oauth/xiaomi.ts

@@ -4,23 +4,44 @@
  * Xiaomi MiMo provides OpenAI-compatible models via
  * https://api.xiaomimimo.com/v1.
  *
- * This is not OAuth - it's a simple API key flow:
- * 1. Open browser to Xiaomi MiMo API key console
- * 2. User copies their API key
- * 3. User pastes the API key into the CLI
+ * 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_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_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);
@@ -28,15 +49,24 @@ function isTokenPlanKey(apiKey: string): boolean {
 
 const VALIDATION_TIMEOUT_MS = 15_000;
 
-async function validateXiaomiApiKey(apiKey: string, signal?: AbortSignal): Promise<void> {
-	// For token-plan keys try SGP first, then AMS as fallback.
-	// Standard sk- keys only hit the one endpoint.
-	const endpoints = isTokenPlanKey(apiKey)
-		? [
-				{ baseUrl: TOKEN_PLAN_SGP_API_BASE_URL, model: TOKEN_PLAN_VALIDATION_MODEL },
-				{ baseUrl: TOKEN_PLAN_AMS_API_BASE_URL, model: TOKEN_PLAN_VALIDATION_MODEL },
-			]
-		: [{ baseUrl: STANDARD_API_BASE_URL, model: STANDARD_VALIDATION_MODEL }];
+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;
 
@@ -47,11 +77,11 @@ async function validateXiaomiApiKey(apiKey: string, signal?: AbortSignal): Promi
 		const timeoutSignal = AbortSignal.timeout(VALIDATION_TIMEOUT_MS);
 		const requestSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
 		try {
-			const response = await fetch(`${ep.baseUrl}/chat/completions`, {
+			const response = await fetchImpl(`${ep.baseUrl}/chat/completions`, {
 				method: "POST",
 				headers: {
 					"Content-Type": "application/json",
-					"x-api-key": apiKey,
+					Authorization: `Bearer ${apiKey}`,
 				},
 				body: JSON.stringify({
 					model: ep.model,
@@ -112,6 +142,7 @@ async function validateXiaomiApiKey(apiKey: string, signal?: AbortSignal): Promi
  * 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`);
 	}
@@ -132,6 +163,37 @@ export async function loginXiaomi(options: OAuthController): Promise<string> {
 	}
 
 	options.onProgress?.(`Validating ${PROVIDER_ID} API key...`);
-	await validateXiaomiApiKey(trimmed, options.signal);
+	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;
 }