@oh-my-pi/pi-ai 17.3.4 → 17.3.7

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 ## [Unreleased]
 
+## [17.3.7] - 2026-08-17
+
+### Changed
+
+- Send the `omp/<version>` User-Agent on xAI chat (`xai` and `xai-oauth`) unless the request already set its own.
+
+## [17.3.5] - 2026-08-16
+
+### Added
+
+- Added retryable oneshot completion support (`retryTransientCompletion`) so non-agent LLM calls correctly retry on transient provider failures (Anthropic overload/rate-limit errors, HTTP 429/500/502/503/529), honoring provider-supplied retry-after timing before giving up.
+
+### Fixed
+
+- Fixed xAI availability detection so paid-key-only setups correctly default to `xai/grok-4.5` instead of the free SuperGrok catalog; explicit `xai-oauth/…` selectors still work as before.
+- Fixed xAI Responses requests sending unsupported parameters (reasoning summary, presence/frequency penalties) that some models rejected.
+- Fixed Umans usage reporting incorrectly marking quota as exhausted based on raw request counts instead of actual weighted usage, and improved the usage display to show both a soft-cap warning and a hard exhaustion limit with an accurate countdown to reset.
+- Fixed `omp usage invalidate` to fully clear stale usage data and force a fresh refresh, so upgraded subscriptions no longer show outdated quota information.
+- Improved session recovery to correctly treat certain Cursor HTTP/2 connection errors as transient instead of ending the session.
+- Fixed OpenAI-compatible streams (e.g. DeepSeek) that are cut off mid-generation being silently treated as a completed response instead of being retried.
+- Fixed DeepSeek resource-exhaustion interruptions not being automatically retried.
+- Fixed tool-call IDs being lost during same-model replay, which could break correlation with custom gateways.
+- Fixed Kimi Code multi-account routing to prefer accounts with more available quota, respect usage-limit cooldowns, and keep consistent usage history across token refreshes.
+- Fixed Anthropic custom signing-proxy conversations losing tool-search results and thinking content during replay.
+- Fixed rare runaway response loops across model providers so they now fail gracefully instead of repeating indefinitely.
+- Fixed xAI rejecting entire turns due to certain MCP tool schema shapes, restoring compatibility while isolating any remaining incompatible tools rather than failing the whole request.
+- Fixed Alibaba DashScope/Bailian transient per-minute rate limits being misclassified as full quota exhaustion, causing unnecessary long backoffs instead of quick retries.
+- Fixed Anthropic-compatible streams dropping thinking content, which broke replay of prior reasoning.
+- Updated the Alibaba Coding Plan China login flow to point to the current Bailian API-key management console.
+
 ## [17.3.4] - 2026-08-14
 
 ### Fixed

package/dist/types/auth-storage.d.ts

@@ -804,10 +804,20 @@ export declare class AuthStorage {
      */
     has(provider: string): boolean;
     /**
-     * Check if any form of auth is configured for a provider.
-     * Unlike getApiKey(), this doesn't refresh OAuth tokens.
+     * Dedicated auth for default-model availability (picker / `getAvailable`).
+     * Unlike {@link getApiKey}, this does not refresh OAuth tokens, and unlike
+     * {@link hasResolvableAuth} it ignores cross-provider env aliases so
+     * `XAI_API_KEY` does not auto-select SuperGrok (`xai-oauth`).
      */
     hasAuth(provider: string): boolean;
+    /**
+     * Whether a request could resolve a key for this provider, including
+     * cross-provider env aliases (`xai-oauth` borrowing `XAI_API_KEY`).
+     * Use this for explicit model preflight (`xai-oauth/grok-4.6`); use
+     * {@link hasAuth} for auto-availability so the default picker stays on
+     * paid `xai` when only `XAI_API_KEY` is set.
+     */
+    hasResolvableAuth(provider: string): boolean;
     /**
      * True iff a dedicated, non-env credential source is configured for this
      * provider — i.e. anything in the cascade EXCEPT `getEnvApiKey(provider)`.

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

@@ -3,11 +3,14 @@
  * Ported from opencode-antigravity-auth plugin for consistency.
  */
 export type RateLimitReason = "QUOTA_EXHAUSTED" | "INSUFFICIENT_G1_CREDITS_BALANCE" | "RATE_LIMIT_EXCEEDED" | "CONCURRENT_LIMIT" | "MODEL_CAPACITY_EXHAUSTED" | "SERVER_ERROR" | "UNKNOWN";
+/** True for DashScope/Bailian's documented OpenAI-compatible TPM/TPS throttle. */
+export declare function isDashScopeTokenLimitText(errorMessage: string): boolean;
 /**
  * Classify a rate-limit error message into a reason category.
  * Priority order: explicit details in a resource-exhausted error > QUOTA
- * (Antigravity "quota will reset") > CONCURRENT_LIMIT > MODEL_CAPACITY >
- * QUOTA (account) > RATE_LIMIT > QUOTA (generic) > SERVER_ERROR > bare resource-exhausted > UNKNOWN.
+ * (Antigravity "quota will reset") > CN quota > DASHSCOPE_TOKEN_LIMIT (TPM/TPS
+ * throttle) > CONCURRENT_LIMIT > MODEL_CAPACITY > QUOTA (account) > RATE_LIMIT >
+ * QUOTA (generic) > SERVER_ERROR > bare resource-exhausted > UNKNOWN.
  *
  * Bare "resource exhausted" / "resource_exhausted" maps to MODEL_CAPACITY (transient, short wait).
  * Explicit details such as "quota exceeded" retain their normal classification.

package/dist/types/index.d.ts

@@ -6,6 +6,7 @@ export * from "./auth-gateway/types.js";
 export * from "./auth-retry.js";
 export * from "./auth-storage.js";
 export * from "./error/rate-limit.js";
+export * from "./oneshot-retry.js";
 export * from "./provider-details.js";
 export * from "./providers/anthropic.js";
 export * from "./providers/anthropic-client.js";

package/dist/types/oneshot-retry.d.ts

@@ -0,0 +1,89 @@
+import type { AssistantMessage } from "./types.js";
+import { type HeadersLike } from "./utils/retry-after.js";
+/**
+ * Transient-failure retry for **oneshot** (non-agent-loop) completions.
+ *
+ * Why this exists: `streamSimple`/`completeSimple` retry *auth* failures
+ * (credential rotation) but deliberately surface *transient* provider failures
+ * — Anthropic `overloaded_error`, `rate_limit_error`, HTTP 429/500/502/503/529
+ * — as a **resolved** `AssistantMessage` with `stopReason: "error"`. For the
+ * main agent turn that is correct: `TurnRecovery` owns recovery there, and it
+ * must refuse to replay once tool calls or visible text have streamed.
+ *
+ * Oneshots have no such hazard. A summary, title, handoff, or image
+ * description produces no side effects, so re-issuing the whole request is
+ * safe and is almost always what the caller wants. Before this helper every
+ * oneshot call site had to re-implement that decision, and most did not —
+ * failing on the first blip, or swallowing it into `null` so a transient
+ * overload was indistinguishable from a legitimate empty result.
+ *
+ * Classification reuses the existing provider predicates (`AIError`), so the
+ * set of retryable Anthropic failures stays defined in exactly one place.
+ * Usage limits are included: unlike the provider loop — which excludes them so
+ * credential rotation can own them — a oneshot has no rotation layer above it,
+ * and the retry hint the provider supplies (`retry-after`, "try again in ~5m")
+ * is honored, so waiting is the correct response.
+ */
+export interface OneshotRetryOptions {
+    /** Total attempts, including the first. Default 3. Values < 1 are treated as 1. */
+    maxAttempts?: number;
+    /** First backoff step in ms; doubles per attempt. Default 500. */
+    baseDelayMs?: number;
+    /**
+     * Upper bound for a single wait. Default 30_000. A provider retry hint
+     * longer than this aborts the retry instead of parking the caller — the
+     * error surfaces so higher-level recovery (or the user) can decide.
+     */
+    maxDelayMs?: number;
+    /**
+     * Stops further attempts. Two distinct paths, both preserving the caller's
+     * intent: an abort already visible when an attempt settles surfaces that
+     * attempt's own result (`completeSimple` reports `stopReason: "aborted"`),
+     * while an abort that lands during the backoff wait rejects with the abort
+     * reason — a user cancel stays a cancel and is never relabelled as the
+     * provider failure we happened to be waiting on.
+     *
+     * This helper does NOT pass the signal into `run` — cancelling the in-flight
+     * request is the closure's job, because a per-attempt deadline must be
+     * rebuilt on every attempt. Construct it inside `run`
+     * (`signal: AbortSignal.timeout(MS)`, or `AbortSignal.any([outer, perAttempt])`);
+     * a deadline captured outside would fire once and then abort every retry,
+     * silently turning this helper into a single attempt.
+     */
+    signal?: AbortSignal;
+    /**
+     * Headers of the attempt that just failed, used to honor `retry-after`.
+     *
+     * Load-bearing: a transient Anthropic failure arrives as a **resolved**
+     * `AssistantMessage`, and `AssistantMessage` carries no headers — so without
+     * this the real `retry-after` / `x-ratelimit-reset` values on a 429/529 are
+     * invisible and only the (usually hint-free) error text is available.
+     * Callers that already capture headers via `SimpleStreamOptions.onResponse`
+     * should return the latest capture here; it is read once per failed attempt.
+     * Thrown errors need no wiring — headers are recovered from the error itself.
+     */
+    getResponseHeaders?: () => HeadersLike;
+    /** Observability hook. Fires immediately before sleeping. */
+    onRetry?: (info: OneshotRetryInfo) => void;
+}
+export interface OneshotRetryInfo {
+    /** 1-based index of the attempt that just failed. */
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    /** True when `delayMs` came from a provider retry hint rather than backoff. */
+    fromRetryHint: boolean;
+    errorMessage: string;
+    /** `AIError` classification bits of the failure. */
+    errorId: number;
+}
+/**
+ * Run a oneshot completion, retrying transient provider failures.
+ *
+ * Handles both failure shapes: a resolved `AssistantMessage` carrying
+ * `stopReason: "error"` (what `completeSimple` produces) and a thrown error
+ * (what the raw HTTP helpers produce). A non-retryable failure is returned or
+ * rethrown unchanged, so existing caller error handling keeps working — this
+ * only removes the *first-blip* failure mode.
+ */
+export declare function retryTransientCompletion(run: (attempt: number) => Promise<AssistantMessage>, options?: OneshotRetryOptions): Promise<AssistantMessage>;

package/dist/types/providers/anthropic-wire.d.ts

@@ -69,6 +69,10 @@ export type ServerToolUseBlockParam = {
 export type WebSearchServerToolUseBlockParam = ServerToolUseBlockParam & {
     name: "web_search";
 };
+/** Tool-search server-tool call whose matching result is replayable by omp. */
+export type ToolSearchServerToolUseBlockParam = ServerToolUseBlockParam & {
+    name: "tool_search_tool_regex" | "tool_search_tool_bm25";
+};
 /** Native web-search result replayed inside an assistant turn. */
 export type WebSearchToolResultBlockParam = {
     type: "web_search_tool_result";
@@ -76,14 +80,23 @@ export type WebSearchToolResultBlockParam = {
     content: unknown;
     [key: string]: unknown;
 };
-/** True for the complete native web-search history variants omp can replay. */
-export declare function isAnthropicWebSearchHistoryBlock(block: {
+/** Native tool-search result replayed inside an assistant turn. */
+export type ToolSearchToolResultBlockParam = {
+    type: "tool_search_tool_result";
+    tool_use_id: string;
+    content: unknown;
+    [key: string]: unknown;
+};
+/** Anthropic server-tool history variants omp can replay atomically. */
+export type AnthropicServerToolHistoryBlockParam = WebSearchServerToolUseBlockParam | WebSearchToolResultBlockParam | ToolSearchServerToolUseBlockParam | ToolSearchToolResultBlockParam;
+/** True when a block is complete Anthropic server-tool history omp can replay. */
+export declare function isAnthropicServerToolHistoryBlock(block: {
     type: string;
     name?: unknown;
     id?: unknown;
     tool_use_id?: unknown;
     content?: unknown;
-}): block is WebSearchServerToolUseBlockParam | WebSearchToolResultBlockParam;
+}): block is AnthropicServerToolHistoryBlockParam;
 export type ThinkingBlockParam = {
     type: "thinking";
     thinking: string;
@@ -108,7 +121,7 @@ export type FallbackBlockParam = {
         model: string;
     };
 };
-export type ContentBlockParam = TextBlockParam | ImageBlockParam | ToolUseBlockParam | ToolResultBlockParam | ServerToolUseBlockParam | WebSearchToolResultBlockParam | ThinkingBlockParam | RedactedThinkingBlockParam | FallbackBlockParam;
+export type ContentBlockParam = TextBlockParam | ImageBlockParam | ToolUseBlockParam | ToolResultBlockParam | ServerToolUseBlockParam | WebSearchToolResultBlockParam | ToolSearchToolResultBlockParam | ThinkingBlockParam | RedactedThinkingBlockParam | FallbackBlockParam;
 /**
  * A single conversation turn.
  *
@@ -284,7 +297,7 @@ export type ResponseContentBlock = {
     id: string;
     name: string;
     input?: Record<string, unknown> | null;
-} | ServerToolUseBlockParam | WebSearchToolResultBlockParam | {
+} | ServerToolUseBlockParam | WebSearchToolResultBlockParam | ToolSearchToolResultBlockParam | {
     type: "fallback";
     from: {
         model: string;

package/dist/types/providers/openai-shared.d.ts

@@ -582,7 +582,7 @@ type CommonSamplingOptions = Pick<StreamOptions, "temperature" | "topP" | "topK"
  * reflect the model's context window rather than the upstream output limit.
  */
 export declare function applyCommonResponsesSamplingParams<P extends CommonResponsesParams>(params: P, options: CommonSamplingOptions | undefined, model: Pick<Model, "provider" | "api" | "id" | "omitMaxOutputTokens" | "maxTokens"> & {
-    compat: Pick<ResolvedOpenAISharedCompat, "supportsSamplingParams">;
+    compat: Pick<ResolvedOpenAISharedCompat, "supportsSamplingParams" | "supportsPenaltyAndStopParams">;
 }): void;
 type ReasoningOptions = {
     reasoning?: string;

package/dist/types/types.d.ts

@@ -521,19 +521,20 @@ export interface AnthropicFallbackContent {
     };
 }
 /**
- * Verbatim Anthropic web-search call/result retained for same-provider
- * history replay. Other providers discard it in `transformMessages`.
+ * Verbatim Anthropic web-search or tool-search call/result retained for
+ * same-provider history replay. Other providers discard it in
+ * `transformMessages`.
  */
 export interface AnthropicServerToolContent {
     type: "anthropicServerTool";
     block: {
         type: "server_tool_use";
         id: string;
-        name: "web_search";
+        name: "web_search" | "tool_search_tool_regex" | "tool_search_tool_bm25";
         input?: Record<string, unknown> | null;
         [key: string]: unknown;
     } | {
-        type: "web_search_tool_result";
+        type: "web_search_tool_result" | "tool_search_tool_result";
         tool_use_id: string;
         content: unknown;
         [key: string]: unknown;

package/dist/types/usage/kimi.d.ts

@@ -1,2 +1,4 @@
-import type { UsageProvider } from "../usage.js";
+import type { CredentialRankingStrategy, UsageProvider } from "../usage.js";
 export declare const kimiUsageProvider: UsageProvider;
+/** Ranks Kimi OAuth accounts by the canonical 5-hour and 7-day quota windows. */
+export declare const kimiRankingStrategy: CredentialRankingStrategy;

package/dist/types/utils/schema/strict-tool-validation.d.ts

@@ -7,10 +7,19 @@
  * copied onto a `type: "null"` branch, or an `enum` placed on an `array`
  * schema instead of its `items`). One such tool 400s the entire turn, so
  * callers quarantine just the offending tool. See issue #2652.
+ *
+ * xAI additionally rejects a leftover *root* `anyOf`/`oneOf` whose branches
+ * are not objects ("tool parameter root must be an object type"). That class
+ * is opt-in via {@link FindStrictToolSchemaViolationOptions.rejectXaiRootObjectUnion}
+ * so OpenAI/Azure/Codex keep valid object-root unions.
  */
+export interface FindStrictToolSchemaViolationOptions {
+    /** xAI (paid + OAuth) only: leftover object-root unions 400 the whole turn. */
+    rejectXaiRootObjectUnion?: boolean;
+}
 /**
  * Walk a tool parameter schema for OpenAI-strict `enum`/`const`-vs-`type`
  * contradictions. Returns a JSON-pointer-ish path to the first offending node,
  * or `null` when the schema is safe to emit.
  */
-export declare function findStrictToolSchemaViolation(schema: unknown, path?: string): string | null;
+export declare function findStrictToolSchemaViolation(schema: unknown, path?: string, options?: FindStrictToolSchemaViolationOptions): string | null;

package/dist/types/utils/schema/wire.d.ts

@@ -14,6 +14,12 @@ import type { Tool } from "../../types.js";
  * methods, while raw JSON Schema is a plain object.
  */
 export declare function isArkSchema(value: unknown): value is Type;
+/**
+ * Return an xAI-compatible copy of an object-root schema whose union consists
+ * only of typeless required-key fragments. Other providers must retain the
+ * union because it is a real model-facing constraint.
+ */
+export declare function flattenExclusiveRequiredRootUnion(schema: Record<string, unknown>): Record<string, unknown>;
 /**
  * Normalize `{}` (an unconstrained schema) to boolean `true` in every
  * schema-valued position. JSON Schema draft 2020-12 §4.3.1 defines them as

package/dist/types/utils/thinking-loop.d.ts

@@ -5,11 +5,12 @@ import { AssistantMessageEventStream } from "./event-stream.js";
  *  classifiers treat it as a transient (retryable) stop without bespoke rules. */
 export declare const THINKING_LOOP_ERROR_MARKER = "Thinking loop detected";
 /**
- * True when `model.id` belongs to a family guarded for thinking/response loops:
- * Gemini, DeepSeek, or Grok.
+ * True when `model.id` belongs to a family guarded by the semantic loop
+ * heuristics: Gemini, DeepSeek, or Grok. Exact suffix-cycle detection applies to
+ * every enabled model independently of this predicate.
  *
  * Model identity is derived only from its id; provider and compatibility metadata
- * do not opt opaque aliases into the guard.
+ * do not opt opaque aliases into semantic detection.
  */
 export declare function isLoopGuardedModel(model: Model<Api>, options?: StreamOptions): boolean;
 /**
@@ -19,6 +20,8 @@ export declare function isLoopGuardedModel(model: Model<Api>, options?: StreamOp
  */
 export declare class ThinkingLoopDetector {
     #private;
+    private readonly semanticHeuristics;
+    constructor(semanticHeuristics?: boolean);
     push(delta: string): string | null;
     /** Process the buffered trailing paragraph (one with no blank-line / heading
      *  terminator). Called when the thinking block ends so the final segment —
@@ -75,12 +78,12 @@ export declare class GeminiHeaderRunDetector {
  */
 export declare function guardThinkingLoopStream(inner: AssistantMessageEventStream, model: Model<Api>, controller: AbortController, options?: StreamOptions): AssistantMessageEventStream;
 /**
- * Apply the loop guard around a provider dispatch. For non-guarded models
- * (or when disabled) this is a transparent pass-through. For guarded models it injects a
- * guard abort signal into the provider call so a detected loop tears down the
- * upstream, then wraps the returned stream. The guard only raises the retryable
- * stall; bounding the re-samples and the final cook pass lives in the
- * result-awaiting caller.
+ * Apply the loop guard around a provider dispatch. Unless explicitly disabled,
+ * every model gets exact suffix-cycle detection; Gemini, DeepSeek, and Grok also
+ * get the semantic heuristics selected by {@link isLoopGuardedModel}. The guard
+ * injects an abort signal into the provider call so a detected loop tears down
+ * the upstream, then wraps the returned stream. Bounding result-path re-samples
+ * lives in the result-awaiting caller.
  */
 export declare function withThinkingLoopGuard<O extends {
     signal?: AbortSignal;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "17.3.4",
+	"version": "17.3.7",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -38,10 +38,10 @@
 	},
 	"dependencies": {
 		"@bufbuild/protobuf": "^2.12.1",
-		"@oh-my-pi/omptype": "17.3.4",
-		"@oh-my-pi/pi-catalog": "17.3.4",
-		"@oh-my-pi/pi-utils": "17.3.4",
-		"@oh-my-pi/pi-wire": "17.3.4"
+		"@oh-my-pi/omptype": "17.3.7",
+		"@oh-my-pi/pi-catalog": "17.3.7",
+		"@oh-my-pi/pi-utils": "17.3.7",
+		"@oh-my-pi/pi-wire": "17.3.7"
 	},
 	"devDependencies": {
 		"@bufbuild/protoc-gen-es": "^2.12.1",

package/src/auth-storage.ts

@@ -53,7 +53,7 @@ import { cursorUsageProvider } from "./usage/cursor";
 import { googleGeminiCliUsageProvider } from "./usage/gemini";
 import { githubCopilotUsageProvider } from "./usage/github-copilot";
 import { antigravityRankingStrategy, antigravityUsageProvider } from "./usage/google-antigravity";
-import { kimiUsageProvider } from "./usage/kimi";
+import { kimiRankingStrategy, kimiUsageProvider } from "./usage/kimi";
 import { minimaxCodeUsageProvider } from "./usage/minimax-code";
 import { ollamaCloudUsageProvider, ollamaUsageProvider } from "./usage/ollama";
 import { codexRankingStrategy, openaiCodexUsageProvider } from "./usage/openai-codex";
@@ -1082,6 +1082,7 @@ const DEFAULT_RANKING_STRATEGIES = new Map<Provider, CredentialRankingStrategy>(
 	["openai-codex", codexRankingStrategy],
 	["anthropic", claudeRankingStrategy],
 	["google-antigravity", antigravityRankingStrategy],
+	["kimi-code", kimiRankingStrategy],
 	["zai", zaiRankingStrategy],
 	["opencode-go", opencodeGoRankingStrategy],
 ]);
@@ -2680,18 +2681,32 @@ export class AuthStorage {
 	}
 
 	/**
-	 * Check if any form of auth is configured for a provider.
-	 * Unlike getApiKey(), this doesn't refresh OAuth tokens.
+	 * Dedicated auth for default-model availability (picker / `getAvailable`).
+	 * Unlike {@link getApiKey}, this does not refresh OAuth tokens, and unlike
+	 * {@link hasResolvableAuth} it ignores cross-provider env aliases so
+	 * `XAI_API_KEY` does not auto-select SuperGrok (`xai-oauth`).
 	 */
 	hasAuth(provider: string): boolean {
 		if (this.#runtimeOverrides.has(provider)) return true;
 		if (this.#configOverrides.has(provider)) return true;
 		if (this.#getCredentialsForProvider(provider).length > 0) return true;
-		if (getEnvApiKey(provider)) return true;
+		if (this.#hasDedicatedEnvAuth(provider)) return true;
 		if (this.#fallbackResolver?.(provider)) return true;
 		return false;
 	}
 
+	/**
+	 * Whether a request could resolve a key for this provider, including
+	 * cross-provider env aliases (`xai-oauth` borrowing `XAI_API_KEY`).
+	 * Use this for explicit model preflight (`xai-oauth/grok-4.6`); use
+	 * {@link hasAuth} for auto-availability so the default picker stays on
+	 * paid `xai` when only `XAI_API_KEY` is set.
+	 */
+	hasResolvableAuth(provider: string): boolean {
+		if (this.hasAuth(provider)) return true;
+		return Boolean(getEnvApiKey(provider));
+	}
+
 	/**
 	 * True iff a dedicated, non-env credential source is configured for this
 	 * provider — i.e. anything in the cascade EXCEPT `getEnvApiKey(provider)`.
@@ -2711,6 +2726,22 @@ export class AuthStorage {
 		return false;
 	}
 
+	/**
+	 * Env auth that belongs to this provider, not a cross-provider alias.
+	 *
+	 * `getEnvApiKey("xai-oauth")` also accepts `XAI_API_KEY` so an explicit
+	 * `xai-oauth/…` stream can still borrow the paid key. Availability and
+	 * origin must not: otherwise an API-key-only setup marks SuperGrok as
+	 * signed in and `pickDefaultAvailableModel` prefers `xai-oauth/grok-4.6`
+	 * over paid `xai/grok-4.6`.
+	 */
+	#hasDedicatedEnvAuth(provider: string): boolean {
+		if (provider === "xai-oauth") {
+			return Boolean($env.XAI_OAUTH_TOKEN?.trim());
+		}
+		return Boolean(getEnvApiKey(provider));
+	}
+
 	/**
 	 * Classify where a provider's auth comes from, following the same precedence
 	 * as {@link AuthStorage.getApiKey}: runtime override → config override →
@@ -2727,7 +2758,7 @@ export class AuthStorage {
 		if (stored.some(credential => credential.type === "api_key" && credential.source === "login")) {
 			return { kind: "api_key" };
 		}
-		if (getEnvApiKey(provider)) return { kind: "env", envVar: getEnvApiKeyName(provider) };
+		if (this.#hasDedicatedEnvAuth(provider)) return { kind: "env", envVar: getEnvApiKeyName(provider) };
 		if (stored.some(credential => credential.type === "api_key")) return { kind: "api_key" };
 		if (this.#fallbackResolver?.(provider)) return { kind: "fallback" };
 		return undefined;

package/src/error/flags.ts

@@ -9,6 +9,7 @@ import {
 } from "./classes";
 import {
 	isAccountScopedCapText,
+	isDashScopeTokenLimitText,
 	isOpaqueStatusBody,
 	isUsageLimitStatus,
 	matchesUsageLimitText,
@@ -106,7 +107,7 @@ const TRANSIENT_ENVELOPE_PATTERN = /anthropic stream envelope error:/i;
 const TRANSIENT_ENVELOPE_BEFORE_START_PATTERN = /before message_start/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|429|500|502|503|504|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)|malformed.?function.?call/i;
+	/\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|429|500|502|503|504|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;
 const AUTH_FAILURE_PATTERN =
 	/\b(?:401|403|unauthorized|forbidden|authentication|auth[_ ]?unavailable|no auth available|(?:invalid|no)[_ ]?api[_ ]?key)\b/i;
 const MALFORMED_FUNCTION_CALL_PATTERN = /\bmalformed.?function.?call\b/i;
@@ -441,7 +442,10 @@ export function classify(error: unknown, api?: Api): number {
 		} else if (link instanceof ProviderHttpError) {
 			let linkKinds = 0;
 			const { status: codeStatus, code } = link;
-			if (code === "usage_limit_reached" || code === "insufficient_quota") {
+			if (
+				code === "usage_limit_reached" ||
+				(code === "insufficient_quota" && !isDashScopeTokenLimitText(link.message))
+			) {
 				linkKinds |= Flag.UsageLimit;
 			}
 			if (code === "overloaded_error" || code === "rate_limit_error") {

package/src/error/rate-limit.ts

@@ -69,6 +69,26 @@ const CN_TRANSIENT_CAP_PATTERN =
 // isOpaqueStatusBody so CN transients stay in the provider backoff lane instead
 // of rotating through the opaque-429 fallback.
 const CN_THROTTLE_PATTERN = /速率(?:限制|过快)|频率(?:过高|过快)|过于频繁|稍后[重再]试/;
+// DashScope / Bailian (Alibaba Model Studio) reports its per-minute token
+// throttle (429 Throttling.AllocationQuota, type `insufficient_quota`) with
+// OpenAI-compatible billing wording — "You exceeded your current quota,
+// please check your plan and billing details. … (type=insufficient_quota
+// param=insufficient_quota)" — and links the error-code doc's `token-limit`
+// anchor. Per that doc section the error is a transient TPM/TPS cap that
+// clears within the minute window, not an account-local quota exhaustion.
+// The same doc anchor also covers permanent errors such as "Free allocated
+// quota exceeded", so require both the anchor and the exact throttle wording.
+// The identical wording WITHOUT the anchor stays quota-exhausted (OpenAI's
+// real account-quota error uses the same sentence).
+const DASHSCOPE_TOKEN_LIMIT_DOC_PATTERN = /error-code[^()\s]*#token-limit/i;
+const DASHSCOPE_TOKEN_LIMIT_MESSAGE_PATTERN =
+	/\byou exceeded your current quota, please check your plan and billing details\b/i;
+/** True for DashScope/Bailian's documented OpenAI-compatible TPM/TPS throttle. */
+export function isDashScopeTokenLimitText(errorMessage: string): boolean {
+	return (
+		DASHSCOPE_TOKEN_LIMIT_DOC_PATTERN.test(errorMessage) && DASHSCOPE_TOKEN_LIMIT_MESSAGE_PATTERN.test(errorMessage)
+	);
+}
 
 const GOOGLE_RPC_ERROR_INFO_TYPE = "type.googleapis.com/google.rpc.ErrorInfo";
 const LONG_RATE_LIMIT_DELAY_MS = 5 * 60 * 1000;
@@ -133,8 +153,9 @@ function isQuotaExhaustedReason(reason: RateLimitReason): boolean {
 /**
  * Classify a rate-limit error message into a reason category.
  * Priority order: explicit details in a resource-exhausted error > QUOTA
- * (Antigravity "quota will reset") > CONCURRENT_LIMIT > MODEL_CAPACITY >
- * QUOTA (account) > RATE_LIMIT > QUOTA (generic) > SERVER_ERROR > bare resource-exhausted > UNKNOWN.
+ * (Antigravity "quota will reset") > CN quota > DASHSCOPE_TOKEN_LIMIT (TPM/TPS
+ * throttle) > CONCURRENT_LIMIT > MODEL_CAPACITY > QUOTA (account) > RATE_LIMIT >
+ * QUOTA (generic) > SERVER_ERROR > bare resource-exhausted > UNKNOWN.
  *
  * Bare "resource exhausted" / "resource_exhausted" maps to MODEL_CAPACITY (transient, short wait).
  * Explicit details such as "quota exceeded" retain their normal classification.
@@ -162,6 +183,13 @@ export function parseRateLimitReason(errorMessage: string): RateLimitReason {
 		return "QUOTA_EXHAUSTED";
 	}
 
+	// DashScope/Bailian TPM/TPS throttle: billing-worded like OpenAI's account
+	// quota, but the doc anchor marks it a per-minute token cap that clears on
+	// its own — short backoff on the same credential, never rotation/block.
+	if (isDashScopeTokenLimitText(errorMessage)) {
+		return "RATE_LIMIT_EXCEEDED";
+	}
+
 	if (CONCURRENT_LIMIT_PATTERN.test(errorMessage)) {
 		return "CONCURRENT_LIMIT";
 	}
@@ -342,6 +370,7 @@ export function isOpaqueStatusBody(message: string): boolean {
 export function matchesUsageLimitText(errorMessage: string): boolean {
 	const structuredReason = parseGoogleRpcRateLimitReason(errorMessage);
 	if (structuredReason !== undefined) return isQuotaExhaustedReason(structuredReason);
+	if (isDashScopeTokenLimitText(errorMessage)) return false;
 	return (
 		USAGE_LIMIT_PATTERN.test(errorMessage) ||
 		(CN_QUOTA_EXHAUSTED_PATTERN.test(errorMessage) && !CN_TRANSIENT_CAP_PATTERN.test(errorMessage)) ||

package/src/index.ts

@@ -6,6 +6,7 @@ export * from "./auth-gateway/types";
 export * from "./auth-retry";
 export * from "./auth-storage";
 export * from "./error/rate-limit";
+export * from "./oneshot-retry";
 export * from "./provider-details";
 export * from "./providers/anthropic";
 export * from "./providers/anthropic-client";