@linxiraos/pi-ai 1.1.6 → 1.1.7

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+## [1.1.7] - 2026-09-01
+
+- 同步上游 OMP v18.0.11（`b8ce33a58911c26bed1d84f0db9a5e2e727c49a2`）。
+
 ## [1.1.6] - 2026-08-30
 
 - 同步上游 OMP v18.0.9（`cc14e04f075d`）。

package/dist/types/error/rate-limit.d.ts

@@ -24,13 +24,15 @@ export declare function calculateRateLimitBackoffMs(reason: RateLimitReason): nu
 /**
  * HTTP status codes that, absent richer body classification, represent an
  * account-local usage cap rather than a bad credential or a transient blip.
- * HTTP 402 Payment Required is categorically an account-billing cap (xAI
+ * HTTP 402 Payment Required represents an account-billing cap (xAI
  * Grok Build "usage balance exhausted", DeepSeek "Insufficient Balance",
- * OpenRouter credit exhaustion) — never a transient blip or bad credential.
- * Always combine with {@link isUsageLimitOutcome} when a message is available
- * — a 429 carrying transient rate-limit wording is NOT a usage cap.
+ * OpenRouter credit exhaustion) when opaque, payment/deactivation/balance-worded,
+ * or QUOTA_EXHAUSTED/CONCURRENT_LIMIT, while informative non-quota 402s (e.g.
+ * endpoint subscription requirements) remain non-usage-limits. Always combine
+ * with {@link isUsageLimitOutcome} when a message is available.
  */
 export declare function isUsageLimitStatus(status: number | undefined): boolean;
+export declare function is402BillingCapBody(message: string | undefined): boolean;
 /**
  * Returns true for failures that should burn one credential and rotate to a
  * sibling account. Decision tree:
@@ -43,13 +45,13 @@ export declare function isUsageLimitStatus(status: number | undefined): boolean;
  *     empty JSON, HTTP framing only) → rotate conservatively: the server
  *     gave us nothing else to go on.
  *  4. Body has content → defer to {@link parseRateLimitReason}. `QUOTA_EXHAUSTED`
- *     rotates; for the categorical 402 billing cap a `CONCURRENT_LIMIT` body
- *     also rotates (the cap is concurrent-worded but the status is still an
- *     exhausted billing cap). `RATE_LIMIT_EXCEEDED` (`Too many requests`,
- *     per-minute caps), `MODEL_CAPACITY_EXHAUSTED` (`Service overloaded`),
- *     `SERVER_ERROR`, and `UNKNOWN` (`Please retry in 5s`) stay in the
- *     provider's own backoff layer so transient 429s don't burn sibling
- *     credentials.
+ *     rotates; for a 402 status a `CONCURRENT_LIMIT` body also rotates (the cap
+ *     is concurrent-worded but the status is an exhausted billing cap).
+ *     `RATE_LIMIT_EXCEEDED` (`Too many requests`, per-minute caps),
+ *     `MODEL_CAPACITY_EXHAUSTED` (`Service overloaded`), `SERVER_ERROR`, and
+ *     `UNKNOWN` (e.g. "A subscription is required for this endpoint" or
+ *     "Please retry in 5s") stay in the provider's own backoff / failure
+ *     layer so transient or non-quota responses don't burn sibling credentials.
  */
 export declare function isUsageLimitOutcome(status: number | undefined, message: string | undefined): boolean;
 /**
@@ -78,6 +80,6 @@ export declare function isAccountScopedCapText(message: string): boolean;
 /**
  * A concurrency cap on a non-billing status is shed-and-backoff, not
  * credential-rotatable. This mirrors the exclusion in {@link isUsageLimitOutcome}
- * for the 403 auth-retry entry points. A 402 remains a categorical billing cap.
+ * for the 403 auth-retry entry points. A 402 remains an account-billing cap.
  */
 export declare function isConcurrencyCapExclusion(status: number | undefined, message: string | undefined): boolean;

package/dist/types/registry/api-key-login.d.ts

@@ -11,6 +11,8 @@ type ChatCompletionsValidation = {
     provider: string;
     baseUrl: string;
     model: string;
+    /** Treat an authenticated 401 (`invalid_model`) as a valid key. */
+    tolerateModelDenied?: boolean;
 };
 type AnthropicMessagesValidation = {
     kind: "anthropic-messages";

package/dist/types/registry/api-key-validation.d.ts

@@ -6,6 +6,7 @@ type OpenAICompatibleValidationOptions = {
     model: string;
     signal?: AbortSignal;
     fetch?: FetchImpl;
+    tolerateModelDenied?: boolean;
 };
 type AnthropicCompatibleValidationOptions = {
     provider: string;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@linxiraos/pi-ai",
-	"version": "1.1.6",
+	"version": "1.1.7",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://linxira-os.github.io/zeta/",
 	"author": "Can Boluk",
@@ -37,10 +37,10 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@linxiraos/pi-omptype": "1.1.6",
-		"@linxiraos/pi-catalog": "1.1.6",
-		"@linxiraos/pi-utils": "1.1.6",
-		"@linxiraos/pi-wire": "1.1.6"
+		"@linxiraos/pi-omptype": "1.1.7",
+		"@linxiraos/pi-catalog": "1.1.7",
+		"@linxiraos/pi-utils": "1.1.7",
+		"@linxiraos/pi-wire": "1.1.7"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/error/flags.ts

@@ -8,6 +8,7 @@ import {
 	STREAM_ENVELOPE_ERROR_PREFIX,
 } from "./classes";
 import {
+	is402BillingCapBody,
 	isAccountScopedCapText,
 	isDashScopeTokenLimitText,
 	isOpaqueStatusBody,
@@ -153,7 +154,7 @@ function matchesPayloadRejectionText(text: string): boolean {
 
 const TIMEOUT_PATTERN = /\b(?:operation\s+)?timed?\s*out\b|\btimeout\b|\bstream stall\b/i;
 const TRANSIENT_ENVELOPE_PATTERN = /anthropic stream envelope error:/i;
-const TRANSIENT_ENVELOPE_BEFORE_START_PATTERN = /before message_start/i;
+const TRANSIENT_ENVELOPE_TRUNCATION_PATTERN = /before message_(?:start|stop)/i;
 export const STREAM_READ_ERROR_PATTERN = /stream[_ -]?read[_ -]?error/i;
 export const TRANSIENT_TRANSPORT_PATTERN =
 	/\b(?:no[_ -]?capacity|(?:high|peak)[ _-]?demand|(?:at|over|insufficient)[ _-]?capacity|capacity[ _-]?(?:exceeded|exhausted)|peak[ _-]?load)\b|overloaded|provider.?returned.?error|rate.?limit|too many requests|\b(?:429|500|502|503|504)\b|service.?unavailable|server.?error|internal.?error|retry your request|network.?error|connection.?error|connection.?refused|unable.?to.?connect\.\s*is the computer able to access the url\?|other side closed|fetch failed|upstream.?connect|upstream.?request.?failed|reset before headers|socket hang up|timed? out|timeout|terminated|retry delay|stream stall|no error details in response|HTTP2(?:StreamReset|RefusedStream|EnhanceYourCalm)|nghttp2_(?:internal_error|refused_stream)|stream closed with error code nghttp2_(?:internal_error|refused_stream)|malformed.?function.?call/i;
@@ -404,7 +405,7 @@ function isTransientErrorText(text: string): boolean {
 	return (
 		isUnexpectedSocketCloseMessage(text) ||
 		isStreamReadErrorText(text) ||
-		(TRANSIENT_ENVELOPE_PATTERN.test(text) && TRANSIENT_ENVELOPE_BEFORE_START_PATTERN.test(text)) ||
+		(TRANSIENT_ENVELOPE_PATTERN.test(text) && TRANSIENT_ENVELOPE_TRUNCATION_PATTERN.test(text)) ||
 		TRANSIENT_TRANSPORT_PATTERN.test(text)
 	);
 }
@@ -471,26 +472,24 @@ function classifyText(
 
 		const isLimitStatus = isUsageLimitStatus(statusClean);
 		const reason = parseRateLimitReason(cleanMessage);
+		const is402BillingCap = statusClean === 402 && is402BillingCapBody(cleanMessage);
 		// Concurrency caps (e.g. Vertex "Online prediction concurrent requests
 		// quota exceeded") are shed-and-backoff, not credential-rotatable —
 		// exclude them even when the quota-worded phrasing matches the generic
 		// usage-limit text matcher, whose `quota.?exceeded` arm would otherwise
 		// set Flag.UsageLimit and burn a healthy sibling credential. HTTP 402 is
-		// excluded from this gate: it is categorically an account-billing cap, so
-		// a 402 whose body merely mentions concurrency still classifies as a
-		// usage limit, mirroring isUsageLimitOutcome.
-		const isBillingCapStatus = statusClean === 402;
-		const concurrencyExcluded = reason === "CONCURRENT_LIMIT" && !isBillingCapStatus;
+		// excluded from this gate: a 402 whose body merely mentions concurrency
+		// still classifies as a usage limit, mirroring isUsageLimitOutcome.
+		const concurrencyExcluded = reason === "CONCURRENT_LIMIT" && statusClean !== 402;
 		if (
 			!concurrencyExcluded &&
-			(matchesUsageLimitText(cleanMessage) ||
+			(is402BillingCap ||
+				matchesUsageLimitText(cleanMessage) ||
 				((statusClean === 403 || statusClean === undefined) && isAccountScopedCapText(cleanMessage)) ||
-				(isLimitStatus &&
-					(isOpaque || reason === "QUOTA_EXHAUSTED" || (isBillingCapStatus && reason === "CONCURRENT_LIMIT"))))
+				(isLimitStatus && (isOpaque || reason === "QUOTA_EXHAUSTED")))
 		) {
 			kinds |= Flag.UsageLimit;
 		}
-
 		if (isTimeoutText(errorMessage)) kinds |= Flag.Transient | Flag.Timeout;
 		else if (isTransientErrorText(errorMessage)) kinds |= Flag.Transient;
 		// A concurrency cap (e.g. Vertex "Online prediction concurrent requests
@@ -519,6 +518,9 @@ function classifyText(
 	) {
 		kinds |= Flag.PayloadRejected;
 	}
+	if (statusEvidence === 402 && (errorMessage === undefined || isOpaqueStatusBody(errorMessage))) {
+		kinds |= Flag.UsageLimit;
+	}
 	if (kinds !== 0) return create(kinds);
 	const fallbackStatus = errorStatus ?? (errorMessage ? status({ message: errorMessage }) : undefined);
 	if (fallbackStatus === 401 || fallbackStatus === 403) return create(Flag.AuthFailed);
@@ -567,7 +569,9 @@ export function classify(error: unknown, api?: Api): number {
 			const { status: codeStatus, code } = link;
 			if (
 				code === "usage_limit_reached" ||
-				(code === "insufficient_quota" && !isDashScopeTokenLimitText(link.message))
+				(code === "insufficient_quota" && !isDashScopeTokenLimitText(link.message)) ||
+				(codeStatus === 402 &&
+					(code === "payment_required" || code === "deactivated_workspace" || is402BillingCapBody(link.message)))
 			) {
 				linkKinds |= Flag.UsageLimit;
 			}

package/src/error/rate-limit.ts

@@ -278,15 +278,25 @@ const USAGE_LIMIT_PATTERN =
 /**
  * HTTP status codes that, absent richer body classification, represent an
  * account-local usage cap rather than a bad credential or a transient blip.
- * HTTP 402 Payment Required is categorically an account-billing cap (xAI
+ * HTTP 402 Payment Required represents an account-billing cap (xAI
  * Grok Build "usage balance exhausted", DeepSeek "Insufficient Balance",
- * OpenRouter credit exhaustion) — never a transient blip or bad credential.
- * Always combine with {@link isUsageLimitOutcome} when a message is available
- * — a 429 carrying transient rate-limit wording is NOT a usage cap.
+ * OpenRouter credit exhaustion) when opaque, payment/deactivation/balance-worded,
+ * or QUOTA_EXHAUSTED/CONCURRENT_LIMIT, while informative non-quota 402s (e.g.
+ * endpoint subscription requirements) remain non-usage-limits. Always combine
+ * with {@link isUsageLimitOutcome} when a message is available.
  */
 export function isUsageLimitStatus(status: number | undefined): boolean {
 	return status === 429 || status === 402;
 }
+const STATUS_402_QUOTA_PATTERN =
+	/\b(?:payment(?:\s+is)?[-_.\s]*required|deactivated_workspace|insufficient.?balance)\b/i;
+
+export function is402BillingCapBody(message: string | undefined): boolean {
+	if (message === undefined || isOpaqueStatusBody(message)) return true;
+	if (STATUS_402_QUOTA_PATTERN.test(message)) return true;
+	const reason = parseRateLimitReason(message);
+	return isQuotaExhaustedReason(reason) || reason === "CONCURRENT_LIMIT";
+}
 
 /**
  * Returns true for failures that should burn one credential and rotate to a
@@ -300,23 +310,17 @@ export function isUsageLimitStatus(status: number | undefined): boolean {
  *     empty JSON, HTTP framing only) → rotate conservatively: the server
  *     gave us nothing else to go on.
  *  4. Body has content → defer to {@link parseRateLimitReason}. `QUOTA_EXHAUSTED`
- *     rotates; for the categorical 402 billing cap a `CONCURRENT_LIMIT` body
- *     also rotates (the cap is concurrent-worded but the status is still an
- *     exhausted billing cap). `RATE_LIMIT_EXCEEDED` (`Too many requests`,
- *     per-minute caps), `MODEL_CAPACITY_EXHAUSTED` (`Service overloaded`),
- *     `SERVER_ERROR`, and `UNKNOWN` (`Please retry in 5s`) stay in the
- *     provider's own backoff layer so transient 429s don't burn sibling
- *     credentials.
+ *     rotates; for a 402 status a `CONCURRENT_LIMIT` body also rotates (the cap
+ *     is concurrent-worded but the status is an exhausted billing cap).
+ *     `RATE_LIMIT_EXCEEDED` (`Too many requests`, per-minute caps),
+ *     `MODEL_CAPACITY_EXHAUSTED` (`Service overloaded`), `SERVER_ERROR`, and
+ *     `UNKNOWN` (e.g. "A subscription is required for this endpoint" or
+ *     "Please retry in 5s") stay in the provider's own backoff / failure
+ *     layer so transient or non-quota responses don't burn sibling credentials.
  */
 export function isUsageLimitOutcome(status: number | undefined, message: string | undefined): boolean {
 	const structuredReason = message ? parseGoogleRpcRateLimitReason(message) : undefined;
 	if (structuredReason !== undefined) return isQuotaExhaustedReason(structuredReason);
-	// Concurrency caps are shed-and-backoff, not credential-rotatable — but only
-	// for quota-worded 429 / other statuses. HTTP 402 is categorically an
-	// account-billing cap, so a 402 whose body happens to mention concurrency is
-	// still an exhausted billing cap and must rotate; gate the exclusion on the
-	// status not being that categorical billing cap.
-	const isBillingCapStatus = status === 402;
 	if (isConcurrencyCapExclusion(status, message)) return false;
 	if (message && matchesUsageLimitText(message)) return true;
 	// A 403 is normally an auth failure, but several providers deliver an
@@ -326,14 +330,12 @@ export function isUsageLimitOutcome(status: number | undefined, message: string
 	// accept an undefined status too — but only when the body names a cap that
 	// resets, never on a bare 403, which stays an auth failure.
 	if ((status === 403 || status === undefined) && message && isAccountScopedCapText(message)) return true;
+	if (status === 402 && is402BillingCapBody(message)) return true;
 	if (!isUsageLimitStatus(status)) return false;
 	if (!message || isOpaqueStatusBody(message)) return true;
 	const reason = parseRateLimitReason(message);
-	// For the categorical 402 billing cap a concurrency-worded body is still an
-	// exhausted cap (rotate); for 429 / other only QUOTA_EXHAUSTED rotates.
-	return isQuotaExhaustedReason(reason) || (isBillingCapStatus && reason === "CONCURRENT_LIMIT");
+	return isQuotaExhaustedReason(reason);
 }
-
 /**
  * A usage-limit status body is opaque when it carries no signal beyond the
  * status itself — empty, whitespace-only, the status digits with HTTP/JSON
@@ -344,7 +346,8 @@ export function isUsageLimitOutcome(status: number | undefined, message: string
 export function isOpaqueStatusBody(message: string): boolean {
 	const cleaned = message
 		.replace(/\b(?:429|402)\b/g, "")
-		.replace(/\b(?:http|https|status|error|code|response|message)\b/gi, "");
+		.replace(/\b(?:http|https|status|error|code|response|message)\b/gi, "")
+		.replace(/\(?\bno body\b\)?/gi, "");
 	// A body is informative when the text classifier can act on it. Any Latin
 	// word or Simplified Chinese phrasing the classifier recognizes (quota
 	// exhaustion or a throttle) defers to parseRateLimitReason; a body that
@@ -395,7 +398,7 @@ export function isAccountScopedCapText(message: string): boolean {
 /**
  * A concurrency cap on a non-billing status is shed-and-backoff, not
  * credential-rotatable. This mirrors the exclusion in {@link isUsageLimitOutcome}
- * for the 403 auth-retry entry points. A 402 remains a categorical billing cap.
+ * for the 403 auth-retry entry points. A 402 remains an account-billing cap.
  */
 export function isConcurrencyCapExclusion(status: number | undefined, message: string | undefined): boolean {
 	return message !== undefined && parseRateLimitReason(message) === "CONCURRENT_LIMIT" && status !== 402;

package/src/providers/openai-completions.ts

@@ -63,6 +63,7 @@ import type {
 	ChatCompletionContentPart,
 	ChatCompletionContentPartImage,
 	ChatCompletionContentPartText,
+	ChatCompletionMessageFunctionToolCall,
 	ChatCompletionMessageParam,
 	ChatCompletionTool,
 	ChatCompletionToolMessageParam,
@@ -132,6 +133,44 @@ type OpenAICompletionsDeltaWithReasoningDetails = ChatCompletionChunk.Choice["de
 	reasoning_details?: unknown;
 };
 
+type GeminiThoughtSignatureNamespace = "google" | "vertex";
+
+type GeminiThoughtSignatureExtraContent = Partial<
+	Record<GeminiThoughtSignatureNamespace, { thought_signature: string }>
+>;
+
+type OpenAICompletionsFunctionToolCall = ChatCompletionMessageFunctionToolCall & {
+	extra_content?: GeminiThoughtSignatureExtraContent;
+};
+
+const GEMINI_THOUGHT_SIGNATURE_NAMESPACES: readonly GeminiThoughtSignatureNamespace[] = ["google", "vertex"];
+
+function getGeminiThoughtSignatureExtraContent(value: unknown): GeminiThoughtSignatureExtraContent | undefined {
+	if (typeof value !== "object" || value === null) return undefined;
+	for (const namespace of GEMINI_THOUGHT_SIGNATURE_NAMESPACES) {
+		const providerContent = Reflect.get(value, namespace);
+		if (typeof providerContent !== "object" || providerContent === null) continue;
+		const thoughtSignature = Reflect.get(providerContent, "thought_signature");
+		if (typeof thoughtSignature !== "string" || thoughtSignature.length === 0) continue;
+		return namespace === "google"
+			? { google: { thought_signature: thoughtSignature } }
+			: { vertex: { thought_signature: thoughtSignature } };
+	}
+	return undefined;
+}
+
+function parseGeminiThoughtSignatureExtraContent(
+	thoughtSignature: string | undefined,
+): GeminiThoughtSignatureExtraContent | undefined {
+	if (!thoughtSignature) return undefined;
+	try {
+		const parsed: unknown = JSON.parse(thoughtSignature);
+		return getGeminiThoughtSignatureExtraContent(parsed);
+	} catch {
+		return undefined;
+	}
+}
+
 type OpenAICompletionsAssistantMessageParam = ChatCompletionAssistantMessageParam &
 	Partial<Record<OpenAICompletionsReasoningField, string>> & {
 		reasoning_details?: unknown[];
@@ -1257,6 +1296,8 @@ const streamOpenAICompletionsOnce = (
 
 							if (toolCall.id) block.id = toolCall.id;
 							if (incomingName) block.name = incomingName;
+							const extraContent = getGeminiThoughtSignatureExtraContent(Reflect.get(toolCall, "extra_content"));
+							if (extraContent) block.thoughtSignature = JSON.stringify(extraContent);
 							let delta = "";
 							// The OpenAI SDK types `function.arguments` as a JSON string, but MiniMax-compatible
 							// hosts stream a fully-formed object instead. Model both shapes so the branches below
@@ -2235,26 +2276,28 @@ export function convertMessages(
 				assistantMsg.tool_calls = toolCalls.map((tc, toolCallIndex) => {
 					const toolCallId = ensureToolCallId(tc.id, `${i}:${toolCallIndex}:${tc.name}`, msg);
 					rememberToolCallId(tc.id, toolCallId);
-					return {
+					const replayedToolCall: OpenAICompletionsFunctionToolCall = {
 						id: normalizeMistralToolId(toolCallId, compat.requiresMistralToolIds),
-						type: "function" as const,
+						type: "function",
 						function: {
 							name: tc.name,
 							arguments: serializeToolArguments(tc.arguments),
 						},
 					};
+					const extraContent = parseGeminiThoughtSignatureExtraContent(tc.thoughtSignature);
+					if (extraContent) replayedToolCall.extra_content = extraContent;
+					return replayedToolCall;
+				});
+				const reasoningDetails = toolCalls.flatMap(tc => {
+					const thoughtSignature = tc.thoughtSignature;
+					if (!thoughtSignature) return [];
+					try {
+						const parsed: unknown = JSON.parse(thoughtSignature);
+						return getGeminiThoughtSignatureExtraContent(parsed) ? [] : [parsed];
+					} catch {
+						return [];
+					}
 				});
-				const reasoningDetails = toolCalls
-					.filter(tc => tc.thoughtSignature)
-					.map(tc => {
-						try {
-							const parsed: unknown = JSON.parse(tc.thoughtSignature!);
-							return parsed;
-						} catch {
-							return null;
-						}
-					})
-					.filter(Boolean);
 				if (reasoningDetails.length > 0) {
 					assistantMsg.reasoning_details = reasoningDetails;
 				}

package/src/providers/openai-data-uri.ts

@@ -4,19 +4,48 @@ export interface DecodedDataUri {
 	mimeType: string;
 }
 
+function hexValue(code: number): number {
+	if (code >= 0x30 && code <= 0x39) return code - 0x30;
+	if (code >= 0x41 && code <= 0x46) return code - 0x41 + 10;
+	if (code >= 0x61 && code <= 0x66) return code - 0x61 + 10;
+	return -1;
+}
+
+/** Decode percent escapes as bytes; image data is not necessarily valid UTF-8. */
+function decodePercentEncodedBytes(payload: string): Buffer {
+	const output = Buffer.allocUnsafe(Buffer.byteLength(payload, "utf8"));
+	let sourceOffset = 0;
+	let outputOffset = 0;
+	while (sourceOffset < payload.length) {
+		if (payload.charCodeAt(sourceOffset) !== 0x25) {
+			const nextEscape = payload.indexOf("%", sourceOffset);
+			const end = nextEscape < 0 ? payload.length : nextEscape;
+			outputOffset += output.write(payload.slice(sourceOffset, end), outputOffset, "utf8");
+			sourceOffset = end;
+			continue;
+		}
+		const high = hexValue(payload.charCodeAt(sourceOffset + 1));
+		const low = hexValue(payload.charCodeAt(sourceOffset + 2));
+		if (high < 0 || low < 0) throw new URIError("URI malformed");
+		output[outputOffset++] = (high << 4) | low;
+		sourceOffset += 3;
+	}
+	return output.subarray(0, outputOffset);
+}
+
 /**
  * Decodes base64 and percent-encoded `data:` URIs.
  *
  * Returns `undefined` for non-data URLs and data URIs without a comma separator.
  */
 export function decodeDataUri(url: string): DecodedDataUri | undefined {
-	if (!url.startsWith("data:")) return undefined;
+	if (url.slice(0, 5).toLowerCase() !== "data:") return undefined;
 	const comma = url.indexOf(",");
 	if (comma < 0) return undefined;
 	const header = url.slice(5, comma);
 	const payload = url.slice(comma + 1);
-	const isBase64 = header.endsWith(";base64");
+	const isBase64 = header.toLowerCase().endsWith(";base64");
 	const mimeType = (isBase64 ? header.slice(0, -";base64".length) : header) || "application/octet-stream";
-	const data = isBase64 ? payload : Buffer.from(decodeURIComponent(payload), "utf8").toString("base64");
+	const data = isBase64 ? payload : decodePercentEncodedBytes(payload).toString("base64");
 	return { data, mimeType };
 }

package/src/registry/api-key-login.ts

@@ -19,8 +19,9 @@ type ChatCompletionsValidation = {
 	provider: string;
 	baseUrl: string;
 	model: string;
+	/** Treat an authenticated 401 (`invalid_model`) as a valid key. */
+	tolerateModelDenied?: boolean;
 };
-
 type AnthropicMessagesValidation = {
 	kind: "anthropic-messages";
 	provider: string;
@@ -99,6 +100,7 @@ export function createApiKeyLogin(config: ApiKeyLoginConfig): (options: OAuthCon
 					model: config.validation.model,
 					signal: options.signal,
 					fetch: options.fetch,
+					tolerateModelDenied: config.validation.tolerateModelDenied,
 				});
 			} else if (config.validation.kind === "anthropic-messages") {
 				await validateAnthropicCompatibleApiKey({

package/src/registry/api-key-validation.ts

@@ -1,4 +1,4 @@
-import { ProviderHttpError } from "../error/classes";
+import { OpenAIHttpError, ProviderHttpError } from "../error/classes";
 import type { FetchImpl } from "../types";
 
 type OpenAICompatibleValidationOptions = {
@@ -8,6 +8,7 @@ type OpenAICompatibleValidationOptions = {
 	model: string;
 	signal?: AbortSignal;
 	fetch?: FetchImpl;
+	tolerateModelDenied?: boolean;
 };
 type AnthropicCompatibleValidationOptions = {
 	provider: string;
@@ -27,6 +28,11 @@ type ModelListValidationOptions = {
 	fetch?: FetchImpl;
 };
 
+type ErrorEnvelope = {
+	details: string;
+	code: string | undefined;
+};
+
 const VALIDATION_TIMEOUT_MS = 15_000;
 
 function normalizeAnthropicCompatibleBaseUrl(baseUrl: string): string {
@@ -40,7 +46,7 @@ function resolveValidationHeaders(
 	return typeof headers === "function" ? headers() : headers;
 }
 
-async function createApiKeyValidationError(provider: string, response: Response): Promise<ProviderHttpError> {
+async function readErrorEnvelope(response: Response): Promise<ErrorEnvelope> {
 	let details = "";
 	try {
 		details = (await response.text()).trim();
@@ -48,10 +54,27 @@ async function createApiKeyValidationError(provider: string, response: Response)
 		// Ignore body read errors; the HTTP status still preserves the failure category.
 	}
 
+	let bodyJson: unknown;
+	try {
+		bodyJson = details ? JSON.parse(details) : undefined;
+	} catch {
+		bodyJson = undefined;
+	}
+	const { code } = OpenAIHttpError.parseEnvelope(bodyJson, details);
+	return { details, code };
+}
+
+async function createApiKeyValidationError(
+	provider: string,
+	response: Response,
+	envelope?: ErrorEnvelope,
+): Promise<ProviderHttpError> {
+	const { details, code } = envelope ?? (await readErrorEnvelope(response));
+
 	const message = details
 		? `${provider} API key validation failed (${response.status}): ${details}`
 		: `${provider} API key validation failed (${response.status})`;
-	return new ProviderHttpError(message, response.status, { headers: response.headers });
+	return new ProviderHttpError(message, response.status, { headers: response.headers, code });
 }
 
 /**
@@ -83,7 +106,12 @@ export async function validateOpenAICompatibleApiKey(options: OpenAICompatibleVa
 		return;
 	}
 
-	throw await createApiKeyValidationError(options.provider, response);
+	const envelope = await readErrorEnvelope(response);
+	if (options.tolerateModelDenied && response.status === 401 && envelope.code === "invalid_model") {
+		return;
+	}
+
+	throw await createApiKeyValidationError(options.provider, response, envelope);
 }
 
 /**

package/src/registry/oauth/perplexity.ts

@@ -199,10 +199,11 @@ async function httpEmailLogin(ctrl: OAuthController): Promise<OAuthCredentials>
 		signal: ctrl.signal,
 	});
 
-	const verifyData = (await verifyResponse.json()) as {
+	let verifyData = (await verifyResponse.json()) as {
 		token?: string;
 		challenge_token?: string;
 		status?: string;
+		error?: string;
 		error_code?: string;
 		text?: string;
 	};
@@ -216,7 +217,52 @@ async function httpEmailLogin(ctrl: OAuthController): Promise<OAuthCredentials>
 		});
 	}
 
-	const token = verifyData.challenge_token || verifyData.token;
+	if (verifyData.status === "totp_challenge_required" && verifyData.challenge_token) {
+		const totp = await ctrl.onPrompt({
+			message: "Enter the code from your authenticator app",
+			placeholder: "123456",
+		});
+		if (ctrl.signal?.aborted) throw new AIError.LoginCancelledError();
+		const trimmedTotp = totp.trim();
+		if (!trimmedTotp) {
+			throw new AIError.OAuthError("Authenticator code is required", {
+				kind: "validation",
+				provider: "perplexity",
+			});
+		}
+		ctrl.onProgress?.("Verifying authenticator code...");
+		const totpResponse = await request("https://www.perplexity.ai/api/auth/totp/challenge-verify", {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				"User-Agent": APP_USER_AGENT,
+				"X-App-ApiVersion": API_VERSION,
+			},
+			body: JSON.stringify({
+				token: verifyData.challenge_token,
+				code: trimmedTotp,
+			}),
+			signal: ctrl.signal,
+		});
+		verifyData = (await totpResponse.json()) as typeof verifyData;
+		if (!totpResponse.ok) {
+			const reason = verifyData.text ?? verifyData.error_code ?? verifyData.status ?? "TOTP verification failed";
+			throw new AIError.OAuthError(`Perplexity authenticator verification failed: ${reason}`, {
+				kind: "validation",
+				provider: "perplexity",
+				status: totpResponse.status,
+			});
+		}
+		if (!verifyData.token) {
+			verifyData = {
+				token:
+					cookies.get("__Secure-next-auth.session-token") ?? cookies.get("next-auth.session-token") ?? undefined,
+				status: "success",
+			};
+		}
+	}
+
+	const token = verifyData.token ?? verifyData.challenge_token;
 	if (!token || verifyData.error_code || (verifyData.status && verifyData.status !== "success")) {
 		const reason = verifyData.text ?? verifyData.error_code ?? verifyData.status ?? "missing token";
 		throw new AIError.OAuthError(`Perplexity OTP verification response rejected: ${reason}`, {

package/src/registry/oauth/zai.ts

@@ -217,7 +217,11 @@ export class ZaiOAuthFlow extends OAuthCallbackFlow {
 	#fetch: FetchImpl;
 
 	constructor(ctrl: OAuthController) {
-		super(ctrl, CALLBACK_PORT, CALLBACK_PATH);
+		super(ctrl, {
+			preferredPort: CALLBACK_PORT,
+			callbackPath: CALLBACK_PATH,
+			allowPortFallback: false,
+		});
 		this.#fetch = ctrl.fetch ?? fetch;
 	}
 

package/src/registry/qianfan.ts

@@ -17,6 +17,7 @@ export const loginQianfan = createApiKeyLogin({
 		provider: "qianfan",
 		baseUrl: API_BASE_URL,
 		model: VALIDATION_MODEL,
+		tolerateModelDenied: true,
 	},
 });