@linxiraos/pi-ai 1.0.0

package/src/registry/kilo.ts

@@ -0,0 +1,114 @@
+import * as AIError from "../error";
+import type { OAuthController, OAuthCredentials } from "./oauth/types";
+import type { ProviderDefinition } from "./types";
+
+const KILO_DEVICE_AUTH_BASE_URL = "https://api.kilo.ai/api/device-auth";
+const POLL_INTERVAL_MS = 5000;
+const ONE_YEAR_MS = 365 * 24 * 60 * 60 * 1000;
+
+interface KiloDeviceAuthCodeResponse {
+	code?: string;
+	verificationUrl?: string;
+	expiresIn?: number;
+}
+
+interface KiloDeviceAuthPollResponse {
+	status?: string;
+	token?: string;
+}
+
+export async function loginKilo(callbacks: OAuthController): Promise<OAuthCredentials> {
+	const fetchImpl = callbacks.fetch ?? fetch;
+	const initiateResponse = await fetchImpl(`${KILO_DEVICE_AUTH_BASE_URL}/codes`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+	});
+
+	if (!initiateResponse.ok) {
+		if (initiateResponse.status === 429) {
+			throw new AIError.OAuthError("Too many pending authorization requests. Please try again later.", {
+				kind: "polling",
+				provider: "kilo",
+				status: initiateResponse.status,
+			});
+		}
+		throw new AIError.OAuthError(`Failed to initiate device authorization: ${initiateResponse.status}`, {
+			kind: "device-auth",
+			provider: "kilo",
+			status: initiateResponse.status,
+		});
+	}
+
+	const initiateData = (await initiateResponse.json()) as KiloDeviceAuthCodeResponse;
+	const userCode = initiateData.code;
+	const verificationUrl = initiateData.verificationUrl;
+	const expiresInSeconds = initiateData.expiresIn;
+	if (!userCode || !verificationUrl || typeof expiresInSeconds !== "number" || expiresInSeconds <= 0) {
+		throw new AIError.OAuthError("Kilo device authorization response missing required fields", {
+			kind: "validation",
+			provider: "kilo",
+		});
+	}
+
+	callbacks.onAuth?.({
+		url: verificationUrl,
+		instructions: `Enter code: ${userCode}`,
+	});
+
+	const deadline = Date.now() + expiresInSeconds * 1000;
+	while (Date.now() < deadline) {
+		if (callbacks.signal?.aborted) {
+			throw new AIError.LoginCancelledError();
+		}
+
+		const pollResponse = await fetchImpl(`${KILO_DEVICE_AUTH_BASE_URL}/codes/${encodeURIComponent(userCode)}`);
+		if (pollResponse.status === 202) {
+			await Bun.sleep(POLL_INTERVAL_MS);
+			continue;
+		}
+		if (pollResponse.status === 403) {
+			throw new AIError.OAuthError("Authorization was denied", { kind: "device-auth", provider: "kilo" });
+		}
+		if (pollResponse.status === 410) {
+			throw new AIError.OAuthError("Authorization code expired. Please try again.", {
+				kind: "device-auth",
+				provider: "kilo",
+			});
+		}
+		if (!pollResponse.ok) {
+			throw new AIError.OAuthError(`Failed to poll device authorization: ${pollResponse.status}`, {
+				kind: "polling",
+				provider: "kilo",
+				status: pollResponse.status,
+			});
+		}
+
+		const pollData = (await pollResponse.json()) as KiloDeviceAuthPollResponse;
+		if (pollData.status === "approved" && pollData.token) {
+			return {
+				refresh: "",
+				access: pollData.token,
+				expires: Date.now() + ONE_YEAR_MS,
+			};
+		}
+		if (pollData.status === "denied") {
+			throw new AIError.OAuthError("Authorization was denied", { kind: "device-auth", provider: "kilo" });
+		}
+		if (pollData.status === "expired") {
+			throw new AIError.OAuthError("Authorization code expired. Please try again.", {
+				kind: "device-auth",
+				provider: "kilo",
+			});
+		}
+
+		await Bun.sleep(POLL_INTERVAL_MS);
+	}
+
+	throw new AIError.OAuthError("Authentication timed out. Please try again.", { kind: "timeout", provider: "kilo" });
+}
+
+export const kiloProvider = {
+	id: "kilo",
+	name: "Kilo Gateway",
+	login: loginKilo,
+} as const satisfies ProviderDefinition;

package/src/registry/kimi-code.ts

@@ -0,0 +1,17 @@
+import type { OAuthCredentials, OAuthLoginCallbacks } from "./oauth/types";
+import type { ProviderDefinition } from "./types";
+
+export const kimiCodeProvider = {
+	id: "kimi-code",
+	name: "Kimi Code",
+	login: async (cb: OAuthLoginCallbacks) => {
+		// Lazy import: keep heavy OAuth flow modules out of the eager registry graph.
+		const { loginKimi } = await import("./oauth/kimi");
+		return loginKimi(cb);
+	},
+	refreshToken: async (credentials: OAuthCredentials) => {
+		// Lazy import: keep heavy OAuth flow modules out of the eager registry graph.
+		const { refreshKimiToken } = await import("./oauth/kimi");
+		return refreshKimiToken(credentials.refresh);
+	},
+} as const satisfies ProviderDefinition;

package/src/registry/litellm.ts

@@ -0,0 +1,45 @@
+import * as AIError from "../error";
+import type { OAuthController, OAuthLoginCallbacks } from "./oauth/types";
+import type { ProviderDefinition } from "./types";
+
+const AUTH_URL = "https://docs.litellm.ai/docs/proxy/deploy";
+
+/**
+ * Login to LiteLLM.
+ *
+ * Opens browser to LiteLLM setup docs, prompts user to paste their API key.
+ * Returns the API key directly (not OAuthCredentials - this isn't OAuth).
+ */
+export async function loginLiteLLM(options: OAuthController): Promise<string> {
+	if (!options.onPrompt) {
+		throw new AIError.OnPromptRequiredError("LiteLLM");
+	}
+
+	options.onAuth?.({
+		url: AUTH_URL,
+		instructions:
+			"Run LiteLLM proxy (default http://localhost:4000/v1; set LITELLM_BASE_URL to customize it), then copy your master key or virtual key",
+	});
+
+	const apiKey = await options.onPrompt({
+		message: "Paste your LiteLLM API key (master key or virtual key)",
+		placeholder: "sk-...",
+	});
+
+	if (options.signal?.aborted) {
+		throw new AIError.LoginCancelledError();
+	}
+
+	const trimmed = apiKey.trim();
+	if (!trimmed) {
+		throw new AIError.ApiKeyRequiredError();
+	}
+
+	return trimmed;
+}
+
+export const litellmProvider = {
+	id: "litellm",
+	name: "LiteLLM",
+	login: (cb: OAuthLoginCallbacks) => loginLiteLLM(cb),
+} as const satisfies ProviderDefinition;

package/src/registry/llama-cpp.ts

@@ -0,0 +1,35 @@
+import * as AIError from "../error";
+import type { OAuthController, OAuthLoginCallbacks } from "./oauth/types";
+import type { ProviderDefinition } from "./types";
+
+const PROVIDER_ID = "llama.cpp";
+const AUTH_URL = "https://github.com/ggml-org/llama.cpp#quick-start";
+const DEFAULT_LOCAL_BASE_URL = "http://127.0.0.1:8080";
+const DEFAULT_LOCAL_TOKEN = "llama-cpp-local";
+
+export async function loginLlamaCpp(options: OAuthController): Promise<string> {
+	if (!options.onPrompt) {
+		throw new AIError.OnPromptRequiredError(PROVIDER_ID);
+	}
+	options.onAuth?.({
+		url: AUTH_URL,
+		instructions: `Paste your llama.cpp API key if your server requires auth. Leave empty for local no-auth mode (default base URL: ${DEFAULT_LOCAL_BASE_URL}; set LLAMA_CPP_BASE_URL to customize).`,
+	});
+	const apiKey = await options.onPrompt({
+		message: "Paste your llama.cpp API key (optional for local no-auth)",
+		placeholder: DEFAULT_LOCAL_TOKEN,
+		allowEmpty: true,
+	});
+	if (options.signal?.aborted) {
+		throw new AIError.LoginCancelledError();
+	}
+	const trimmed = apiKey.trim();
+	return trimmed || DEFAULT_LOCAL_TOKEN;
+}
+
+export const llamaCppProvider = {
+	id: PROVIDER_ID,
+	name: "llama.cpp (Local OpenAI-compatible)",
+	envKeys: "LLAMA_CPP_API_KEY",
+	login: (cb: OAuthLoginCallbacks) => loginLlamaCpp(cb),
+} as const satisfies ProviderDefinition;

package/src/registry/lm-studio.ts

@@ -0,0 +1,31 @@
+import * as AIError from "../error";
+import type { OAuthController, OAuthLoginCallbacks } from "./oauth/types";
+import type { ProviderDefinition } from "./types";
+
+const PROVIDER_ID = "lm-studio";
+export const DEFAULT_LOCAL_TOKEN = "lm-studio-local";
+
+export async function loginLmStudio(options: OAuthController): Promise<string> {
+	if (!options.onPrompt) {
+		throw new AIError.OnPromptRequiredError(PROVIDER_ID);
+	}
+
+	const apiKey = await options.onPrompt({
+		message: "Optional: Paste LM Studio API key (to customize endpoint URL, set LM_STUDIO_BASE_URL env var)",
+		placeholder: DEFAULT_LOCAL_TOKEN,
+		allowEmpty: true,
+	});
+
+	if (options.signal?.aborted) {
+		throw new AIError.LoginCancelledError();
+	}
+
+	const trimmed = apiKey.trim();
+	return trimmed || DEFAULT_LOCAL_TOKEN;
+}
+
+export const lmStudioProvider = {
+	id: "lm-studio",
+	name: "LM Studio (Local OpenAI-compatible)",
+	login: (cb: OAuthLoginCallbacks) => loginLmStudio(cb),
+} as const satisfies ProviderDefinition;

package/src/registry/meta.ts

@@ -0,0 +1,22 @@
+import { createApiKeyLogin } from "./api-key-login";
+import type { OAuthLoginCallbacks } from "./oauth/types";
+import type { ProviderDefinition } from "./types";
+
+export const loginMeta = createApiKeyLogin({
+	providerLabel: "Meta Model API",
+	authUrl: "https://developer.meta.com/ai/",
+	instructions: "Create or copy your key from the Meta Model API dashboard",
+	promptMessage: "Paste your Meta Model API key",
+	placeholder: "Model API key",
+	validation: {
+		kind: "models-endpoint",
+		provider: "Meta Model API",
+		modelsUrl: "https://api.meta.ai/v1/models",
+	},
+});
+
+export const metaProvider = {
+	id: "meta",
+	name: "Meta Model API",
+	login: (cb: OAuthLoginCallbacks) => loginMeta(cb),
+} as const satisfies ProviderDefinition;

package/src/registry/minimax-code-cn.ts

@@ -0,0 +1,12 @@
+import type { OAuthLoginCallbacks } from "./oauth/types";
+import type { ProviderDefinition } from "./types";
+
+export const minimaxCodeCnProvider = {
+	id: "minimax-code-cn",
+	name: "MiniMax Token Plan (China)",
+	login: async (cb: OAuthLoginCallbacks) => {
+		// Lazy import: keep heavy OAuth flow modules out of the eager registry graph.
+		const { loginMiniMaxCodeCn } = await import("./oauth/minimax-code");
+		return loginMiniMaxCodeCn(cb);
+	},
+} as const satisfies ProviderDefinition;

package/src/registry/minimax-code.ts

@@ -0,0 +1,12 @@
+import type { OAuthLoginCallbacks } from "./oauth/types";
+import type { ProviderDefinition } from "./types";
+
+export const minimaxCodeProvider = {
+	id: "minimax-code",
+	name: "MiniMax Token Plan (International)",
+	login: async (cb: OAuthLoginCallbacks) => {
+		// Lazy import: keep heavy OAuth flow modules out of the eager registry graph.
+		const { loginMiniMaxCode } = await import("./oauth/minimax-code");
+		return loginMiniMaxCode(cb);
+	},
+} as const satisfies ProviderDefinition;

package/src/registry/minimax.ts

@@ -0,0 +1,6 @@
+import type { ProviderDefinition } from "./types";
+
+export const minimaxProvider = {
+	id: "minimax",
+	name: "MiniMax",
+} as const satisfies ProviderDefinition;

package/src/registry/mistral.ts

@@ -0,0 +1,6 @@
+import type { ProviderDefinition } from "./types";
+
+export const mistralProvider = {
+	id: "mistral",
+	name: "Mistral",
+} as const satisfies ProviderDefinition;

package/src/registry/moonshot.ts

@@ -0,0 +1,28 @@
+import { $env } from "@linxiraos/pi-utils";
+import { createApiKeyLogin } from "./api-key-login";
+import type { OAuthLoginCallbacks } from "./oauth/types";
+import type { ProviderDefinition } from "./types";
+
+function resolveMoonshotModelsUrl(): string {
+	const baseUrl = $env.MOONSHOT_BASE_URL?.trim() || "https://api.moonshot.ai/v1";
+	return `${baseUrl.replace(/\/+$/, "")}/models`;
+}
+
+export const loginMoonshot = createApiKeyLogin({
+	providerLabel: "Moonshot",
+	authUrl: "https://platform.moonshot.ai/console/api-keys",
+	instructions: "Copy your API key from the Moonshot dashboard",
+	promptMessage: "Paste your Moonshot API key",
+	placeholder: "sk-...",
+	validation: {
+		kind: "models-endpoint",
+		provider: "moonshot",
+		modelsUrl: resolveMoonshotModelsUrl,
+	},
+});
+
+export const moonshotProvider = {
+	id: "moonshot",
+	name: "Moonshot (Kimi API)",
+	login: (cb: OAuthLoginCallbacks) => loginMoonshot(cb),
+} as const satisfies ProviderDefinition;

package/src/registry/nanogpt.ts

@@ -0,0 +1,22 @@
+import { createApiKeyLogin } from "./api-key-login";
+import type { OAuthLoginCallbacks } from "./oauth/types";
+import type { ProviderDefinition } from "./types";
+
+export const loginNanoGPT = createApiKeyLogin({
+	providerLabel: "NanoGPT",
+	authUrl: "https://nano-gpt.com/api",
+	instructions: "Create or copy your NanoGPT API key",
+	promptMessage: "Paste your NanoGPT API key",
+	placeholder: "sk-...",
+	validation: {
+		kind: "models-endpoint",
+		provider: "NanoGPT",
+		modelsUrl: "https://nano-gpt.com/api/v1/models",
+	},
+});
+
+export const nanogptProvider = {
+	id: "nanogpt",
+	name: "NanoGPT",
+	login: (cb: OAuthLoginCallbacks) => loginNanoGPT(cb),
+} as const satisfies ProviderDefinition;

package/src/registry/novita.ts

@@ -0,0 +1,25 @@
+import { createApiKeyLogin } from "./api-key-login";
+import type { ProviderDefinition } from "./types";
+
+export const loginNovita = createApiKeyLogin({
+	providerLabel: "Novita",
+	authUrl: "https://novita.ai/settings/key-management",
+	instructions: "Create or copy your API key from the Novita dashboard",
+	promptMessage: "Paste your Novita API key",
+	placeholder: "sk_...",
+	validation: {
+		// Validate against inference, not billing: `/openapi/v1/billing/balance/detail`
+		// requires the account-level Balance permission, which Novita's Developer and
+		// Basic team roles don't hold, so their valid inference keys were rejected.
+		kind: "chat-completions",
+		provider: "Novita",
+		baseUrl: "https://api.novita.ai/openai/v1",
+		model: "moonshotai/kimi-k2.7-code",
+	},
+});
+
+export const novitaProvider = {
+	id: "novita",
+	name: "Novita",
+	login: loginNovita,
+} satisfies ProviderDefinition & { readonly id: "novita" };

package/src/registry/nvidia.ts

@@ -0,0 +1,61 @@
+import * as AIError from "../error";
+import { validateOpenAICompatibleApiKey } from "./api-key-validation";
+import type { OAuthController, OAuthLoginCallbacks } from "./oauth/types";
+import type { ProviderDefinition } from "./types";
+
+const AUTH_URL = "https://org.ngc.nvidia.com/setup/personal-keys";
+const API_BASE_URL = "https://integrate.api.nvidia.com/v1";
+const VALIDATION_MODEL = "nvidia/llama-3.1-nemotron-70b-instruct";
+const PROVIDER_ID = "nvidia";
+
+export async function loginNvidia(options: OAuthController): Promise<string> {
+	if (!options.onPrompt) {
+		throw new AIError.OnPromptRequiredError("NVIDIA");
+	}
+
+	options.onAuth?.({
+		url: AUTH_URL,
+		instructions: "Copy your API key from NVIDIA NGC Personal Keys",
+	});
+
+	const apiKey = await options.onPrompt({
+		message: "Paste your NVIDIA API key",
+		placeholder: "nvapi-...",
+	});
+
+	if (options.signal?.aborted) {
+		throw new AIError.LoginCancelledError();
+	}
+
+	const trimmed = apiKey.trim();
+	if (!trimmed) {
+		throw new AIError.ApiKeyRequiredError();
+	}
+
+	options.onProgress?.("Validating API key (optional)...");
+	try {
+		await validateOpenAICompatibleApiKey({
+			provider: PROVIDER_ID,
+			apiKey: trimmed,
+			baseUrl: API_BASE_URL,
+			model: VALIDATION_MODEL,
+			signal: options.signal,
+			fetch: options.fetch,
+		});
+	} catch (error) {
+		// A real auth rejection (401/403) is fatal; any other validation-endpoint
+		// failure is non-fatal — skip validation and trust the supplied key.
+		if (AIError.is(AIError.classify(error), AIError.Flag.AuthFailed)) {
+			throw error;
+		}
+		options.onProgress?.("Skipping NVIDIA validation endpoint; continuing with provided API key.");
+	}
+
+	return trimmed;
+}
+
+export const nvidiaProvider = {
+	id: "nvidia",
+	name: "NVIDIA",
+	login: (cb: OAuthLoginCallbacks) => loginNvidia(cb),
+} as const satisfies ProviderDefinition;

package/src/registry/oauth/anthropic-constants.ts

@@ -0,0 +1,12 @@
+/**
+ * Absolute lifetime of an Anthropic OAuth grant family, anchored at the
+ * interactive login. Refresh-token rotation does NOT extend it: ~30 days
+ * after authorization the token endpoint returns
+ * `invalid_grant: "Refresh token expired"` for the latest rotated token and
+ * only a fresh interactive login recovers the account. Observed against
+ * production (grants authorized 2026-06-20/06-25 died 30d later to the hour
+ * despite healthy 8h rotations); matches Claude Code's documented monthly
+ * re-login. Consumers use this to warn before the deadline — it is a display
+ * heuristic, not a wire contract.
+ */
+export const ANTHROPIC_OAUTH_GRANT_TTL_MS = 30 * 24 * 60 * 60 * 1000;