dsh-subscriptions 0.1.0

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

@@ -0,0 +1,30 @@
+import type { AccountTokenManager } from './accounts.js';
+import type { RateLimitResetReader } from './rate-limit.js';
+type ImageProvider = 'codex' | 'grok';
+interface ImageSession {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+}
+export interface ImageAccountRequest<S extends ImageSession> {
+    provider: ImageProvider;
+    tokens: AccountTokenManager<S>;
+    signal: AbortSignal;
+    /** Session object identity provides bounded-lifetime affinity, also across generate/edit. */
+    owner?: object | undefined;
+    rateLimitReset: RateLimitResetReader;
+    send: (session: S) => Promise<Response>;
+}
+export declare class ImageAccountPool {
+    private readonly options;
+    private readonly health;
+    private sticky;
+    constructor(options?: {
+        enabled?: boolean;
+        onWarn?: (message: string) => void;
+    });
+    /** Login/logout clears cooling image members and stale session affinity. */
+    clear(provider: ImageProvider, account?: string): void;
+    request<S extends ImageSession>(request: ImageAccountRequest<S>): Promise<Response>;
+}
+export {};

package/lib/providers/image-pool.js

@@ -0,0 +1,89 @@
+/** Account scheduling shared by image generation and editing, independent of chat catalogs/quota. */
+import { LlmError } from '@deepseek-ai/dsh-llm';
+import { httpLlmError } from './common.js';
+import { AUTH_COOLDOWN_MS, DEFAULT_QUOTA_COOLDOWN_MS, TRANSIENT_COOLDOWN_MS, PoolHealthRegistry, memberKey } from './pool-health.js';
+export class ImageAccountPool {
+    options;
+    // Deliberately separate from chat health: image quotas/entitlements need not match chat.
+    health = new PoolHealthRegistry();
+    sticky = new WeakMap();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /** Login/logout clears cooling image members and stale session affinity. */
+    clear(provider, account) {
+        this.health.clear(provider, account);
+        this.sticky = new WeakMap();
+    }
+    async request(request) {
+        const { provider, tokens, signal, owner, send, rateLimitReset } = request;
+        signal.throwIfAborted();
+        const accounts = await tokens.list();
+        if (accounts.length === 0) {
+            await tokens.session(); // standard provider-specific login hint
+            throw new LlmError('image_generate: no image account is logged in', 'MISSING_CREDENTIAL');
+        }
+        const pooling = this.options.enabled !== false;
+        const members = (pooling ? accounts : accounts.slice(0, 1)).map(entry => entry.key);
+        const sticky = pooling && owner !== undefined ? this.sticky.get(owner)?.get(provider) : undefined;
+        const ordered = sticky !== undefined && members.includes(sticky)
+            ? [sticky, ...members.filter(key => key !== sticky)] : members;
+        let lastError;
+        for (const account of ordered) {
+            signal.throwIfAborted();
+            const key = memberKey(provider, account, 'images');
+            if (pooling && !this.health.isAvailable(key))
+                continue;
+            let failure;
+            try {
+                let session = await tokens.session(account);
+                signal.throwIfAborted();
+                let response = await send(session);
+                // Only a definitive unauthorized rejection permits retrying this account.
+                if (response.status === 401) {
+                    await response.body?.cancel();
+                    session = await tokens.session(account, true);
+                    signal.throwIfAborted();
+                    response = await send(session);
+                }
+                signal.throwIfAborted();
+                if (response.ok) {
+                    if (pooling && owner !== undefined) {
+                        let affinity = this.sticky.get(owner);
+                        if (affinity === undefined) {
+                            affinity = new Map();
+                            this.sticky.set(owner, affinity);
+                        }
+                        affinity.set(provider, account);
+                    }
+                    return response;
+                }
+                // Images can be produced despite timeouts/server failures. Switch only on
+                // explicit auth/quota/entitlement rejection, never ambiguous transport/5xx.
+                failure = await httpLlmError(response, 'image_generate', { rateLimitReset });
+                if (![401, 402, 403, 404, 429].includes(response.status))
+                    throw failure;
+            }
+            catch (error) {
+                signal.throwIfAborted();
+                if (!(error instanceof LlmError) || !['AUTH', 'INVALID_CREDENTIAL', 'MISSING_CREDENTIAL', 'RATE_LIMIT', 'HTTP_402', 'HTTP_404'].includes(error.code))
+                    throw error;
+                failure = error;
+            }
+            if (!pooling)
+                throw failure;
+            const delay = failure.failure.providerRetryAfterMs ?? (failure.code === 'RATE_LIMIT'
+                ? DEFAULT_QUOTA_COOLDOWN_MS
+                : ['AUTH', 'INVALID_CREDENTIAL', 'MISSING_CREDENTIAL'].includes(failure.code) ? AUTH_COOLDOWN_MS : TRANSIENT_COOLDOWN_MS);
+            this.health.markUnavailable(key, delay, failure.code);
+            this.options.onWarn?.(`image pool ${provider}: account ${members.indexOf(account) + 1}/${members.length} rejected (${failure.code}); checking remaining accounts`);
+            lastError = failure;
+        }
+        if (lastError !== undefined)
+            throw lastError;
+        const recovery = this.health.earliestRecovery(new Set(members.map(account => memberKey(provider, account, 'images'))));
+        throw new LlmError(`image_generate: all ${provider} image accounts are cooling down`, 'RATE_LIMIT', {
+            ...recovery === undefined ? {} : { providerRetryAfterMs: Math.max(0, recovery - Date.now()) },
+        });
+    }
+}

package/lib/providers/npm-cli-version.d.ts

@@ -0,0 +1,56 @@
+import type { FetchFn } from './common.js';
+/**
+ * Compare two stable `major.minor.patch` versions numerically.
+ * @returns negative when `a` is older, positive when newer, 0 when equal.
+ */
+export declare function compareVersions(a: string, b: string): number;
+/** Where a presented CLI version came from; shown in Settings so a stale one is visible. */
+export type CliVersionSource = 'npm' | 'local' | 'fallback' | 'config';
+/** The CLI version a route presents, and where it came from. */
+export interface CliVersion {
+    version: string;
+    source: CliVersionSource;
+}
+export interface NpmCliVersionOptions {
+    /** Registry metadata of the package's `latest` dist-tag; public, so never send credentials. */
+    url: string;
+    /** Names the CLI in lookup errors. */
+    label: string;
+    /**
+     * The version served until a lookup succeeds, and the floor a looked-up
+     * version may never go below. Read once, on first use, so a costly probe
+     * (a local CLI's `--version`) never runs for an unused provider.
+     */
+    floor: () => CliVersion;
+    fetchFn?: FetchFn;
+    now?: () => number;
+    timeoutMs?: number;
+}
+/**
+ * Lazy, shared-per-plugin lookup of an official CLI's newest stable version
+ * on npm. Subscription endpoints gate new models on the client version they
+ * see, so presenting the released CLI's version keeps new models usable
+ * without a plugin release for every CLI bump.
+ */
+export declare class NpmCliVersionCache {
+    private readonly options;
+    private presented;
+    /** Whether a lookup has finished yet, successfully or not. */
+    private settled;
+    private expiresAt;
+    private pending;
+    private readonly fetchFn;
+    private readonly now;
+    private readonly timeoutMs;
+    constructor(options: NpmCliVersionOptions);
+    /** A manual catalog refresh also checks for a newly released CLI. */
+    invalidate(): void;
+    resolve(): Promise<string>;
+    /**
+     * The version presented right now, without waiting on the registry;
+     * undefined until the first lookup finishes, so a lookup still in flight
+     * is never reported as a failed one.
+     */
+    current(): CliVersion | undefined;
+    private refresh;
+}

package/lib/providers/npm-cli-version.js

@@ -0,0 +1,98 @@
+import { hostFetch } from '../http.js';
+/** Stable `major.minor.patch` only: prerelease and platform tags are not client versions. */
+const STABLE_VERSION = /^\d{1,6}\.\d{1,6}\.\d{1,6}$/;
+/**
+ * Compare two stable `major.minor.patch` versions numerically.
+ * @returns negative when `a` is older, positive when newer, 0 when equal.
+ */
+export function compareVersions(a, b) {
+    const left = a.split('.').map(Number);
+    const right = b.split('.').map(Number);
+    const different = left.findIndex((part, index) => part !== right[index]);
+    return different === -1 ? 0 : left[different] - right[different];
+}
+/**
+ * Lazy, shared-per-plugin lookup of an official CLI's newest stable version
+ * on npm. Subscription endpoints gate new models on the client version they
+ * see, so presenting the released CLI's version keeps new models usable
+ * without a plugin release for every CLI bump.
+ */
+export class NpmCliVersionCache {
+    options;
+    presented;
+    /** Whether a lookup has finished yet, successfully or not. */
+    settled = false;
+    expiresAt = 0;
+    pending;
+    fetchFn;
+    now;
+    timeoutMs;
+    constructor(options) {
+        this.options = options;
+        this.fetchFn = options.fetchFn ?? hostFetch;
+        this.now = options.now ?? Date.now;
+        this.timeoutMs = options.timeoutMs ?? 5000;
+    }
+    /** A manual catalog refresh also checks for a newly released CLI. */
+    invalidate() { this.expiresAt = 0; }
+    resolve() {
+        if (this.pending !== undefined)
+            return this.pending;
+        if (this.presented !== undefined && this.now() < this.expiresAt)
+            return Promise.resolve(this.presented.version);
+        this.pending = this.refresh().finally(() => { this.pending = undefined; });
+        return this.pending;
+    }
+    /**
+     * The version presented right now, without waiting on the registry;
+     * undefined until the first lookup finishes, so a lookup still in flight
+     * is never reported as a failed one.
+     */
+    current() {
+        return this.settled ? this.presented : undefined;
+    }
+    async refresh() {
+        const current = (this.presented ??= this.options.floor()).version;
+        const { url, label } = this.options;
+        const controller = new AbortController();
+        let timer;
+        try {
+            const lookup = async () => {
+                const response = await this.fetchFn(url, {
+                    headers: { accept: 'application/json' },
+                    redirect: 'error',
+                    signal: controller.signal,
+                });
+                if (!response.ok)
+                    throw new Error(`${label} version lookup failed`);
+                const payload = await response.json();
+                const version = payload?.version;
+                // Ignore prerelease/platform tags and malformed or regressed metadata.
+                if (typeof version !== 'string' || !STABLE_VERSION.test(version)) {
+                    throw new Error(`Invalid stable ${label} version`);
+                }
+                if (compareVersions(version, current) < 0)
+                    throw new Error(`Older ${label} version`);
+                return version;
+            };
+            const timeout = new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    controller.abort();
+                    reject(new Error(`${label} version lookup timed out`));
+                }, this.timeoutMs);
+            });
+            // Also bounded when an injected transport ignores cancellation.
+            this.presented = { version: await Promise.race([lookup(), timeout]), source: 'npm' };
+            this.expiresAt = this.now() + 6 * 60 * 60_000;
+        }
+        catch {
+            // Retain last-known good; on first use this is the floor.
+            this.expiresAt = this.now() + 5 * 60_000;
+        }
+        finally {
+            clearTimeout(timer);
+            this.settled = true;
+        }
+        return this.presented.version;
+    }
+}

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

@@ -0,0 +1,56 @@
+/**
+ * Same-subscription account routing: the picker is the union of every
+ * account's catalog (deduped by wire id). A model listed by two or more
+ * accounts failovers between them; a model listed by only one account is
+ * sent to that account. No extra pool identity, no cross-provider
+ * aggregation.
+ */
+import type { LlmModelInfo } from '@deepseek-ai/dsh-llm';
+import type { ProviderId } from '../auth/store.js';
+/** One pool member: an exact provider/account/model route. */
+export interface PoolMemberRef {
+    provider: ProviderId;
+    /** Account key; omitted in configured members to mean "the default account". */
+    account?: string;
+    model: string;
+}
+/** A member with its account resolved (no config indirection left). */
+export type ConcretePoolMember = PoolMemberRef & {
+    account: string;
+};
+/** One pool: its members plus display metadata for the picker. */
+export interface PoolDefinition {
+    members: PoolMemberRef[];
+    /** Display name of the catalog entry (account pools) or the pool id (extras). */
+    name?: string;
+    /** Description of the catalog entry, when the pool borrowed one. */
+    description?: string;
+    /**
+     * When true, the pool is an extra picker entry (a configured tier). Account
+     * pools leave this unset so they reuse the provider's existing catalog row.
+     */
+    extra?: boolean;
+}
+/** One account's catalog as seen through that account's credentials. */
+export interface AccountCatalog {
+    account: string;
+    models: readonly LlmModelInfo[];
+}
+/** One provider's contribution to account-pool aggregation. */
+export interface ProviderPoolSource {
+    /** Per-account catalogs, default first. A model pools only the accounts that list it. */
+    catalogs: readonly AccountCatalog[];
+}
+/** Map key for one provider's pool of one model (ids collide across providers). */
+export declare function poolKey(provider: string, model: string): string;
+/**
+ * Build per-provider account routes. Each model id becomes a definition of
+ * the accounts that list it: two or more fail over; one is pinned to that
+ * account (so a Max-only model is never sent to a Plus login). The picker
+ * unions these catalogs; a logout that drops a model to one account keeps
+ * the same id and pins it to whoever remains.
+ * @param sources - per-account catalogs (providers with no accounts list
+ *   nothing and simply never join a pool).
+ * @returns `provider/model` → pool definition (not listed as an extra entry).
+ */
+export declare function buildAccountPools(sources: Partial<Record<ProviderId, ProviderPoolSource>>): Map<string, PoolDefinition>;

package/lib/providers/pool-family.js

@@ -0,0 +1,45 @@
+/**
+ * Same-subscription account routing: the picker is the union of every
+ * account's catalog (deduped by wire id). A model listed by two or more
+ * accounts failovers between them; a model listed by only one account is
+ * sent to that account. No extra pool identity, no cross-provider
+ * aggregation.
+ */
+/** Map key for one provider's pool of one model (ids collide across providers). */
+export function poolKey(provider, model) {
+    return `${provider}/${model}`;
+}
+/**
+ * Build per-provider account routes. Each model id becomes a definition of
+ * the accounts that list it: two or more fail over; one is pinned to that
+ * account (so a Max-only model is never sent to a Plus login). The picker
+ * unions these catalogs; a logout that drops a model to one account keeps
+ * the same id and pins it to whoever remains.
+ * @param sources - per-account catalogs (providers with no accounts list
+ *   nothing and simply never join a pool).
+ * @returns `provider/model` → pool definition (not listed as an extra entry).
+ */
+export function buildAccountPools(sources) {
+    const pools = new Map();
+    for (const [provider, source] of Object.entries(sources)) {
+        const byModel = new Map();
+        for (const catalog of source.catalogs) {
+            for (const model of catalog.models) {
+                let entry = byModel.get(model.id);
+                if (entry === undefined) {
+                    entry = { members: [], info: model };
+                    byModel.set(model.id, entry);
+                }
+                entry.members.push({ provider, account: catalog.account, model: model.id });
+            }
+        }
+        for (const [id, { members, info }] of byModel) {
+            pools.set(poolKey(provider, id), {
+                members,
+                ...info.name === undefined || info.name === id ? {} : { name: info.name },
+                ...info.description === undefined ? {} : { description: info.description },
+            });
+        }
+    }
+    return pools;
+}

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

@@ -0,0 +1,74 @@
+/**
+ * Health bookkeeping for pool members: which `(provider, account, model)`
+ * member is cooling down after a failure, and for how long. Purely in-memory
+ * — a restart re-probes members naturally, so nothing here is persisted.
+ *
+ * The failure classifier maps the adapters' stable `LlmError` codes (see
+ * `httpLlmError`/`mapFetchFailure` in `common.ts`) to one of three actions:
+ * switch to another member with a cooldown, switch without recording a
+ * cooldown (transport blips say nothing about the account), or rethrow
+ * (the request itself is at fault and another account would fail alike).
+ */
+import type { ProviderId } from '../auth/store.js';
+/** Registry key for one pool member. */
+export declare function memberKey(provider: ProviderId, account: string, model: string): string;
+/** Registry key parking EVERY member of one account (account-level failures). */
+export declare function accountKey(provider: ProviderId, account: string): string;
+/** Default cooldown when a quota/rate failure carries no `retry-after`. */
+export declare const DEFAULT_QUOTA_COOLDOWN_MS: number;
+/** Auth failures recheck after a day; a re-login clears the record immediately. */
+export declare const AUTH_COOLDOWN_MS: number;
+/** Transient server-side failures cool down briefly. */
+export declare const TRANSIENT_COOLDOWN_MS = 60000;
+/** Whether a failure parks one member or the account's whole quota. */
+export type PoolFailureScope = 'member' | 'account';
+/** What the pool should do with a member that just failed. */
+export type PoolFailureAction = {
+    action: 'switch';
+    cooldownMs: number;
+    reason: string;
+    scope: PoolFailureScope;
+} | {
+    action: 'switch';
+} | {
+    action: 'throw';
+};
+/**
+ * Classify a member failure. Quota and rate-limit failures cool down (using
+ * the provider's own `retry-after` when sent, which is more accurate than
+ * any fixed guess) — account-wide for account-metered providers, per-member
+ * for model-scoped ones; auth failures park the account until re-login
+ * (credentials are account-level); server/timeout failures get a short
+ * per-member cooldown; transport failures switch without a record;
+ * everything else — most importantly CONTEXT_WINDOW_EXCEEDED and ABORTED —
+ * is the request's own fault and is rethrown untouched.
+ * @param error - the failure thrown by a member adapter's stream.
+ * @param provider - the failing member's provider (decides the quota scope).
+ * @returns the action the pool should take.
+ */
+export declare function classifyPoolFailure(error: unknown, provider: ProviderId): PoolFailureAction;
+/**
+ * Cooldown registry keyed by {@link memberKey}. A member whose cooldown has
+ * expired is simply available again — recovery is proven by the next real
+ * request, not by a background probe.
+ */
+export declare class PoolHealthRegistry {
+    private readonly records;
+    /** Whether a member may serve: neither it nor its whole account is cooling. */
+    isMemberAvailable(provider: ProviderId, account: string, model: string, now?: number): boolean;
+    /** Whether one registry key is clear right now. */
+    isAvailable(key: string, now?: number): boolean;
+    /** Park a member for `cooldownMs`; a longer existing cooldown wins. */
+    markUnavailable(key: string, cooldownMs: number, reason: string, now?: number): void;
+    /**
+     * Epoch ms at which the earliest cooling record among `keys` recovers;
+     * `undefined` when none of them is cooling. The registry is shared by
+     * every pool, so the caller passes the keys of ITS members (member and
+     * account keys alike) — an unrelated pool's cooldown must not shape this
+     * pool's retry hint. Feeds the pool-exhausted error's
+     * `providerRetryAfterMs`.
+     */
+    earliestRecovery(keys: ReadonlySet<string>, now?: number): number | undefined;
+    /** 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

@@ -0,0 +1,150 @@
+/**
+ * Health bookkeeping for pool members: which `(provider, account, model)`
+ * member is cooling down after a failure, and for how long. Purely in-memory
+ * — a restart re-probes members naturally, so nothing here is persisted.
+ *
+ * The failure classifier maps the adapters' stable `LlmError` codes (see
+ * `httpLlmError`/`mapFetchFailure` in `common.ts`) to one of three actions:
+ * switch to another member with a cooldown, switch without recording a
+ * cooldown (transport blips say nothing about the account), or rethrow
+ * (the request itself is at fault and another account would fail alike).
+ */
+import { CONTEXT_WINDOW_EXCEEDED_CODE, LlmError, QUOTA_EXCEEDED_CODE } from '@deepseek-ai/dsh-llm';
+/** Registry key for one pool member. */
+export function memberKey(provider, account, model) {
+    return `${provider}/${account}/${model}`;
+}
+/** Registry key parking EVERY member of one account (account-level failures). */
+export function accountKey(provider, account) {
+    return `${provider}/${account}/*`;
+}
+/** Default cooldown when a quota/rate failure carries no `retry-after`. */
+export const DEFAULT_QUOTA_COOLDOWN_MS = 5 * 60_000;
+/** Auth failures recheck after a day; a re-login clears the record immediately. */
+export const AUTH_COOLDOWN_MS = 24 * 60 * 60_000;
+/** Transient server-side failures cool down briefly. */
+export const TRANSIENT_COOLDOWN_MS = 60_000;
+/**
+ * Providers whose quota windows are model-scoped, so a quota failure on one
+ * model says nothing about its siblings (Claude's Opus/Sonnet lanes;
+ * Antigravity's per-model quotas, whose 429 names the exhausted model and
+ * can disclose a reset 35 hours out that must not park its Gemini siblings).
+ * Every other provider meters the account as a whole: one member hitting the
+ * wall means its siblings on the SAME account would too, so the cooldown
+ * parks the account (other accounts of the provider are unaffected).
+ */
+const MODEL_SCOPED_QUOTA_PROVIDERS = new Set(['claude', 'antigravity']);
+/** The `retry-after` an adapter propagated through `httpLlmError`, when any. */
+function retryAfterMs(error) {
+    return error.failure.providerRetryAfterMs;
+}
+/**
+ * Classify a member failure. Quota and rate-limit failures cool down (using
+ * the provider's own `retry-after` when sent, which is more accurate than
+ * any fixed guess) — account-wide for account-metered providers, per-member
+ * for model-scoped ones; auth failures park the account until re-login
+ * (credentials are account-level); server/timeout failures get a short
+ * per-member cooldown; transport failures switch without a record;
+ * everything else — most importantly CONTEXT_WINDOW_EXCEEDED and ABORTED —
+ * is the request's own fault and is rethrown untouched.
+ * @param error - the failure thrown by a member adapter's stream.
+ * @param provider - the failing member's provider (decides the quota scope).
+ * @returns the action the pool should take.
+ */
+export function classifyPoolFailure(error, provider) {
+    if (!(error instanceof LlmError))
+        return { action: 'throw' };
+    switch (error.code) {
+        case QUOTA_EXCEEDED_CODE:
+        case 'RATE_LIMIT':
+            return {
+                action: 'switch',
+                cooldownMs: retryAfterMs(error) ?? DEFAULT_QUOTA_COOLDOWN_MS,
+                reason: error.code,
+                scope: MODEL_SCOPED_QUOTA_PROVIDERS.has(provider) ? 'member' : 'account',
+            };
+        case 'AUTH':
+        case 'INVALID_CREDENTIAL':
+        case 'MISSING_CREDENTIAL':
+            return { action: 'switch', cooldownMs: AUTH_COOLDOWN_MS, reason: error.code, scope: 'account' };
+        case 'SERVER':
+        case 'TIMEOUT':
+        case 'EMPTY_RESPONSE':
+            return { action: 'switch', cooldownMs: TRANSIENT_COOLDOWN_MS, reason: error.code, scope: 'member' };
+        case 'TRANSPORT':
+            return { action: 'switch' };
+        case 'HTTP_402':
+        case 'HTTP_404':
+            // Plan/model availability is account-shaped: another account of the
+            // same subscription may still serve. A 400 that is not a context-window
+            // error stays HTTP_400 and throws (the request itself is at fault).
+            return { action: 'switch', cooldownMs: TRANSIENT_COOLDOWN_MS, reason: error.code, scope: 'member' };
+        case CONTEXT_WINDOW_EXCEEDED_CODE:
+        case 'ABORTED':
+        default:
+            return { action: 'throw' };
+    }
+}
+/**
+ * Cooldown registry keyed by {@link memberKey}. A member whose cooldown has
+ * expired is simply available again — recovery is proven by the next real
+ * request, not by a background probe.
+ */
+export class PoolHealthRegistry {
+    records = new Map();
+    /** Whether a member may serve: neither it nor its whole account is cooling. */
+    isMemberAvailable(provider, account, model, now = Date.now()) {
+        return this.isAvailable(accountKey(provider, account), now)
+            && this.isAvailable(memberKey(provider, account, model), now);
+    }
+    /** Whether one registry key is clear right now. */
+    isAvailable(key, now = Date.now()) {
+        const record = this.records.get(key);
+        if (record === undefined)
+            return true;
+        if (record.unavailableUntil <= now) {
+            this.records.delete(key);
+            return true;
+        }
+        return false;
+    }
+    /** Park a member for `cooldownMs`; a longer existing cooldown wins. */
+    markUnavailable(key, cooldownMs, reason, now = Date.now()) {
+        const until = now + cooldownMs;
+        const existing = this.records.get(key);
+        if (existing !== undefined && existing.unavailableUntil > until)
+            return;
+        this.records.set(key, { unavailableUntil: until, reason });
+    }
+    /**
+     * Epoch ms at which the earliest cooling record among `keys` recovers;
+     * `undefined` when none of them is cooling. The registry is shared by
+     * every pool, so the caller passes the keys of ITS members (member and
+     * account keys alike) — an unrelated pool's cooldown must not shape this
+     * pool's retry hint. Feeds the pool-exhausted error's
+     * `providerRetryAfterMs`.
+     */
+    earliestRecovery(keys, now = Date.now()) {
+        let earliest;
+        for (const [key, record] of this.records) {
+            if (record.unavailableUntil <= now) {
+                this.records.delete(key);
+                continue;
+            }
+            if (!keys.has(key))
+                continue;
+            if (earliest === undefined || record.unavailableUntil < earliest) {
+                earliest = record.unavailableUntil;
+            }
+        }
+        return earliest;
+    }
+    /** Drop records of one provider, or of a single account when given (auth changes). */
+    clear(provider, account) {
+        const prefix = account === undefined ? `${provider}/` : `${provider}/${account}/`;
+        for (const key of [...this.records.keys()]) {
+            if (key.startsWith(prefix))
+                this.records.delete(key);
+        }
+    }
+}