dsh-plugin-subscriptions 0.5.3 → 0.6.0

package/lib/providers/common.d.ts

@@ -5,8 +5,8 @@
  * Concurrent refreshes for one provider coalesce behind a single in-flight
  * promise (`inflight`), so a rotating refresh token is never spent twice.
  */
-import { LlmError } from '@deepseek-ai/dsh-llm';
-import type { ReasoningEffortId } from '@deepseek-ai/dsh-llm';
+import { LlmError, ReasoningEffortId } from '@deepseek-ai/dsh-llm';
+import type { RateLimitResetReader } from './rate-limit.js';
 /** One configured model catalog entry. */
 export interface ModelEntry {
     /** Wire model id; must be non-empty. */
@@ -33,14 +33,34 @@ export interface ModelEntry {
  * @returns the validated entries.
  */
 export declare function validateModels(models: readonly ModelEntry[], label: string): ModelEntry[];
+/** Optional per-call hooks {@link httpLlmError} uses to read a rate-limit window. */
+export interface HttpLlmErrorOptions {
+    /**
+     * The calling provider's reader for the instant its rate-limit window
+     * reopens. Consulted on a 429 only, and there ahead of the generic
+     * `retry-after` header, because a provider's own field names the window while
+     * `retry-after` often names a short backoff.
+     */
+    rateLimitReset?: RateLimitResetReader;
+    /** Diagnostic sink for a 429 that disclosed no reset instant this code recognizes. */
+    onWarn?: (message: string) => void;
+}
 /**
- * Build an LlmError from a non-2xx provider response, reading and truncating
- * the body for the message and mapping the status to a stable code.
+ * Build an LlmError from a non-2xx provider response, mapping the status to a
+ * stable code and, for a rate-limited request, the disclosed reset instant to
+ * the `providerRetryAfterMs` the retry plugin waits out.
+ *
+ * A 429 classifies as `RATE_LIMIT` on the strength of the status alone, ahead
+ * of the quota-wording check. On these routes there is no terminal quota to
+ * distinguish: a subscription has no balance to top up, only a window that
+ * reopens, and providers announce an exhausted window with wording
+ * (`usage_limit_reached`) the shared classifier reads as permanent.
  * @param response - the failed response.
  * @param label - diagnostic prefix naming the provider API.
+ * @param options - the calling provider's rate-limit reader and warning sink.
  * @returns the classified error.
  */
-export declare function httpLlmError(response: Response, label: string): Promise<LlmError>;
+export declare function httpLlmError(response: Response, label: string, options?: HttpLlmErrorOptions): Promise<LlmError>;
 /** An idle watchdog: aborts its signal when no SSE activity arrives within the timeout. */
 export interface IdleWatchdog {
     /** Signal to pass to fetch and body reads; aborts on caller cancel or idle expiry. */
@@ -76,7 +96,15 @@ export declare class OAuthEndpointError extends Error {
     readonly status: number;
     /** The provider's OAuth `error` code (e.g. `invalid_grant`), when present. */
     readonly oauthCode: string | undefined;
-    constructor(message: string, status: number, oauthCode?: string);
+    /**
+     * The endpoint's `retry-after`, in ms, when it sent one. Usage/models
+     * endpoints reuse this error type and can rate-limit progressively (each
+     * hit within the window extends the next one), so a caller retrying on a
+     * fixed schedule instead of honoring this can keep an account locked out
+     * indefinitely.
+     */
+    readonly retryAfterMs: number | undefined;
+    constructor(message: string, status: number, oauthCode?: string, retryAfterMs?: number);
 }
 /**
  * Read an OAuth JSON error body into an {@link OAuthEndpointError}.
@@ -203,6 +231,42 @@ export interface DiscoveredModel {
      */
     copilotResponses?: boolean;
 }
+/** Display name for a wire reasoning-effort identifier. */
+export declare function effortDisplayName(effort: string): string;
+/** The reasoning-block shape every caller passes to {@link mergeReasoning}. */
+export interface ReasoningBlock {
+    efforts: readonly {
+        id: ReasoningEffortId;
+        name: string;
+        description?: string;
+    }[];
+    defaultEffort?: ReasoningEffortId;
+}
+/**
+ * Fold a configured per-model default effort into a reasoning block, keeping
+ * the DSH runtime invariant `defaultEffort ∈ efforts` (the runtime rejects an
+ * unknown default with `INVALID_MODEL_REASONING`).
+ *
+ * A configured level the base set does not advertise is *dropped*, not
+ * appended: for claude/grok/copilot the base is the provider's live catalog,
+ * i.e. the truth about what the model accepts, so honouring a stale override
+ * would put an unsupported effort on every single request instead of letting
+ * the harness reject it before provider I/O. The override then simply falls
+ * back to the provider's own default until the user picks a level the catalog
+ * still lists.
+ *
+ * `extendable` opts into the opposite rule for a base that is a *built-in
+ * fallback* rather than discovered truth (codex, whose static effort list is
+ * known to trail the backend): there, appending the configured level is how a
+ * newly shipped tier becomes selectable at all.
+ * @param configuredDefault - the user-configured default effort id, or undefined.
+ * @param base - the discovered/built-in reasoning block, or undefined.
+ * @param options - `extendable` marks the base as a fallback that may be extended.
+ * @returns the merged block, or undefined when neither side contributes one.
+ */
+export declare function mergeReasoning(configuredDefault: string | undefined, base: ReasoningBlock | undefined, options?: {
+    extendable?: boolean;
+}): DiscoveredModel['reasoning'] | undefined;
 /**
  * First account catalog that lists `model` (callers pass default-first).
  * One failing lookup sits that account out so a sibling's metadata still

package/lib/providers/common.js

@@ -5,7 +5,8 @@
  * Concurrent refreshes for one provider coalesce behind a single in-flight
  * promise (`inflight`), so a rotating refresh token is never spent twice.
  */
-import { CONTEXT_WINDOW_EXCEEDED_CODE, isContextWindowExceededError, isQuotaExceededError, LlmError, QUOTA_EXCEEDED_CODE, } from '@deepseek-ai/dsh-llm';
+import { CONTEXT_WINDOW_EXCEEDED_CODE, isContextWindowExceededError, isQuotaExceededError, LlmError, QUOTA_EXCEEDED_CODE, ReasoningEffortId, } from '@deepseek-ai/dsh-llm';
+import { rateLimitDiagnostics, retryAfterInstant, waitFromReset } from './rate-limit.js';
 /**
  * Validate a configured model catalog (mirrors llm-deepseek's resolveModels).
  * @param models - raw configured entries.
@@ -49,31 +50,41 @@ export function validateModels(models, label) {
     });
 }
 /**
- * Build an LlmError from a non-2xx provider response, reading and truncating
- * the body for the message and mapping the status to a stable code.
+ * Build an LlmError from a non-2xx provider response, mapping the status to a
+ * stable code and, for a rate-limited request, the disclosed reset instant to
+ * the `providerRetryAfterMs` the retry plugin waits out.
+ *
+ * A 429 classifies as `RATE_LIMIT` on the strength of the status alone, ahead
+ * of the quota-wording check. On these routes there is no terminal quota to
+ * distinguish: a subscription has no balance to top up, only a window that
+ * reopens, and providers announce an exhausted window with wording
+ * (`usage_limit_reached`) the shared classifier reads as permanent.
  * @param response - the failed response.
  * @param label - diagnostic prefix naming the provider API.
+ * @param options - the calling provider's rate-limit reader and warning sink.
  * @returns the classified error.
  */
-export async function httpLlmError(response, label) {
+export async function httpLlmError(response, label, options = {}) {
     let body = '';
     try {
-        body = (await response.text()).slice(0, 500);
+        body = await response.text();
     }
     catch {
         // Only swallow error-body reading: the HTTP status still identifies the failure.
     }
-    const message = body.length > 0
-        ? `${label} error (HTTP ${String(response.status)}): ${body}`
+    // Truncated for display only; the readers below need the whole body to parse it.
+    const shown = body.slice(0, 500);
+    const message = shown.length > 0
+        ? `${label} error (HTTP ${String(response.status)}): ${shown}`
         : `${label} error (HTTP ${String(response.status)})`;
     let code;
     if (response.status === 401 || response.status === 403)
         code = 'AUTH';
-    else if (isQuotaExceededError(body))
-        code = QUOTA_EXCEEDED_CODE;
     else if (response.status === 429)
         code = 'RATE_LIMIT';
-    else if (response.status === 400 && isContextWindowExceededError(body))
+    else if (isQuotaExceededError(shown))
+        code = QUOTA_EXCEEDED_CODE;
+    else if (response.status === 400 && isContextWindowExceededError(shown))
         code = CONTEXT_WINDOW_EXCEEDED_CODE;
     else if (response.status === 408 || response.status === 504)
         code = 'TIMEOUT';
@@ -81,18 +92,43 @@ export async function httpLlmError(response, label) {
         code = 'SERVER';
     else
         code = `HTTP_${String(response.status)}`;
-    const retryAfter = response.headers.get('retry-after');
-    let providerRetryAfterMs;
-    if (retryAfter !== null) {
-        const seconds = Number(retryAfter);
-        if (Number.isFinite(seconds) && seconds > 0)
-            providerRetryAfterMs = seconds * 1000;
+    const now = Date.now();
+    // The provider's reader runs on a 429 and nowhere else. Providers attach
+    // their rate-limit headers to every response, so reading them on a transient
+    // 500 would report the current window's rollover — hours out — as the delay
+    // before retrying a failure that has nothing to do with the window, and the
+    // retry plugin honours `providerRetryAfterMs` for every retryable code.
+    // `retry-after` stays readable on any status: there it is a real backoff the
+    // provider asked for (a 503 shedding load), not a window snapshot.
+    //
+    // On a 429 the provider's own field wins outright rather than being raced
+    // against `retry-after`: a rejected window often carries both, and the
+    // generic header then names a short backoff that would burn the retry budget
+    // re-hitting the same closed window.
+    const rateLimited = response.status === 429;
+    const reset = rateLimited
+        ? options.rateLimitReset?.(response, body, now) ?? retryAfterInstant(response, now)
+        : retryAfterInstant(response, now);
+    if (reset === undefined && rateLimited) {
+        options.onWarn?.(`${label}: ${rateLimitDiagnostics(response, body)}`);
     }
     return new LlmError(message, code, {
         status: response.status,
-        ...providerRetryAfterMs === undefined ? {} : { providerRetryAfterMs },
+        ...reset === undefined ? {} : { providerRetryAfterMs: waitFromReset(reset, now) },
     });
 }
+/**
+ * Parse a response's `retry-after` header (seconds) into milliseconds.
+ * @param response - the failed response.
+ * @returns the delay in ms, or undefined when absent/unusable.
+ */
+function parseRetryAfterMs(response) {
+    const retryAfter = response.headers.get('retry-after');
+    if (retryAfter === null)
+        return undefined;
+    const seconds = Number(retryAfter);
+    return Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : undefined;
+}
 /**
  * Create an idle watchdog chained to the caller's signal.
  * @param caller - the request's own abort signal, when present.
@@ -154,11 +190,20 @@ export class OAuthEndpointError extends Error {
     status;
     /** The provider's OAuth `error` code (e.g. `invalid_grant`), when present. */
     oauthCode;
-    constructor(message, status, oauthCode) {
+    /**
+     * The endpoint's `retry-after`, in ms, when it sent one. Usage/models
+     * endpoints reuse this error type and can rate-limit progressively (each
+     * hit within the window extends the next one), so a caller retrying on a
+     * fixed schedule instead of honoring this can keep an account locked out
+     * indefinitely.
+     */
+    retryAfterMs;
+    constructor(message, status, oauthCode, retryAfterMs) {
         super(message);
         this.name = 'OAuthEndpointError';
         this.status = status;
         this.oauthCode = oauthCode;
+        this.retryAfterMs = retryAfterMs;
     }
 }
 /**
@@ -181,7 +226,7 @@ export async function oauthEndpointError(response, label) {
     const message = detail.length > 0
         ? `${label} token endpoint error (HTTP ${String(response.status)}): ${detail}`
         : `${label} token endpoint error (HTTP ${String(response.status)})`;
-    return new OAuthEndpointError(message, response.status, oauthCode);
+    return new OAuthEndpointError(message, response.status, oauthCode, parseRetryAfterMs(response));
 }
 /**
  * Per-provider session freshness: loads the stored session, refreshes
@@ -286,6 +331,60 @@ export function withTimeout(work, timeoutMs) {
         aborted,
     ]);
 }
+/** Display name for a wire reasoning-effort identifier. */
+export function effortDisplayName(effort) {
+    return effort === 'xhigh' ? 'Extra High' : effort.charAt(0).toUpperCase() + effort.slice(1);
+}
+/**
+ * Fold a configured per-model default effort into a reasoning block, keeping
+ * the DSH runtime invariant `defaultEffort ∈ efforts` (the runtime rejects an
+ * unknown default with `INVALID_MODEL_REASONING`).
+ *
+ * A configured level the base set does not advertise is *dropped*, not
+ * appended: for claude/grok/copilot the base is the provider's live catalog,
+ * i.e. the truth about what the model accepts, so honouring a stale override
+ * would put an unsupported effort on every single request instead of letting
+ * the harness reject it before provider I/O. The override then simply falls
+ * back to the provider's own default until the user picks a level the catalog
+ * still lists.
+ *
+ * `extendable` opts into the opposite rule for a base that is a *built-in
+ * fallback* rather than discovered truth (codex, whose static effort list is
+ * known to trail the backend): there, appending the configured level is how a
+ * newly shipped tier becomes selectable at all.
+ * @param configuredDefault - the user-configured default effort id, or undefined.
+ * @param base - the discovered/built-in reasoning block, or undefined.
+ * @param options - `extendable` marks the base as a fallback that may be extended.
+ * @returns the merged block, or undefined when neither side contributes one.
+ */
+export function mergeReasoning(configuredDefault, base, options) {
+    const detached = base === undefined
+        ? undefined
+        : {
+            efforts: [...base.efforts],
+            ...(base.defaultEffort === undefined ? {} : { defaultEffort: base.defaultEffort }),
+        };
+    if (configuredDefault === undefined)
+        return detached;
+    const effort = ReasoningEffortId(configuredDefault);
+    if (base === undefined) {
+        // No capability information at all (catalog unavailable, or a model the
+        // catalog does not cover). Inventing a reasoning block here would claim a
+        // capability nobody advertised; only a fallback-based provider may.
+        return options?.extendable === true
+            ? { efforts: [{ id: effort, name: effortDisplayName(effort) }], defaultEffort: effort }
+            : undefined;
+    }
+    if (base.efforts.some(entry => entry.id === effort)) {
+        return { efforts: [...base.efforts], defaultEffort: effort };
+    }
+    if (options?.extendable !== true)
+        return detached;
+    return {
+        efforts: [...base.efforts, { id: effort, name: effortDisplayName(effort) }],
+        defaultEffort: effort,
+    };
+}
 /**
  * First account catalog that lists `model` (callers pass default-first).
  * One failing lookup sits that account out so a sibling's metadata still

package/lib/providers/copilot.d.ts

@@ -22,6 +22,7 @@ import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
 import type { ReasoningReplayItem, ResponsesRequestInput, ResponsesStreamEvent } from '../translate/responses.js';
 import { AccountTokenManager } from './accounts.js';
 import type { CatalogPersistence, DiscoveredModel, FetchFn, ModelEntry } from './common.js';
+import type { RateLimitWait } from './rate-limit.js';
 /**
  * Client id of the VS Code Copilot Chat GitHub App (pi-mono and
  * copilot2api-go use the same value): the app is pre-authorized for the
@@ -230,6 +231,14 @@ export interface CopilotAdapterOptions {
     resolveAttachments?: () => AttachmentStore | undefined;
     /** Durable catalog store seeding capability metadata across restarts. */
     catalogStore?: CatalogPersistence;
+    /** How long this route may hold a turn open waiting for a rate-limit window; defaults to waiting on, six-hour ceiling. */
+    rateLimit?: RateLimitWait;
+    /**
+     * Per-model default reasoning effort override (the Settings page's picker).
+     * Returns the user-configured default for one model, or undefined to follow
+     * the provider's own default.
+     */
+    defaultEffortOf?: (model: string) => string | undefined;
 }
 /** Copilot wire adapter: one instance serves the `copilot` provider route. */
 export declare class CopilotAdapter extends LlmAdapter {
@@ -263,6 +272,7 @@ export declare class CopilotAdapter extends LlmAdapter {
     /** Persisted cache for the default account; a throwaway cache for any other. */
     private catalogFor;
     providerInfo(provider: string): LlmProviderInfo;
+    providerRetryPolicy(provider: string): import("@deepseek-ai/dsh-llm").ResolvedRetryPolicy;
     private staticModels;
     listModels(provider: string): Promise<readonly LlmModelInfo[]>;
     /** The provider's own catalog: union of every account, or one account when named. */

package/lib/providers/copilot.js

@@ -17,9 +17,10 @@ import { EMPTY_RESPONSE_CODE, errorChain, LlmAdapter, LlmError, ReasoningEffortI
 import { resolveImages } from '../translate/resolved.js';
 import { streamChatCompletions, toChatMessages, toChatTools, } from '../translate/chat-completions.js';
 import { streamResponses, toResponsesInput, toResponsesTools } from '../translate/responses.js';
-import { httpLlmError, idleWatchdog, mapFetchFailure, ModelCatalogCache, discoverAcrossAccounts, discoverOrRetryAuth, isDiscoveryAborted, isMissingOrInvalidCredential, oauthEndpointError, OAuthEndpointError, } from './common.js';
+import { httpLlmError, idleWatchdog, mapFetchFailure, mergeReasoning, ModelCatalogCache, discoverAcrossAccounts, discoverOrRetryAuth, isDiscoveryAborted, isMissingOrInvalidCredential, oauthEndpointError, OAuthEndpointError, } from './common.js';
 import { AccountTokenManager, DISCOVERY_TIMEOUT_MS, unionAccountCatalogs } from './accounts.js';
 import { proxiedFetch } from '../http.js';
+import { DEFAULT_RATE_LIMIT_WAIT, DEFAULT_RETRY, subscriptionRetryPolicy, } from './rate-limit.js';
 /**
  * Client id of the VS Code Copilot Chat GitHub App (pi-mono and
  * copilot2api-go use the same value): the app is pre-authorized for the
@@ -574,6 +575,9 @@ export class CopilotAdapter extends LlmAdapter {
     providerInfo(provider) {
         return { id: provider, name: 'GitHub Copilot' };
     }
+    providerRetryPolicy(provider) {
+        return subscriptionRetryPolicy(DEFAULT_RETRY, this.options.rateLimit ?? DEFAULT_RATE_LIMIT_WAIT, `copilot: provider "${provider}" retryPolicy`);
+    }
     staticModels(provider) {
         return this.options.models.map(model => ({
             provider,
@@ -768,6 +772,13 @@ export class CopilotAdapter extends LlmAdapter {
     async resolveOwnModel(provider, model) {
         const discovered = await this.discovered(model);
         const configured = this.options.models.find(entry => entry.id === model);
+        // Efforts come from the discovered catalog's reasoning_effort array; a
+        // model that did not advertise one exposes none, so the harness rejects
+        // an explicit effort before provider I/O instead of the API 400ing
+        // (Copilot returns invalid_request_body for models that cannot reason).
+        // A configured default effort still merges in: the picker then
+        // preselects it even for models the catalog does not cover.
+        const reasoning = mergeReasoning(this.options.defaultEffortOf?.(model), discovered?.reasoning);
         return {
             provider,
             id: model,
@@ -776,11 +787,7 @@ export class CopilotAdapter extends LlmAdapter {
             inputModalities: discovered?.inputModalities ?? configured?.inputModalities ?? ['text'],
             context: { contextWindow: discovered?.contextWindow ?? configured?.contextWindow ?? COPILOT_CONTEXT_WINDOW },
             defaultMaxTokens: configured?.maxTokens ?? COPILOT_DEFAULT_MAX_TOKENS,
-            // Efforts come from the discovered catalog's reasoning_effort array; a
-            // model that did not advertise one exposes none, so the harness rejects
-            // an explicit effort before provider I/O instead of the API 400ing
-            // (Copilot returns invalid_request_body for models that cannot reason).
-            ...discovered?.reasoning === undefined ? {} : { reasoning: discovered.reasoning },
+            ...reasoning === undefined ? {} : { reasoning },
         };
     }
     async *stream(options) {
@@ -819,8 +826,14 @@ export class CopilotAdapter extends LlmAdapter {
                 session = await this.options.tokens.session(account, true);
                 response = await this.request(options, session, watchdog.signal, wire, scope);
             }
-            if (!response.ok)
-                throw await httpLlmError(response, 'copilot API');
+            if (!response.ok) {
+                throw await httpLlmError(response, 'copilot API', {
+                    // Copilot has no provider-specific reset reader yet. The shared
+                    // mapper still honors its generic retry-after header and warns with
+                    // rate-limit-shaped headers/body when GitHub sends another signal.
+                    ...this.options.onWarn === undefined ? {} : { onWarn: this.options.onWarn },
+                });
+            }
             if (response.body === null) {
                 throw new LlmError('copilot API returned no response body', EMPTY_RESPONSE_CODE);
             }

package/lib/providers/grok.d.ts

@@ -11,11 +11,23 @@ import type { PoolAdapter } from './pool.js';
 import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
 import { AccountTokenManager } from './accounts.js';
 import type { CatalogPersistence, DiscoveredModel, FetchFn, ModelEntry, ProviderUsage } from './common.js';
+import type { RateLimitResetReader, RateLimitWait } from './rate-limit.js';
 export declare const GROK_CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828";
 export declare const GROK_DISCOVERY_URL = "https://auth.x.ai/.well-known/openid-configuration";
 export declare const GROK_API_URL = "https://api.x.ai/v1/responses";
 /** Refresh when the access token has less than this much life left. */
 export declare const GROK_PREEMPT_MS: number;
+/**
+ * Reads the reset instant of the xAI window that rejected a request.
+ *
+ * Body only. xAI serves the OpenAI-compatible `x-ratelimit-reset-*` family,
+ * whose values are rollover durations (`6m0s`) present on every response, one
+ * per bucket — on a 429 the earliest of them is usually a bucket with room
+ * (`0s` for the request bucket while the token bucket is the one exhausted),
+ * which would burn the whole retry budget in seconds. They reach the operator
+ * through `rateLimitDiagnostics` instead.
+ */
+export declare const grokRateLimitReset: RateLimitResetReader;
 /** Discovered OIDC endpoints for the xAI authorization server. */
 export interface GrokDiscovery {
     authorizationEndpoint: string;
@@ -132,6 +144,14 @@ export interface GrokAdapterOptions {
     resolveAttachments?: () => AttachmentStore | undefined;
     /** Durable catalog store seeding capability metadata across restarts. */
     catalogStore?: CatalogPersistence;
+    /**
+     * Per-model default reasoning effort override (the Settings page's picker).
+     * Returns the user-configured default for one model, or undefined to follow
+     * the provider's own default.
+     */
+    defaultEffortOf?: (model: string) => string | undefined;
+    /** How long this route may hold a turn open waiting for a rate-limit window; defaults to waiting on, six-hour ceiling. */
+    rateLimit?: RateLimitWait;
 }
 /** Grok wire adapter: one instance serves the `grok` provider route. */
 export declare class GrokAdapter extends LlmAdapter {
@@ -150,6 +170,7 @@ export declare class GrokAdapter extends LlmAdapter {
     private catalogFor;
     private listed;
     providerInfo(provider: string): LlmProviderInfo;
+    providerRetryPolicy(provider: string): import("@deepseek-ai/dsh-llm").ResolvedRetryPolicy;
     private staticModels;
     listModels(provider: string): Promise<readonly LlmModelInfo[]>;
     /** The provider's own catalog: union of every account, or one account when named. */

package/lib/providers/grok.js

@@ -7,9 +7,10 @@ import { attributionHeaders, EMPTY_RESPONSE_CODE, errorChain, LlmAdapter, LlmErr
 import { decodeJwtPayload } from '../auth/jwt.js';
 import { resolveImages } from '../translate/resolved.js';
 import { streamResponses, toResponsesInput, toResponsesTools } from '../translate/responses.js';
-import { httpLlmError, idleWatchdog, mapFetchFailure, ModelCatalogCache, discoverAcrossAccounts, discoverOrRetryAuth, isDiscoveryAborted, isMissingOrInvalidCredential, oauthEndpointError, OAuthEndpointError, } from './common.js';
+import { httpLlmError, idleWatchdog, mapFetchFailure, mergeReasoning, ModelCatalogCache, discoverAcrossAccounts, discoverOrRetryAuth, isDiscoveryAborted, isMissingOrInvalidCredential, oauthEndpointError, OAuthEndpointError, } from './common.js';
 import { AccountTokenManager, DISCOVERY_TIMEOUT_MS, unionAccountCatalogs } from './accounts.js';
 import { proxiedFetch } from '../http.js';
+import { DEFAULT_RATE_LIMIT_WAIT, DEFAULT_RETRY, jsonBody, resetFromFields, subscriptionRetryPolicy, } from './rate-limit.js';
 export const GROK_CLIENT_ID = 'b1a00492-073a-47ea-816f-4c329264a828';
 export const GROK_DISCOVERY_URL = 'https://auth.x.ai/.well-known/openid-configuration';
 export const GROK_API_URL = 'https://api.x.ai/v1/responses';
@@ -19,6 +20,19 @@ const GROK_CONTEXT_WINDOW = 256_000;
 const GROK_DEFAULT_MAX_TOKENS = 32_000;
 /** Refresh when the access token has less than this much life left. */
 export const GROK_PREEMPT_MS = 2 * 60_000;
+/** Body fields xAI uses to name a delay or reset. */
+const GROK_RESET_FIELDS = ['retry_after', 'retry_after_seconds', 'resets_at', 'reset_at'];
+/**
+ * Reads the reset instant of the xAI window that rejected a request.
+ *
+ * Body only. xAI serves the OpenAI-compatible `x-ratelimit-reset-*` family,
+ * whose values are rollover durations (`6m0s`) present on every response, one
+ * per bucket — on a 429 the earliest of them is usually a bucket with room
+ * (`0s` for the request bucket while the token bucket is the one exhausted),
+ * which would burn the whole retry budget in seconds. They reach the operator
+ * through `rateLimitDiagnostics` instead.
+ */
+export const grokRateLimitReset = (_response, body, now) => resetFromFields(jsonBody(body), GROK_RESET_FIELDS, now);
 /** A discovered URL must be https on x.ai or a subdomain; anything else is a hostile document. */
 function assertXaiEndpoint(url, field) {
     let parsed;
@@ -500,6 +514,9 @@ export class GrokAdapter extends LlmAdapter {
     providerInfo(provider) {
         return { id: provider, name: 'Grok (Subscription)' };
     }
+    providerRetryPolicy(provider) {
+        return subscriptionRetryPolicy(DEFAULT_RETRY, this.options.rateLimit ?? DEFAULT_RATE_LIMIT_WAIT, `grok: provider "${provider}" retryPolicy`);
+    }
     staticModels(provider) {
         return this.options.models.map(model => ({
             provider,
@@ -578,6 +595,12 @@ export class GrokAdapter extends LlmAdapter {
     async resolveOwnModel(provider, model) {
         const discovered = await this.discovered(model);
         const configured = this.options.models.find(entry => entry.id === model);
+        // Efforts come from the discovered CLI catalog; models it does not
+        // cover expose none, so the harness rejects explicit efforts before
+        // provider I/O instead of the API 400ing. A configured default effort
+        // still merges in: the picker then preselects it even for models the
+        // CLI catalog does not cover.
+        const reasoning = mergeReasoning(this.options.defaultEffortOf?.(model), discovered?.reasoning);
         return {
             provider,
             id: model,
@@ -586,10 +609,7 @@ export class GrokAdapter extends LlmAdapter {
             inputModalities: configured?.inputModalities ?? grokModalities(model),
             context: { contextWindow: discovered?.contextWindow ?? configured?.contextWindow ?? GROK_CONTEXT_WINDOW },
             defaultMaxTokens: configured?.maxTokens ?? GROK_DEFAULT_MAX_TOKENS,
-            // Efforts come from the discovered CLI catalog; models it does not
-            // cover expose none, so the harness rejects explicit efforts before
-            // provider I/O instead of the API 400ing.
-            ...discovered?.reasoning === undefined ? {} : { reasoning: discovered.reasoning },
+            ...reasoning === undefined ? {} : { reasoning },
         };
     }
     async *stream(options) {
@@ -614,8 +634,12 @@ export class GrokAdapter extends LlmAdapter {
                 session = await this.options.tokens.session(account, true);
                 response = await this.request(options, session, watchdog.signal);
             }
-            if (!response.ok)
-                throw await httpLlmError(response, 'grok API');
+            if (!response.ok) {
+                throw await httpLlmError(response, 'grok API', {
+                    rateLimitReset: grokRateLimitReset,
+                    ...this.options.onWarn === undefined ? {} : { onWarn: this.options.onWarn },
+                });
+            }
             if (response.body === null) {
                 throw new LlmError('grok API returned no response body', EMPTY_RESPONSE_CODE);
             }
@@ -646,6 +670,12 @@ export class GrokAdapter extends LlmAdapter {
             ...options.reasoningEffort !== undefined
                 ? { reasoning: { effort: String(options.reasoningEffort) } }
                 : {},
+            // Cache-affinity hint (mirrors codex): xAI caches prompts per server,
+            // and `prompt_cache_key` is the Responses-API signal that routes repeat
+            // requests back to the cache-holding shard — without it every turn's
+            // cache hit is shard-routing luck. The session id is the stable key
+            // xAI's own docs recommend.
+            ...options.sessionId !== undefined ? { prompt_cache_key: String(options.sessionId) } : {},
             store: false,
             stream: true,
         };

package/lib/providers/pool-usage.d.ts

@@ -43,14 +43,35 @@ export declare class PoolUsageTracker {
     /**
      * The quota view of one member. A cold cache awaits the first fetch; a
      * stale one answers immediately while the refresh serves the NEXT call
-     * (member selection must never block on the network mid-conversation).
+     * (member selection must never block on the network mid-conversation). A
+     * failure still cooling down degrades immediately with no network call.
      * @param member - the pool member to score (account resolved).
      * @returns availability plus the urgency score.
      */
     quotaFor(member: ConcretePoolMember): Promise<MemberQuota>;
+    /**
+     * Same cache as {@link quotaFor}, for direct display (the Settings page):
+     * the raw snapshot, or the original fetch error, instead of a routing
+     * score.
+     * @param provider - the account's provider.
+     * @param account - the account key.
+     * @param force - bypass a fresh cached SNAPSHOT for an honest re-check (the
+     *   manual Refresh button). A live failure cooldown is never bypassed —
+     *   retrying through it is exactly what turns a 429 into a permanent
+     *   lockout, so even a forced call still answers from the negative cache.
+     * @returns `{ supported: false }` when the provider has no usage fetcher.
+     */
+    snapshotFor(provider: ProviderId, account: string, force?: boolean): Promise<ProviderUsage>;
     /** Drop cached snapshots: one account, or a whole provider when `account` is omitted. */
     invalidate(provider: ProviderId, account?: string): void;
-    /** Run (or join) the single in-flight fetch for one account key. */
+    /**
+     * Run (or join) the single in-flight fetch for one account key, caching
+     * either outcome. A missing/invalid credential is deliberately NOT
+     * negative-cached: it costs no network round trip (the session lookup
+     * fails before the request goes out) and re-checking live means the
+     * member rejoins routing the instant its login is fixed, rather than
+     * waiting out a stale cooldown.
+     */
     private refresh;
     /** Score one member against a snapshot's windows. */
     private score;