dsh-plugin-subscriptions 0.5.2 → 0.6.0

package/lib/providers/pool.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The pool adapter: same-subscription account routing, plus optional
+ * configured tier extras. The picker is the union of every account's
+ * catalog. A model listed by several accounts failovers; a model listed by
+ * one account is pinned to it. Tiers are extra picker rows. Member
+ * selection is sticky per session (so prompt caches survive) and optionally
+ * quota-aware; failures fail over to the next member as long as no stream
+ * chunk has been emitted.
+ */
+import { LlmAdapter } from '@deepseek-ai/dsh-llm';
+import type { GenerateOptions, LlmModelInfo, LlmResolvedModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { ProviderId } from '../auth/store.js';
+import type { AccountAwareAdapter } from './accounts.js';
+import type { PoolDefinition, PoolMemberRef } from './pool-family.js';
+import { PoolHealthRegistry } from './pool-health.js';
+import type { PoolUsageTracker } from './pool-usage.js';
+/** Member-selection strategy: plain priority failover or quota-aware scheduling. */
+export type PoolStrategy = 'priority' | 'quota_aware';
+export interface PoolAdapterOptions {
+    /** The live subscription adapters, by provider route. */
+    adapters: Partial<Record<ProviderId, AccountAwareAdapter>>;
+    health: PoolHealthRegistry;
+    usage: PoolUsageTracker;
+    strategy: PoolStrategy;
+    /** A challenger must out-urgency the sticky member by this factor to take over. */
+    switchMargin: number;
+    /** The default account of one provider (for config members omitting `account`). */
+    defaultAccount: (provider: ProviderId) => Promise<string | undefined>;
+    /** Account pools (auto-aggregated plus config overrides), resolved lazily. */
+    families: () => Promise<Map<string, PoolDefinition>>;
+    /** User-configured extra picker entries (heterogeneous fallbacks), by pool id. */
+    tiers: Record<string, PoolMemberRef[]>;
+    onWarn: (message: string) => void;
+}
+export declare class PoolAdapter extends LlmAdapter {
+    private readonly options;
+    /** sessionId|poolId → member key of the last member that served a chunk. */
+    private readonly sticky;
+    /** Messages already warned about — configuration diagnostics repeat every request otherwise. */
+    private readonly warned;
+    /**
+     * Short-lived pools snapshot. `owns()` runs on every resolveModel — the
+     * model picker issues one per entry — and pool assembly touches every
+     * provider's catalog and account store, so recompute at most this often.
+     * Auth changes bump {@link generation} so a stale snapshot cannot land.
+     */
+    private poolsCache;
+    private poolsInflight;
+    private generation;
+    constructor(options: PoolAdapterOptions);
+    /** Drop the pools snapshot so the next read reflects the current accounts. */
+    invalidate(): void;
+    /** Warn once per distinct message (pools() runs on every request). */
+    private warnOnce;
+    /** Drop members whose adapter is not registered (copy — caller state is shared). */
+    private usable;
+    /** Account pools (auto-aggregated plus config overrides) with usable members. */
+    private familyPools;
+    /** All pools (account pools merged with extra tiers) with usable members. */
+    private pools;
+    /** Recompute the pools snapshot (account pools merged with extra tiers). */
+    private assemblePools;
+    /**
+     * Extra picker rows one provider lists (configured tiers). Account pools
+     * reuse the catalog entry of the same wire id, so they are not listed
+     * again — the picker stays one row per model in ChatGPT / Claude / ….
+     */
+    modelsForProvider(provider: ProviderId): Promise<LlmModelInfo[]>;
+    /**
+     * Whether `model` on `provider`'s route is served here (several accounts
+     * fail over, one account is pinned, or a configured tier).
+     */
+    owns(provider: ProviderId, model: string): Promise<boolean>;
+    /**
+     * Resolve every member's account (config members may omit it to mean "the
+     * default account") and drop members with no resolvable login. Duplicates
+     * collapse — an explicitly pinned account and the default may coincide.
+     */
+    private concrete;
+    /**
+     * Resolve a pool model to the conservative INTERSECTION of its members'
+     * capabilities: the smallest context window and output cap, the reasoning
+     * efforts every member supports, and the modalities all of them accept —
+     * so a request valid for the pool stays valid after a failover. Capability
+     * metadata is provider-level, so each provider resolves once regardless of
+     * how many accounts it pools.
+     */
+    resolveModel(provider: string, model: string): Promise<LlmResolvedModelInfo>;
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+    /**
+     * Order the candidates for one request. Health filters both strategies;
+     * `quota_aware` then ranks by urgency (members without telemetry, e.g.
+     * copilot, score zero and sink to the bottom of their class), while
+     * quota-exhausted members stay as a last-resort tail in pool order. The
+     * sticky member keeps its lead unless a challenger out-scores it by
+     * `switchMargin`.
+     */
+    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).
+     */
+    private exhausted;
+}

package/lib/providers/pool.js

@@ -0,0 +1,371 @@
+/**
+ * The pool adapter: same-subscription account routing, plus optional
+ * configured tier extras. The picker is the union of every account's
+ * catalog. A model listed by several accounts failovers; a model listed by
+ * one account is pinned to it. Tiers are extra picker rows. Member
+ * selection is sticky per session (so prompt caches survive) and optionally
+ * quota-aware; failures fail over to the next member as long as no stream
+ * chunk has been emitted.
+ */
+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';
+/** Bound on sticky-session memory; oldest entries evict past it. */
+const STICKY_SESSION_LIMIT = 1000;
+/** Display form of one member (account shown when pinned). */
+function memberLabel(member) {
+    return member.account === undefined
+        ? `${member.provider}/${member.model}`
+        : `${member.provider}/${member.account}/${member.model}`;
+}
+/** How long a pools snapshot is trusted (auth changes invalidate immediately). */
+const POOLS_CACHE_TTL_MS = 5_000;
+export class PoolAdapter extends LlmAdapter {
+    options;
+    /** sessionId|poolId → member key of the last member that served a chunk. */
+    sticky = new Map();
+    /** Messages already warned about — configuration diagnostics repeat every request otherwise. */
+    warned = new Set();
+    /**
+     * Short-lived pools snapshot. `owns()` runs on every resolveModel — the
+     * model picker issues one per entry — and pool assembly touches every
+     * provider's catalog and account store, so recompute at most this often.
+     * Auth changes bump {@link generation} so a stale snapshot cannot land.
+     */
+    poolsCache;
+    poolsInflight;
+    generation = 0;
+    constructor(options) {
+        super();
+        this.options = options;
+    }
+    /** Drop the pools snapshot so the next read reflects the current accounts. */
+    invalidate() {
+        this.generation += 1;
+        this.poolsCache = undefined;
+        this.poolsInflight = undefined;
+    }
+    /** Warn once per distinct message (pools() runs on every request). */
+    warnOnce(message) {
+        if (this.warned.has(message))
+            return;
+        this.warned.add(message);
+        this.options.onWarn(message);
+    }
+    /** Drop members whose adapter is not registered (copy — caller state is shared). */
+    usable(pools) {
+        const result = new Map(pools);
+        for (const [id, definition] of [...result]) {
+            const kept = definition.members.filter(member => this.options.adapters[member.provider] !== undefined);
+            if (kept.length === 0)
+                result.delete(id);
+            else if (kept.length < definition.members.length)
+                result.set(id, { ...definition, members: kept });
+        }
+        return result;
+    }
+    /** Account pools (auto-aggregated plus config overrides) with usable members. */
+    async familyPools() {
+        return this.usable(new Map(await this.options.families()));
+    }
+    /** All pools (account pools merged with extra tiers) with usable members. */
+    async pools() {
+        const cached = this.poolsCache;
+        if (cached !== undefined && Date.now() - cached.at < POOLS_CACHE_TTL_MS)
+            return cached.pools;
+        const gen = this.generation;
+        this.poolsInflight ??= this.assemblePools()
+            .then((pools) => {
+            if (this.generation === gen)
+                this.poolsCache = { at: Date.now(), pools };
+            return pools;
+        })
+            .finally(() => {
+            this.poolsInflight = undefined;
+        });
+        return this.poolsInflight;
+    }
+    /** Recompute the pools snapshot (account pools merged with extra tiers). */
+    async assemblePools() {
+        const pools = await this.familyPools();
+        for (const [id, members] of Object.entries(this.options.tiers)) {
+            if (members.length === 0)
+                continue;
+            const owner = members[0].provider;
+            const key = poolKey(owner, id);
+            if (pools.has(key))
+                this.warnOnce(`tier pool "${id}" overrides the account pool of the same id under ${owner}`);
+            pools.set(key, { members, extra: true });
+        }
+        return this.usable(pools);
+    }
+    /**
+     * Extra picker rows one provider lists (configured tiers). Account pools
+     * reuse the catalog entry of the same wire id, so they are not listed
+     * again — the picker stays one row per model in ChatGPT / Claude / ….
+     */
+    async modelsForProvider(provider) {
+        const pools = await this.pools();
+        const models = [];
+        for (const [key, definition] of pools) {
+            if (definition.extra !== true)
+                continue;
+            if (!key.startsWith(`${provider}/`))
+                continue;
+            const id = key.slice(provider.length + 1);
+            models.push({
+                provider,
+                id,
+                name: definition.name ?? id,
+                ...definition.description === undefined ? {} : { description: definition.description },
+            });
+        }
+        return models;
+    }
+    /**
+     * Whether `model` on `provider`'s route is served here (several accounts
+     * fail over, one account is pinned, or a configured tier).
+     */
+    async owns(provider, model) {
+        return (await this.pools()).has(poolKey(provider, model));
+    }
+    /**
+     * Resolve every member's account (config members may omit it to mean "the
+     * default account") and drop members with no resolvable login. Duplicates
+     * collapse — an explicitly pinned account and the default may coincide.
+     */
+    async concrete(members) {
+        const seen = new Set();
+        const resolved = [];
+        for (const member of members) {
+            const account = member.account ?? await this.options.defaultAccount(member.provider);
+            if (account === undefined)
+                continue;
+            const key = memberKey(member.provider, account, member.model);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            resolved.push({ provider: member.provider, account, model: member.model });
+        }
+        return resolved;
+    }
+    /**
+     * Resolve a pool model to the conservative INTERSECTION of its members'
+     * capabilities: the smallest context window and output cap, the reasoning
+     * efforts every member supports, and the modalities all of them accept —
+     * so a request valid for the pool stays valid after a failover. Capability
+     * metadata is provider-level, so each provider resolves once regardless of
+     * how many accounts it pools.
+     */
+    async resolveModel(provider, model) {
+        const definition = (await this.pools()).get(poolKey(provider, model));
+        if (definition === undefined)
+            throw new LlmError(`unknown pool model "${model}"`, 'NO_ADAPTER');
+        const resolved = [];
+        let lastFailure;
+        const seenProviders = new Set();
+        for (const member of definition.members) {
+            if (seenProviders.has(member.provider))
+                continue;
+            seenProviders.add(member.provider);
+            const adapter = this.options.adapters[member.provider];
+            if (adapter === undefined)
+                continue;
+            // Tolerate per-member failures (a misconfigured tier member, a
+            // logged-out provider throwing AUTH): the pool serves as long as ONE
+            // member resolves, mirroring stream()'s failover semantics.
+            try {
+                resolved.push(await adapter.resolveOwnModel(member.provider, member.model));
+            }
+            catch (error) {
+                lastFailure = error;
+                this.warnOnce(`pool "${model}": member ${memberLabel(member)} failed to resolve`
+                    + ` (${error instanceof Error ? error.message : String(error)}); excluding it`);
+            }
+        }
+        if (resolved.length === 0) {
+            throw new LlmError(`pool "${model}" has no usable member`, 'NO_ADAPTER', {
+                ...lastFailure === undefined ? {} : { cause: lastFailure },
+            });
+        }
+        const contextWindows = resolved.map(info => info.context?.contextWindow).filter(isNumber);
+        const maxTokens = resolved.map(info => info.defaultMaxTokens).filter(isNumber);
+        const reasoning = intersectReasoning(resolved);
+        const modalities = intersectModalities(resolved);
+        return {
+            provider,
+            id: model,
+            name: definition.name ?? model,
+            ...definition.description === undefined ? {} : { description: definition.description },
+            ...contextWindows.length > 0 ? { context: { contextWindow: Math.min(...contextWindows) } } : {},
+            ...maxTokens.length > 0 ? { defaultMaxTokens: Math.min(...maxTokens) } : {},
+            ...reasoning === undefined ? {} : { reasoning },
+            ...modalities === undefined ? {} : { inputModalities: modalities },
+        };
+    }
+    async *stream(options) {
+        const definition = (await this.pools()).get(poolKey(options.provider, options.model));
+        if (definition === undefined)
+            throw new LlmError(`unknown pool model "${options.model}"`, 'NO_ADAPTER');
+        const members = await this.concrete(definition.members);
+        const candidates = await this.select(options.model, members, options.sessionId);
+        if (candidates.length === 0)
+            throw this.exhausted(options.model, members);
+        let lastError;
+        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]();
+            let first;
+            try {
+                first = await iterator.next();
+                if (first.done === true) {
+                    throw new LlmError(`${memberLabel(member)} returned an empty stream`, EMPTY_RESPONSE_CODE);
+                }
+            }
+            catch (error) {
+                const classification = classifyPoolFailure(error, member.provider);
+                if (classification.action === 'throw')
+                    throw error;
+                if ('cooldownMs' in classification) {
+                    this.options.health.markUnavailable(classification.scope === 'account'
+                        ? accountKey(member.provider, member.account)
+                        : memberKey(member.provider, member.account, member.model), classification.cooldownMs, classification.reason);
+                    // A quota failure invalidates the cached usage snapshot so the NEXT
+                    // selection re-polls instead of trusting minutes-old percentages.
+                    // Transient/auth failures say nothing about quota — keep the cache.
+                    if (classification.reason === QUOTA_EXCEEDED_CODE || classification.reason === 'RATE_LIMIT') {
+                        this.options.usage.invalidate(member.provider, member.account);
+                    }
+                }
+                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;
+                continue;
+            }
+            this.remember(options.model, options.sessionId, member);
+            // Past the first chunk there is no clean attempt boundary: whatever
+            // the member does next (including failing) reaches the caller as-is.
+            // The finally closes the member stream when the CALLER walks away
+            // early (break / .return()) — manual iteration does not propagate
+            // closure the way `yield*` would, and a half-consumed member stream
+            // must not linger holding its connection.
+            try {
+                yield first.value;
+                for (let next = await iterator.next(); next.done !== true; next = await iterator.next()) {
+                    yield next.value;
+                }
+            }
+            finally {
+                try {
+                    await iterator.return?.();
+                }
+                catch {
+                    // Closing a half-consumed member stream must not mask the outcome.
+                }
+            }
+            return;
+        }
+        throw this.exhausted(options.model, members, lastError);
+    }
+    /**
+     * Order the candidates for one request. Health filters both strategies;
+     * `quota_aware` then ranks by urgency (members without telemetry, e.g.
+     * copilot, score zero and sink to the bottom of their class), while
+     * quota-exhausted members stay as a last-resort tail in pool order. The
+     * sticky member keeps its lead unless a challenger out-scores it by
+     * `switchMargin`.
+     */
+    async select(poolId, members, sessionId) {
+        const usable = members.filter(member => this.options.adapters[member.provider] !== undefined
+            && this.options.health.isMemberAvailable(member.provider, member.account, member.model));
+        if (usable.length === 0)
+            return [];
+        const stickyMember = sessionId === undefined
+            ? undefined
+            : usable.find(member => memberKey(member.provider, member.account, member.model) === this.sticky.get(stickyKey(poolId, sessionId)));
+        if (this.options.strategy === 'priority') {
+            return stickyMember === undefined
+                ? usable
+                : [stickyMember, ...usable.filter(member => member !== stickyMember)];
+        }
+        const quotas = new Map(await Promise.all(usable.map(async (member) => [member, await this.options.usage.quotaFor(member)])));
+        const scored = usable.filter(member => quotas.get(member)?.available === true);
+        const quotaFull = usable.filter(member => quotas.get(member)?.available === false);
+        scored.sort((a, b) => (quotas.get(b)?.urgency ?? 0) - (quotas.get(a)?.urgency ?? 0));
+        if (stickyMember !== undefined && scored.includes(stickyMember)) {
+            const best = scored[0];
+            const stickyUrgency = quotas.get(stickyMember)?.urgency ?? 0;
+            const bestUrgency = quotas.get(best)?.urgency ?? 0;
+            if (best === stickyMember || bestUrgency <= stickyUrgency * this.options.switchMargin) {
+                // Sticky holds (no challenger beats it by the margin): lead with it.
+                scored.splice(scored.indexOf(stickyMember), 1);
+                scored.unshift(stickyMember);
+            }
+        }
+        return [...scored, ...quotaFull];
+    }
+    /** Pin the serving member to the session (with bounded memory). */
+    remember(poolId, sessionId, member) {
+        if (sessionId === undefined)
+            return;
+        const key = stickyKey(poolId, sessionId);
+        this.sticky.delete(key);
+        if (this.sticky.size >= STICKY_SESSION_LIMIT) {
+            const oldest = this.sticky.keys().next();
+            if (oldest.done !== true)
+                this.sticky.delete(oldest.value);
+        }
+        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) {
+        const keys = new Set();
+        for (const member of pool) {
+            keys.add(memberKey(member.provider, member.account, member.model));
+            keys.add(accountKey(member.provider, member.account));
+        }
+        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', {
+            ...retryAfterMs === undefined ? {} : { providerRetryAfterMs: retryAfterMs },
+            ...cause === undefined ? {} : { cause },
+        });
+    }
+}
+function stickyKey(poolId, sessionId) {
+    return `${String(sessionId)}|${poolId}`;
+}
+function isNumber(value) {
+    return value !== undefined;
+}
+/** Reasoning efforts every member supports (id intersection, first member's order). */
+function intersectReasoning(resolved) {
+    const [first, ...rest] = resolved;
+    if (first?.reasoning === undefined)
+        return undefined;
+    const efforts = first.reasoning.efforts.filter(effort => rest.every(info => info.reasoning?.efforts.some(other => other.id === effort.id) === true));
+    if (efforts.length === 0)
+        return undefined;
+    const defaultEffort = first.reasoning.defaultEffort !== undefined
+        && efforts.some(effort => effort.id === first.reasoning?.defaultEffort)
+        ? first.reasoning.defaultEffort
+        : undefined;
+    return { efforts, ...defaultEffort === undefined ? {} : { defaultEffort } };
+}
+/** Modalities all members accept; undefined when any member leaves it unknown. */
+function intersectModalities(resolved) {
+    const [first, ...rest] = resolved;
+    if (first?.inputModalities === undefined)
+        return undefined;
+    const modalities = first.inputModalities.filter(modality => rest.every(info => info.inputModalities?.includes(modality) === true));
+    // An empty intersection would declare negative capability ("accepts
+    // nothing"); report unknown instead — the serving member enforces its own
+    // limits at request time.
+    return modalities.length === 0 ? undefined : modalities;
+}

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

@@ -0,0 +1,192 @@
+/**
+ * Rate-limit window handling shared by the subscription adapters.
+ *
+ * A subscription plan is rate-limit shaped by design — a five-hour session
+ * window, a weekly window, and on some plans a per-model weekly one — so a 429
+ * is not a dead end: the window reopens at a time the provider discloses. This
+ * module turns that disclosure into the `providerRetryAfterMs` the optional
+ * `@deepseek-ai/dsh-llm-retry` plugin waits out, and resolves the retry policy
+ * whose `maxDelayMs` decides how long a route is allowed to hold the turn.
+ *
+ * The wait itself is provider-independent: adapters own the policy, the retry
+ * plugin executes it. Only the extraction of the reset instant differs, so each
+ * adapter contributes one {@link RateLimitResetReader} built from the parsing
+ * primitives here.
+ *
+ * @module dsh-plugin-subscriptions/providers/rate-limit
+ */
+import type { ResolvedRetryPolicy } from '@deepseek-ai/dsh-llm';
+/**
+ * Reads the instant one provider's rate-limit window reopens off a 429.
+ * @param response - the failed response, for its headers.
+ * @param body - the complete response body (never truncated: readers parse JSON).
+ * @param now - the current epoch milliseconds, injected so parsing is testable.
+ * @returns epoch milliseconds of the reset, or undefined when the provider said nothing.
+ */
+export type RateLimitResetReader = (response: Response, body: string, now: number) => number | undefined;
+/** Default ceiling on a rate-limit wait: six hours covers a five-hour session window with slack. */
+export declare const DEFAULT_RATE_LIMIT_MAX_WAIT_MS: number;
+/**
+ * Interpret a bare numeric rate-limit value, which providers write in three
+ * shapes: epoch milliseconds, epoch seconds, or a delay in seconds. The
+ * magnitude separates them unambiguously for any plausible value — an epoch in
+ * seconds is ~1.8e9 today, while a delay of even a full week is ~6e5.
+ * @param value - the raw numeric value.
+ * @param now - the current epoch milliseconds.
+ * @returns epoch milliseconds of the reset, or undefined when the value is unusable.
+ */
+export declare function resetInstantFromNumber(value: number, now: number): number | undefined;
+/**
+ * Parse a Go-style duration (`6m0s`, `1h2m3.5s`, `150ms`) into milliseconds —
+ * the form OpenAI-compatible `x-ratelimit-reset-*` headers use.
+ * @param text - the raw header value.
+ * @returns the duration in milliseconds, or undefined when the text is not one.
+ */
+export declare function durationMs(text: string): number | undefined;
+/**
+ * Interpret any single rate-limit value — a number, a numeric string, a
+ * duration (`6m0s`), or a date — as the instant a window reopens. One reader
+ * for every shape, so a provider that changes the encoding of a field it
+ * already sends does not need a code change here.
+ * @param value - the raw header value or JSON field.
+ * @param now - the current epoch milliseconds.
+ * @returns epoch milliseconds of the reset, or undefined when the value is unusable.
+ */
+export declare function resetInstantFromValue(value: unknown, now: number): number | undefined;
+/**
+ * Read a header carrying any of the {@link resetInstantFromValue} shapes.
+ * @param response - the failed response.
+ * @param name - the header to read.
+ * @param now - the current epoch milliseconds.
+ * @returns epoch milliseconds of the reset, or undefined when absent or unusable.
+ */
+export declare function resetInstantFromHeader(response: Response, name: string, now: number): number | undefined;
+/**
+ * Read the RFC 7231 `retry-after` header in both its forms: a delay in seconds
+ * (never an epoch stamp, whatever its magnitude) or an HTTP-date.
+ * @param response - the failed response.
+ * @param now - the current epoch milliseconds.
+ * @returns epoch milliseconds of the reset, or undefined when absent or unusable.
+ */
+export declare function retryAfterInstant(response: Response, now: number): number | undefined;
+/**
+ * Parse a response body as JSON without throwing on the non-JSON bodies
+ * providers occasionally return under load (an HTML gateway page, say).
+ * @param body - the complete response body.
+ * @returns the parsed value, or undefined when the body is not JSON.
+ */
+export declare function jsonBody(body: string): unknown;
+/**
+ * Find a reset instant under any of the named keys, anywhere in a parsed body.
+ *
+ * The search is by key rather than by path on purpose: providers move the same
+ * field between containers (`detail`, `error`, top level) across endpoints and
+ * versions, and a path-shaped reader silently stops working when they do. Only
+ * the key list is provider-specific.
+ * @param value - the parsed body, or any nested value.
+ * @param keys - field names this provider uses for a reset or delay.
+ * @param now - the current epoch milliseconds.
+ * @param depth - remaining recursion depth.
+ * @returns the earliest instant found, or undefined when no key matched.
+ */
+export declare function resetFromFields(value: unknown, keys: readonly string[], now: number, depth?: number): number | undefined;
+/**
+ * The earliest of several candidate reset instants, ignoring absent ones. The
+ * earliest is the one that matters: it is the first moment any of the reported
+ * limits allows a request again.
+ * @param candidates - reset instants in no particular order.
+ * @returns the earliest instant, or undefined when every candidate is absent.
+ */
+export declare function earliestReset(...candidates: (number | undefined)[]): number | undefined;
+/**
+ * Turn a reset instant into the wait to report as `providerRetryAfterMs`.
+ *
+ * Deliberately not capped: a reset beyond the policy's `maxDelayMs` makes the
+ * retry plugin delegate immediately, failing the turn at once with the real
+ * reset in the message, rather than clamping the wait down and burning the
+ * retry budget against a window that is still closed.
+ * @param instant - epoch milliseconds the window reopens.
+ * @param now - the current epoch milliseconds.
+ * @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. */
+    readonly maxRetries: number;
+    /** First local backoff delay. */
+    readonly initialDelayMs: number;
+    /** Local backoff ceiling, and the accepted-provider-delay ceiling when waiting is off. */
+    readonly maxDelayMs: number;
+    /** Symmetric jitter around each local delay. */
+    readonly jitterRatio: number;
+}
+/**
+ * The retry shape every subscription route starts from: Claude Code's own SDK
+ * numbers — ten retries after the first attempt, exponential backoff from 1s
+ * doubling per attempt, capped at 60s, plus 20% jitter.
+ *
+ * Shared across all four routes rather than kept to claude, because what these
+ * numbers are tuned for is the shape of a subscription endpoint — a consumer
+ * plan behind a session window, which sheds load in bursts and rewards an
+ * attempt that outlasts them — and that is the same on all four. The dsh-llm
+ * defaults (5 retries from 500ms to 10s) give up after about fifteen seconds,
+ * which is short for that.
+ *
+ * The 60s cap governs local backoff only: a disclosed rate-limit reset is
+ * accepted up to the configured wait ceiling instead.
+ */
+export declare const DEFAULT_RETRY: RetryDefaults;
+/** How long a route may hold a turn open waiting for a rate-limit window. */
+export interface RateLimitWait {
+    /** Whether a disclosed reset may be waited out at all. */
+    readonly wait: boolean;
+    /** Ceiling on one wait; a reset further out fails the turn instead. */
+    readonly maxWaitMs: number;
+}
+/** Rate-limit waiting as the plugin config accepts it. */
+export interface RateLimitConfig {
+    /** Wait for a disclosed reset instead of failing the turn (default true). */
+    wait?: boolean;
+    /** Ceiling on one wait in milliseconds (default six hours). */
+    maxWaitMs?: number;
+}
+/** Waiting behavior a route falls back to when the plugin passed none (waiting on, six-hour ceiling). */
+export declare const DEFAULT_RATE_LIMIT_WAIT: RateLimitWait;
+/**
+ * Validate and default the rate-limit waiting config.
+ * @param config - the raw plugin config section, when present.
+ * @param path - diagnostic path naming the config that owns the value.
+ * @returns the resolved, immutable behavior.
+ */
+export declare function resolveRateLimitWait(config: RateLimitConfig | undefined, path: string): RateLimitWait;
+/**
+ * Resolve one route's retry policy, widening the delay ceiling to the
+ * configured wait so a disclosed reset hours out is accepted rather than
+ * refused.
+ *
+ * The ceiling is shared with local exponential backoff, so widening it also
+ * raises how long an unrelated transient failure may back off for. That stays
+ * bounded by the finite retry budget — the claude route's ten retries reach
+ * 512 s per attempt at most — and it only governs when the provider disclosed
+ * nothing, which is exactly the case where a longer wait is the safer guess.
+ * @param defaults - the route's retry shape.
+ * @param rateLimit - resolved waiting behavior.
+ * @param path - diagnostic path naming the provider route.
+ * @returns the policy to report from `providerRetryPolicy`.
+ */
+export declare function subscriptionRetryPolicy(defaults: RetryDefaults, rateLimit: RateLimitWait, path: string): ResolvedRetryPolicy;