dsh-subscriptions 0.1.2 → 0.1.4

package/lib/providers/common.js

@@ -7,7 +7,7 @@
  */
 import { createHash, randomUUID } from 'node:crypto';
 import { CONTEXT_WINDOW_EXCEEDED_CODE, isContextWindowExceededError, isQuotaExceededError, LlmError, QUOTA_EXCEEDED_CODE, ReasoningEffortId, } from '@deepseek-ai/dsh-llm';
-import { durationMs, rateLimitDiagnostics, retryAfterInstant, waitFromReset } from './rate-limit.js';
+import { durationMs, retryAfterInstant, waitFromReset } from './rate-limit.js';
 /**
  * Validate a configured model catalog (mirrors llm-deepseek's resolveModels).
  * @param models - raw configured entries.
@@ -50,6 +50,17 @@ export function validateModels(models, label) {
         };
     });
 }
+/**
+ * Provider failures can echo credentials or customer input in any format.
+ * Shape-based filtering cannot make arbitrary response text safe to display.
+ * Here, safe means this diagnostic carries no provider-controlled free text,
+ * not that secrets cannot exist elsewhere in the system. Keep raw responses
+ * internal for classification and reset parsing; display only local summaries.
+ * This deliberately loses model, parameter and plan details useful to support.
+ */
+function providerDiagnostic(summary, hasBody) {
+    return hasBody ? `${summary}: [provider response body omitted]` : summary;
+}
 /**
  * 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
@@ -73,11 +84,8 @@ export async function httpLlmError(response, label, options = {}) {
     catch {
         // Only swallow error-body reading: the HTTP status still identifies the failure.
     }
-    // Truncated for display only; the readers below need the whole body to parse it.
+    // Preserve the existing classification window; reset readers need the full body.
     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';
@@ -93,6 +101,7 @@ export async function httpLlmError(response, label, options = {}) {
         code = 'SERVER';
     else
         code = `HTTP_${String(response.status)}`;
+    const message = providerDiagnostic(`${label} error (HTTP ${String(response.status)}, ${code})`, body.length > 0);
     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
@@ -111,7 +120,8 @@ export async function httpLlmError(response, label, options = {}) {
         ? options.rateLimitReset?.(response, body, now) ?? googleQuotaReset(body, now) ?? retryAfterInstant(response, now)
         : retryAfterInstant(response, now);
     if (reset === undefined && rateLimited) {
-        options.onWarn?.(`${label}: ${rateLimitDiagnostics(response, body)}`);
+        // Header names and values are provider-controlled too; none are displayed.
+        options.onWarn?.(providerDiagnostic(`${label}: 429 disclosed no reset time; [provider response headers omitted]`, body.length > 0));
     }
     return new LlmError(message, code, {
         status: response.status,
@@ -246,9 +256,10 @@ export class OAuthEndpointError extends Error {
  */
 export async function oauthEndpointError(response, label) {
     let oauthCode;
-    let detail = '';
+    let body = '';
     try {
-        const parsed = await response.json();
+        body = await response.text();
+        const parsed = JSON.parse(body);
         if (typeof parsed.error === 'string') {
             oauthCode = parsed.error;
         }
@@ -256,20 +267,13 @@ export async function oauthEndpointError(response, label) {
             const nested = parsed.error;
             if (typeof nested.code === 'string' && nested.code.length > 0)
                 oauthCode = nested.code;
-            if (typeof nested.message === 'string')
-                detail = nested.message;
         }
-        if (typeof parsed.error_description === 'string')
-            detail = parsed.error_description;
-        if (detail.length === 0)
-            detail = oauthCode ?? '';
     }
     catch {
-        // Only swallow error-body parsing: the HTTP status still identifies the failure.
+        // Only swallow error-body reading/parsing: HTTP status still identifies the failure.
     }
-    const message = detail.length > 0
-        ? `${label} token endpoint error (HTTP ${String(response.status)}): ${detail}`
-        : `${label} token endpoint error (HTTP ${String(response.status)})`;
+    // oauthCode remains structural for auth classification, never display text.
+    const message = providerDiagnostic(`${label} token endpoint error (HTTP ${String(response.status)})`, body.length > 0);
     return new OAuthEndpointError(message, response.status, oauthCode, parseRetryAfterMs(response));
 }
 /**

package/lib/providers/copilot.d.ts

@@ -297,7 +297,8 @@ export declare class CopilotAdapter extends LlmAdapter {
      * account identity is the session's long-lived GitHub token (stable across
      * Copilot-token refreshes, different per GitHub login); the conversation is
      * the loop-stamped `sessionId`, falling back to the first message's id
-     * when a hand-built request carries no session stamp; the model separates
+     * when a hand-built request carries no session stamp. Identity-free
+     * requests have no replay scope; the model separates
      * wire families. A call id captured in one scope is invisible to every
      * other scope, so reused ids cannot leak reasoning across accounts,
      * conversations, or models.

package/lib/providers/copilot.js

@@ -677,7 +677,8 @@ export class CopilotAdapter extends LlmAdapter {
      * account identity is the session's long-lived GitHub token (stable across
      * Copilot-token refreshes, different per GitHub login); the conversation is
      * the loop-stamped `sessionId`, falling back to the first message's id
-     * when a hand-built request carries no session stamp; the model separates
+     * when a hand-built request carries no session stamp. Identity-free
+     * requests have no replay scope; the model separates
      * wire families. A call id captured in one scope is invisible to every
      * other scope, so reused ids cannot leak reasoning across accounts,
      * conversations, or models.
@@ -685,9 +686,11 @@ export class CopilotAdapter extends LlmAdapter {
     replayScope(tokenKey, options) {
         const conversation = options.sessionId !== undefined
             ? `session:${String(options.sessionId)}`
-            : options.messages[0] !== undefined
+            : options.messages[0]?.id !== undefined
                 ? `anchor:${String(options.messages[0].id)}`
-                : 'conversation:none';
+                : undefined;
+        if (conversation === undefined)
+            return undefined;
         return `${tokenKey}\u0000${conversation}\u0000${options.model}`;
     }
     /**
@@ -701,6 +704,8 @@ export class CopilotAdapter extends LlmAdapter {
      * per call.
      */
     captureReasoning(scope, callIds, items) {
+        if (scope === undefined)
+            return;
         let entries = this.replayByScope.get(scope);
         if (entries === undefined) {
             entries = new Map();
@@ -745,6 +750,8 @@ export class CopilotAdapter extends LlmAdapter {
      * degradation, never an error.
      */
     replayFor(scope, callId) {
+        if (scope === undefined)
+            return undefined;
         const entries = this.replayByScope.get(scope);
         const entry = entries?.get(callId);
         if (entries === undefined || entry === undefined)

package/lib/providers/grok.d.ts

@@ -25,8 +25,8 @@ export declare const GROK_PREEMPT_MS: number;
  * 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.
+ * which would burn the whole retry budget in seconds. The parsed body reset
+ * supplies the retry hint; diagnostics omit raw provider headers and body text.
  */
 export declare const grokRateLimitReset: RateLimitResetReader;
 /** Discovered OIDC endpoints for the xAI authorization server. */

package/lib/providers/grok.js

@@ -29,8 +29,8 @@ const GROK_RESET_FIELDS = ['retry_after', 'retry_after_seconds', 'resets_at', 'r
  * 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.
+ * which would burn the whole retry budget in seconds. The parsed body reset
+ * supplies the retry hint; diagnostics omit raw provider headers and body text.
  */
 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. */

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

@@ -1,3 +1,24 @@
 import type { ProviderUsage } from './common.js';
-/** MiniMax subscription quota, not the balance API for sk-api-* inference keys. */
+/**
+ * Read MiniMax subscription quota (M Plan and Token Plan), not the balance API
+ * that `sk-api-*` pay-as-you-go keys use.
+ *
+ * Each `model_remains` row can yield an interval window and a weekly window.
+ * A window needs a finite share: the explicit `*_remaining_percent` (the weekly
+ * one scaled by `weekly_boost_permille`), else the legacy counts. Time-based
+ * plans report zero counts beside the percentage for standard models, so the
+ * percentage stands on its own and a zero total does not hide the window.
+ * Windows that cannot be a finite bar are omitted rather than approximated:
+ * status 3 (unlimited, or no quota in the plan), a weekly pool boosted past
+ * 100% remaining, a percentage outside 0-100, and a row with neither a
+ * percentage nor positive counts. Start and end times are kept only when both
+ * are valid millisecond bounds.
+ * @param key - subscription key for the region; never copied into a result or error.
+ * @param region - `global` or `cn`, which selects the fixed quota host.
+ * @param http - fetch implementation (injectable for tests).
+ * @param signal - caller cancellation from the RPC transport.
+ * @returns the finite windows in the order the API lists them.
+ * @throws when the key is pay-as-you-go, the endpoint or its business status
+ *   fails, the body has no `model_remains`, or no window is a finite bar.
+ */
 export declare function fetchMiniMaxUsage(key: string, region: 'global' | 'cn', http?: typeof fetch, signal?: AbortSignal): Promise<ProviderUsage>;

package/lib/providers/minimax-usage.js

@@ -1,4 +1,36 @@
-/** MiniMax subscription quota, not the balance API for sk-api-* inference keys. */
+/**
+ * Used percentage from the legacy counts, read as the official CLI does when no
+ * explicit percentage exists: the count is the quota remaining. Undefined
+ * unless the total is a positive finite number, so a zero total never yields a
+ * bar.
+ */
+function usedFromCounts(total, count) {
+    return typeof total === 'number' && Number.isFinite(total) && total > 0 && typeof count === 'number'
+        ? (1 - count / total) * 100
+        : undefined;
+}
+/**
+ * Read MiniMax subscription quota (M Plan and Token Plan), not the balance API
+ * that `sk-api-*` pay-as-you-go keys use.
+ *
+ * Each `model_remains` row can yield an interval window and a weekly window.
+ * A window needs a finite share: the explicit `*_remaining_percent` (the weekly
+ * one scaled by `weekly_boost_permille`), else the legacy counts. Time-based
+ * plans report zero counts beside the percentage for standard models, so the
+ * percentage stands on its own and a zero total does not hide the window.
+ * Windows that cannot be a finite bar are omitted rather than approximated:
+ * status 3 (unlimited, or no quota in the plan), a weekly pool boosted past
+ * 100% remaining, a percentage outside 0-100, and a row with neither a
+ * percentage nor positive counts. Start and end times are kept only when both
+ * are valid millisecond bounds.
+ * @param key - subscription key for the region; never copied into a result or error.
+ * @param region - `global` or `cn`, which selects the fixed quota host.
+ * @param http - fetch implementation (injectable for tests).
+ * @param signal - caller cancellation from the RPC transport.
+ * @returns the finite windows in the order the API lists them.
+ * @throws when the key is pay-as-you-go, the endpoint or its business status
+ *   fails, the body has no `model_remains`, or no window is a finite bar.
+ */
 export async function fetchMiniMaxUsage(key, region, http = fetch, signal) {
     if (key.startsWith('sk-api-'))
         throw new Error('MiniMax requires a subscription key, not a pay-as-you-go key');
@@ -30,13 +62,11 @@ export async function fetchMiniMaxUsage(key, region, http = fetch, signal) {
             const boost = prefix === 'current_weekly' ? row.weekly_boost_permille ?? 1000 : 1000;
             if (typeof boost !== 'number' || !Number.isFinite(boost) || boost <= 0)
                 continue;
-            const total = row[`${prefix}_total_count`];
-            const count = row[`${prefix}_usage_count`];
-            if (typeof total !== 'number' || !Number.isFinite(total) || total <= 0)
-                continue;
-            // Official CLI compatibility: absent percentages use legacy remaining counts.
+            // An explicit percentage needs no counts: time-based plans send zero
+            // counts beside it. Official CLI compatibility: without a percentage, the
+            // legacy counts are the quota remaining.
             const usedPercent = typeof remaining === 'number' ? 100 - remaining * boost / 1000
-                : typeof total === 'number' && total > 0 && typeof count === 'number' ? (1 - count / total) * 100 : undefined;
+                : usedFromCounts(row[`${prefix}_total_count`], row[`${prefix}_usage_count`]);
             if (usedPercent === undefined || !Number.isFinite(usedPercent) || usedPercent < 0 || usedPercent > 100)
                 continue;
             const start = row[startKey];

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

@@ -69,6 +69,8 @@ export declare class PoolHealthRegistry {
      * `providerRetryAfterMs`.
      */
     earliestRecovery(keys: ReadonlySet<string>, now?: number): number | undefined;
+    /** Active failure codes for the given keys; reading them does not change cooldowns. */
+    unavailableReasons(keys: ReadonlySet<string>, now?: number): string[];
     /** Drop records of one provider, or of a single account when given (auth changes). */
     clear(provider: ProviderId, account?: string): void;
 }

package/lib/providers/pool-health.js

@@ -139,6 +139,15 @@ export class PoolHealthRegistry {
         }
         return earliest;
     }
+    /** Active failure codes for the given keys; reading them does not change cooldowns. */
+    unavailableReasons(keys, now = Date.now()) {
+        const reasons = [];
+        for (const [key, record] of this.records) {
+            if (keys.has(key) && record.unavailableUntil > now)
+                reasons.push(record.reason);
+        }
+        return reasons;
+    }
     /** Drop records of one provider, or of a single account when given (auth changes). */
     clear(provider, account) {
         const prefix = account === undefined ? `${provider}/` : `${provider}/${account}/`;

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

@@ -39,6 +39,11 @@ export declare class PoolUsageTracker {
     private readonly ttlMs;
     private readonly entries;
     private readonly inflight;
+    /** Bumped by {@link invalidate} so a fetch started before it cannot repopulate the cache. */
+    private readonly generation;
+    /** Monotonic per-key write order: only the newest settled fetch may cache. */
+    private nextSequence;
+    private readonly lastWritten;
     constructor(fetcherFor: (provider: ProviderId, account: string) => (() => Promise<ProviderUsage>) | undefined, ttlMs?: number);
     /**
      * The quota view of one member. A cold cache awaits the first fetch; a
@@ -70,7 +75,14 @@ export declare class PoolUsageTracker {
      * @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. */
+    /**
+     * Drop cached snapshots: one account, or a whole provider when `account` is
+     * omitted. A fetch already in flight is abandoned too. It was started against
+     * state the caller has just declared changed — a redeemed credit, a completed
+     * login — so joining it would return the pre-change numbers and cache them for
+     * the full freshness window. Its result is discarded on arrival by the
+     * generation check in {@link refresh}.
+     */
     invalidate(provider: ProviderId, account?: string): void;
     /**
      * Run (or join) the single in-flight fetch for one account key, caching

package/lib/providers/pool-usage.js

@@ -34,6 +34,11 @@ export class PoolUsageTracker {
     ttlMs;
     entries = new Map();
     inflight = new Map();
+    /** Bumped by {@link invalidate} so a fetch started before it cannot repopulate the cache. */
+    generation = new Map();
+    /** Monotonic per-key write order: only the newest settled fetch may cache. */
+    nextSequence = 0;
+    lastWritten = new Map();
     constructor(fetcherFor, ttlMs = USAGE_TTL_MS) {
         this.fetcherFor = fetcherFor;
         this.ttlMs = ttlMs;
@@ -126,15 +131,27 @@ export class PoolUsageTracker {
             throw error;
         }
     }
-    /** Drop cached snapshots: one account, or a whole provider when `account` is omitted. */
+    /**
+     * Drop cached snapshots: one account, or a whole provider when `account` is
+     * omitted. A fetch already in flight is abandoned too. It was started against
+     * state the caller has just declared changed — a redeemed credit, a completed
+     * login — so joining it would return the pre-change numbers and cache them for
+     * the full freshness window. Its result is discarded on arrival by the
+     * generation check in {@link refresh}.
+     */
     invalidate(provider, account) {
+        const drop = (key) => {
+            this.entries.delete(key);
+            this.inflight.delete(key);
+            this.generation.set(key, (this.generation.get(key) ?? 0) + 1);
+        };
         if (account !== undefined) {
-            this.entries.delete(`${provider}/${account}`);
+            drop(`${provider}/${account}`);
             return;
         }
-        for (const key of [...this.entries.keys()]) {
+        for (const key of [...this.entries.keys(), ...this.inflight.keys()]) {
             if (key.startsWith(`${provider}/`))
-                this.entries.delete(key);
+                drop(key);
         }
     }
     /**
@@ -155,13 +172,26 @@ export class PoolUsageTracker {
             // consecutive failure, even though nothing newer ever replaced it.
             const prior = this.entries.get(key);
             const lastSnapshot = prior?.snapshot ?? prior?.lastSnapshot;
+            const generation = this.generation.get(key) ?? 0;
+            // A newer fetch may settle before this one does. The generation only
+            // catches an invalidate; the sequence catches a plain race, where this
+            // fetch fails late and would otherwise cache a cooldown over a fresher
+            // success that already landed.
+            const sequence = ++this.nextSequence;
             pending = fetcher().then((value) => {
                 const at = Date.now();
                 const snapshot = { ...value, observedAt: at, stale: false };
-                this.entries.set(key, { snapshot, at });
+                // An invalidate() during the fetch means this result describes a world
+                // that has moved on; caching it would resurrect the old numbers.
+                if ((this.generation.get(key) ?? 0) === generation && (this.lastWritten.get(key) ?? 0) < sequence) {
+                    this.lastWritten.set(key, sequence);
+                    this.entries.set(key, { snapshot, at });
+                }
                 return snapshot;
             }, (error) => {
-                if (!isMissingOrInvalidCredential(error)) {
+                if (!isMissingOrInvalidCredential(error) && (this.generation.get(key) ?? 0) === generation
+                    && (this.lastWritten.get(key) ?? 0) < sequence) {
+                    this.lastWritten.set(key, sequence);
                     this.entries.set(key, {
                         error,
                         at: Date.now(),
@@ -171,7 +201,9 @@ export class PoolUsageTracker {
                 }
                 throw error;
             }).finally(() => {
-                this.inflight.delete(key);
+                // Only clear our own slot: an invalidate may have replaced it.
+                if (this.inflight.get(key) === pending)
+                    this.inflight.delete(key);
             });
             this.inflight.set(key, pending);
         }

package/lib/providers/pool.d.ts

@@ -87,6 +87,12 @@ export declare class PoolAdapter extends LlmAdapter {
      * metadata is account-specific, so every distinct member is resolved.
      */
     resolveModel(provider: string, model: string): Promise<LlmResolvedModelInfo>;
+    /**
+     * Fail over before output. A single non-quota failure keeps its identity
+     * and shared provider message, with scoped pool recovery or its own hint as fallback.
+     * Multiple failures carry a bounded summary and all attempts in an AggregateError cause.
+     * Pure quota/rate exhaustion retains RATE_LIMIT and this pool's earliest recovery hint.
+     */
     stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
     /**
      * Order the candidates for one request. Health filters both strategies;
@@ -99,10 +105,6 @@ export declare class PoolAdapter extends LlmAdapter {
     private select;
     /** Pin the serving member to the session (with bounded memory). */
     private remember;
-    /**
-     * The error for an exhausted pool, carrying the earliest recovery hint of
-     * THIS pool's members (the health registry is shared across pools, so the
-     * hint is scoped to the keys this pool can actually recover through).
-     */
+    /** Report attempt failures or this pool's active cooldowns, never unrelated health records. */
     private exhausted;
 }

package/lib/providers/pool.js

@@ -10,6 +10,7 @@
 import { EMPTY_RESPONSE_CODE, LlmAdapter, LlmError, QUOTA_EXCEEDED_CODE, } from '@deepseek-ai/dsh-llm';
 import { poolKey } from './pool-family.js';
 import { accountKey, classifyPoolFailure, memberKey, PoolHealthRegistry } from './pool-health.js';
+import { streamAccountWithReplay } from './replay.js';
 /** Bound on sticky-session memory; oldest entries evict past it. */
 const STICKY_SESSION_LIMIT = 1000;
 /** Display form of one member (account shown when pinned). */
@@ -200,6 +201,12 @@ export class PoolAdapter extends LlmAdapter {
             ...modalities === undefined ? {} : { inputModalities: modalities },
         };
     }
+    /**
+     * Fail over before output. A single non-quota failure keeps its identity
+     * and shared provider message, with scoped pool recovery or its own hint as fallback.
+     * Multiple failures carry a bounded summary and all attempts in an AggregateError cause.
+     * Pure quota/rate exhaustion retains RATE_LIMIT and this pool's earliest recovery hint.
+     */
     async *stream(options) {
         const definition = (await this.pools()).get(poolKey(options.provider, options.model));
         if (definition === undefined)
@@ -208,12 +215,12 @@ export class PoolAdapter extends LlmAdapter {
         const candidates = await this.select(options.model, members, options.sessionId);
         if (candidates.length === 0)
             throw this.exhausted(options.model, members);
-        let lastError;
+        const failures = [];
         for (const member of candidates) {
             const adapter = this.options.adapters[member.provider];
             if (adapter === undefined)
                 continue;
-            const iterator = adapter.streamAccount({ ...options, provider: member.provider, model: member.model }, member.account)[Symbol.asyncIterator]();
+            const iterator = streamAccountWithReplay(adapter, { ...options, provider: member.provider }, member.account, member.model)[Symbol.asyncIterator]();
             let first;
             try {
                 first = await iterator.next();
@@ -223,7 +230,7 @@ export class PoolAdapter extends LlmAdapter {
             }
             catch (error) {
                 const classification = classifyPoolFailure(error, member.provider);
-                if (classification.action === 'throw')
+                if (classification.action === 'throw' || !(error instanceof LlmError))
                     throw error;
                 if ('cooldownMs' in classification) {
                     this.options.health.markUnavailable(classification.scope === 'account'
@@ -238,7 +245,7 @@ export class PoolAdapter extends LlmAdapter {
                 }
                 this.options.onWarn(`pool "${options.model}": ${memberLabel(member)} failed before any output`
                     + ` (${error instanceof Error ? error.message : String(error)}); trying the next member`);
-                lastError = error;
+                failures.push(error);
                 continue;
             }
             this.remember(options.model, options.sessionId, member);
@@ -264,7 +271,7 @@ export class PoolAdapter extends LlmAdapter {
             }
             return;
         }
-        throw this.exhausted(options.model, members, lastError);
+        throw this.exhausted(options.model, members, failures);
     }
     /**
      * Order the candidates for one request. Health filters both strategies;
@@ -316,12 +323,11 @@ export class PoolAdapter extends LlmAdapter {
         }
         this.sticky.set(key, memberKey(member.provider, member.account, member.model));
     }
-    /**
-     * The error for an exhausted pool, carrying the earliest recovery hint of
-     * THIS pool's members (the health registry is shared across pools, so the
-     * hint is scoped to the keys this pool can actually recover through).
-     */
-    exhausted(model, pool, cause) {
+    /** Report attempt failures or this pool's active cooldowns, never unrelated health records. */
+    exhausted(model, pool, failures = []) {
+        if (pool.length === 0) {
+            return new LlmError(`pool "${model}" has no usable member: no account could be resolved`, 'NO_ADAPTER');
+        }
         const keys = new Set();
         for (const member of pool) {
             keys.add(memberKey(member.provider, member.account, member.model));
@@ -329,12 +335,83 @@ export class PoolAdapter extends LlmAdapter {
         }
         const recovery = this.options.health.earliestRecovery(keys);
         const retryAfterMs = recovery === undefined ? undefined : Math.max(recovery - Date.now(), 1);
-        return new LlmError(`pool "${model}" exhausted: every member is unavailable or failed`, 'RATE_LIMIT', {
+        const coolingReasons = this.options.health.unavailableReasons(keys);
+        const codes = [...failures.map(error => error.code), ...coolingReasons];
+        if (codes.length === 0)
+            return new LlmError(`pool "${model}" has no usable member`, 'NO_ADAPTER');
+        const quotaOnly = codes.every(isQuotaFailure);
+        if (failures.length === 1 && !isQuotaFailure(failures[0].code)) {
+            const failure = failures[0];
+            // Keep the same error, code, status and cause. The message arrives already
+            // free of provider text: the shared converter in common.ts owns that, and
+            // non-pooled callers receive the same text, so the pool adds no sanitizer
+            // of its own and cannot make the two paths disagree.
+            // The pool's earliest scoped recovery wins even if the member's hint is
+            // later: another member may recover sooner. Without scoped recovery,
+            // keep the member hint; with neither, leave it absent.
+            // Keep the error object itself. LlmError freezes its facts snapshot, so
+            // replace that snapshot to correct only providerRetryAfterMs for pool
+            // routing; this is not permission to rewrite other frozen failure facts.
+            if (retryAfterMs !== undefined && retryAfterMs !== failure.failure.providerRetryAfterMs) {
+                Object.defineProperty(failure, 'failure', {
+                    value: Object.freeze({ ...failure.failure, providerRetryAfterMs: retryAfterMs }),
+                });
+            }
+            return failure;
+        }
+        const attemptedCodes = failures.map(error => error.code);
+        const details = [...attemptedCodes, ...coolingReasons.filter(code => !attemptedCodes.includes(code))];
+        const summary = failureSummary(details);
+        const cause = failures.length === 0
+            ? undefined
+            : failures.length === 1
+                ? failures[0]
+                : new AggregateError(failures, `${failures.length} pool members failed: ${summary}`);
+        // Subscription quotas reopen: preserve the existing retry classification and text.
+        const message = quotaOnly
+            ? `pool "${model}" exhausted: every member is unavailable or failed`
+            : failures.length > 0
+                ? `pool "${model}" exhausted: ${failures.length} ${failures.length === 1 ? 'member' : 'members'} failed (${summary})`
+                : `pool "${model}" unavailable: ${pool.length} members are cooling down (${summary})`;
+        // For mixed failures, a real non-quota failure must not become a rate limit
+        // merely because the last member hit its quota. No new aggregate error code.
+        const code = quotaOnly
+            ? 'RATE_LIMIT'
+            : attemptedCodes.filter(code => !isQuotaFailure(code)).at(-1)
+                ?? coolingReasons.filter(code => !isQuotaFailure(code)).at(-1);
+        return new LlmError(message, code, {
             ...retryAfterMs === undefined ? {} : { providerRetryAfterMs: retryAfterMs },
             ...cause === undefined ? {} : { cause },
         });
     }
 }
+function isQuotaFailure(code) {
+    return code === QUOTA_EXCEEDED_CODE || code === 'RATE_LIMIT';
+}
+/** Summaries use stable codes only: adapter messages and nested causes can contain raw payloads. */
+function failureSummary(codes) {
+    const descriptions = {
+        AUTH: 'authentication failed',
+        INVALID_CREDENTIAL: 'credential is invalid',
+        MISSING_CREDENTIAL: 'credential is missing',
+        SERVER: 'provider server failed',
+        TIMEOUT: 'provider request timed out',
+        EMPTY_RESPONSE: 'provider returned no output',
+        TRANSPORT: 'provider connection failed',
+        HTTP_402: 'provider plan unavailable',
+        HTTP_404: 'provider model unavailable',
+        QUOTA: 'provider quota exhausted',
+        RATE_LIMIT: 'provider rate limit reached',
+    };
+    const limit = 5;
+    const shown = codes.slice(0, limit).map(code => {
+        const description = descriptions[code];
+        return description === undefined ? 'member unavailable' : `${code}: ${description}`;
+    });
+    if (codes.length > limit)
+        shown.push(`${codes.length - limit} more`);
+    return shown.join('; ');
+}
 function stickyKey(poolId, sessionId) {
     return `${String(sessionId)}|${poolId}`;
 }

package/lib/providers/rate-limit.d.ts

@@ -110,20 +110,6 @@ export declare function earliestReset(...candidates: (number | undefined)[]): nu
  * @returns the wait in milliseconds, never below {@link MIN_WAIT_MS}.
  */
 export declare function waitFromReset(instant: number, now: number): number;
-/**
- * Render the rate-limit-shaped headers and the head of the body of a 429 whose
- * reset instant nothing parsed. Emitted through the adapter's `onWarn`, this is
- * how an unrecognized provider field gets named from live traffic instead of
- * being guessed at.
- *
- * It is also where the per-bucket rollover snapshots land by design — no reader
- * parks a turn on one, because on a 429 they cannot say which bucket refused —
- * so the operator still sees what the provider disclosed.
- * @param response - the failed response.
- * @param body - the complete response body.
- * @returns a one-line diagnostic.
- */
-export declare function rateLimitDiagnostics(response: Response, body: string): string;
 /** Per-route retry shape a subscription adapter starts from. */
 export interface RetryDefaults {
     /** Retries after the first attempt. */

package/lib/providers/rate-limit.js

@@ -238,32 +238,6 @@ export function earliestReset(...candidates) {
 export function waitFromReset(instant, now) {
     return Math.max(MIN_WAIT_MS, instant - now + RESET_GRACE_MS);
 }
-/** Header names worth showing when a 429 disclosed no reset this code recognizes. */
-const DIAGNOSTIC_HEADER = /rate-?limit|retry|reset|^x-codex-/i;
-/**
- * Render the rate-limit-shaped headers and the head of the body of a 429 whose
- * reset instant nothing parsed. Emitted through the adapter's `onWarn`, this is
- * how an unrecognized provider field gets named from live traffic instead of
- * being guessed at.
- *
- * It is also where the per-bucket rollover snapshots land by design — no reader
- * parks a turn on one, because on a 429 they cannot say which bucket refused —
- * so the operator still sees what the provider disclosed.
- * @param response - the failed response.
- * @param body - the complete response body.
- * @returns a one-line diagnostic.
- */
-export function rateLimitDiagnostics(response, body) {
-    const headers = [];
-    response.headers.forEach((value, key) => {
-        if (DIAGNOSTIC_HEADER.test(key))
-            headers.push(`${key}: ${value}`);
-    });
-    headers.sort();
-    const rendered = headers.length > 0 ? headers.join('; ') : '(none)';
-    const head = body.slice(0, 200);
-    return `429 disclosed no reset time; headers [${rendered}]; body ${head.length > 0 ? head : '(empty)'}`;
-}
 /**
  * The retry shape every subscription route starts from: Claude Code's own SDK
  * numbers — ten retries after the first attempt, exponential backoff from 1s

package/lib/providers/replay.d.ts

@@ -0,0 +1,4 @@
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { AccountAwareAdapter } from './accounts.js';
+/** Bind opaque replay to the concrete account/model behind a route alias. */
+export declare function streamAccountWithReplay(adapter: AccountAwareAdapter, options: GenerateOptions, account: string, model?: string): AsyncIterable<StreamChunk>;