@leaves615/dsh-llm-ctl 0.1.0

package/lib/concurrency.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Per-provider concurrency resolution.
+ *
+ * The wire value {@link UNLIMITED_CONCURRENCY} (`0`) means "no cap". Inside
+ * the gate it is normalized to `Infinity`, so every existing comparison
+ * (`active < limit`) and ETA estimate keeps working without a special case.
+ * State payloads and settings always carry the wire value, never `Infinity`
+ * (which JSON would silently turn into `null`).
+ *
+ * @module dsh-llm-ctl/concurrency
+ */
+/** Wire value meaning "no concurrency cap" in settings, routes, and state. */
+export declare const UNLIMITED_CONCURRENCY = 0;
+/**
+ * Resolve one provider's effective concurrency.
+ *
+ * An explicit entry wins (including `0` = unlimited for that provider);
+ * otherwise the table's `default` applies; without either, the provider is
+ * unlimited. There is deliberately no special case for free/shared routes:
+ * fragility there is handled by rate-limit cooldown, not by a default cap.
+ *
+ * @param table - per-provider table; the reserved key `default` applies to
+ * every provider without an explicit entry. `0` (or a negative number,
+ * defensively) means unlimited.
+ * @param provider - provider id to resolve.
+ * @returns the effective cap, or `Infinity` when uncapped.
+ */
+export declare function concurrencyFor(table: Record<string, number>, provider: string): number;

package/lib/concurrency.js

@@ -0,0 +1,36 @@
+/**
+ * Per-provider concurrency resolution.
+ *
+ * The wire value {@link UNLIMITED_CONCURRENCY} (`0`) means "no cap". Inside
+ * the gate it is normalized to `Infinity`, so every existing comparison
+ * (`active < limit`) and ETA estimate keeps working without a special case.
+ * State payloads and settings always carry the wire value, never `Infinity`
+ * (which JSON would silently turn into `null`).
+ *
+ * @module dsh-llm-ctl/concurrency
+ */
+/** Wire value meaning "no concurrency cap" in settings, routes, and state. */
+export const UNLIMITED_CONCURRENCY = 0;
+/**
+ * Resolve one provider's effective concurrency.
+ *
+ * An explicit entry wins (including `0` = unlimited for that provider);
+ * otherwise the table's `default` applies; without either, the provider is
+ * unlimited. There is deliberately no special case for free/shared routes:
+ * fragility there is handled by rate-limit cooldown, not by a default cap.
+ *
+ * @param table - per-provider table; the reserved key `default` applies to
+ * every provider without an explicit entry. `0` (or a negative number,
+ * defensively) means unlimited.
+ * @param provider - provider id to resolve.
+ * @returns the effective cap, or `Infinity` when uncapped.
+ */
+export function concurrencyFor(table, provider) {
+    const exact = table[provider];
+    if (exact !== undefined)
+        return exact <= 0 ? Infinity : exact;
+    const fallback = table['default'];
+    if (fallback === undefined || fallback <= 0)
+        return Infinity;
+    return fallback;
+}

package/lib/config.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Plugin configuration schema and normalization.
+ *
+ * @module dsh-llm-ctl/config
+ */
+import z from '@deepseek-ai/schemastery';
+import type { BackoffConfig } from './delay.ts';
+export { UNLIMITED_CONCURRENCY, concurrencyFor } from './concurrency.ts';
+/** Single wait budget covering both queue patience and honored cooldown. */
+export declare const DEFAULT_MAX_WAIT_MS = 120000;
+/** Default bounded budget for standalone recovery when no retry executor is mounted. */
+export declare const DEFAULT_REACTIVE_RETRIES = 3;
+/** Local backoff used when a provider supplies no hint. */
+export declare const BackoffConfigSchema: z<Schemastery.ObjectS<{
+    initialDelayMs: z<number, number>;
+    maxDelayMs: z<number, number>;
+    jitterRatio: z<number, number>;
+}>, Schemastery.ObjectT<{
+    initialDelayMs: z<number, number>;
+    maxDelayMs: z<number, number>;
+    jitterRatio: z<number, number>;
+}>>;
+/** Admission queue configuration. */
+export declare const QueueConfigSchema: z<Schemastery.ObjectS<{
+    /**
+     * Per-provider concurrency. The reserved key `default` applies to every
+     * provider without an explicit entry; free routes fall back to 1.
+     */
+    perProviderConcurrency: z<import("@deepseek-ai/cosmokit").Dict<number, string>, import("@deepseek-ai/cosmokit").Dict<number, string>>;
+    maxQueueDepth: z<number, number>;
+    maxWaitMs: z<number, number>;
+    honorRetryAfter: z<boolean, boolean>;
+    backoff: z<Schemastery.ObjectS<{
+        initialDelayMs: z<number, number>;
+        maxDelayMs: z<number, number>;
+        jitterRatio: z<number, number>;
+    }>, Schemastery.ObjectT<{
+        initialDelayMs: z<number, number>;
+        maxDelayMs: z<number, number>;
+        jitterRatio: z<number, number>;
+    }>>;
+}>, Schemastery.ObjectT<{
+    /**
+     * Per-provider concurrency. The reserved key `default` applies to every
+     * provider without an explicit entry; free routes fall back to 1.
+     */
+    perProviderConcurrency: z<import("@deepseek-ai/cosmokit").Dict<number, string>, import("@deepseek-ai/cosmokit").Dict<number, string>>;
+    maxQueueDepth: z<number, number>;
+    maxWaitMs: z<number, number>;
+    honorRetryAfter: z<boolean, boolean>;
+    backoff: z<Schemastery.ObjectS<{
+        initialDelayMs: z<number, number>;
+        maxDelayMs: z<number, number>;
+        jitterRatio: z<number, number>;
+    }>, Schemastery.ObjectT<{
+        initialDelayMs: z<number, number>;
+        maxDelayMs: z<number, number>;
+        jitterRatio: z<number, number>;
+    }>>;
+}>>;
+/** Visibility presets owned by the composition, not by the user layer. */
+export declare const VisibilityConfigSchema: z<Schemastery.ObjectS<{
+    /** Read-only glob patterns; only \`*\` is a metacharacter. */
+    hiddenPatterns: z<string[], string[]>;
+}>, Schemastery.ObjectT<{
+    /** Read-only glob patterns; only \`*\` is a metacharacter. */
+    hiddenPatterns: z<string[], string[]>;
+}>>;
+/** Whole-plugin configuration. */
+export declare const Config: z<Schemastery.ObjectS<{
+    queue: z<Schemastery.ObjectS<{
+        /**
+         * Per-provider concurrency. The reserved key `default` applies to every
+         * provider without an explicit entry; free routes fall back to 1.
+         */
+        perProviderConcurrency: z<import("@deepseek-ai/cosmokit").Dict<number, string>, import("@deepseek-ai/cosmokit").Dict<number, string>>;
+        maxQueueDepth: z<number, number>;
+        maxWaitMs: z<number, number>;
+        honorRetryAfter: z<boolean, boolean>;
+        backoff: z<Schemastery.ObjectS<{
+            initialDelayMs: z<number, number>;
+            maxDelayMs: z<number, number>;
+            jitterRatio: z<number, number>;
+        }>, Schemastery.ObjectT<{
+            initialDelayMs: z<number, number>;
+            maxDelayMs: z<number, number>;
+            jitterRatio: z<number, number>;
+        }>>;
+    }>, Schemastery.ObjectT<{
+        /**
+         * Per-provider concurrency. The reserved key `default` applies to every
+         * provider without an explicit entry; free routes fall back to 1.
+         */
+        perProviderConcurrency: z<import("@deepseek-ai/cosmokit").Dict<number, string>, import("@deepseek-ai/cosmokit").Dict<number, string>>;
+        maxQueueDepth: z<number, number>;
+        maxWaitMs: z<number, number>;
+        honorRetryAfter: z<boolean, boolean>;
+        backoff: z<Schemastery.ObjectS<{
+            initialDelayMs: z<number, number>;
+            maxDelayMs: z<number, number>;
+            jitterRatio: z<number, number>;
+        }>, Schemastery.ObjectT<{
+            initialDelayMs: z<number, number>;
+            maxDelayMs: z<number, number>;
+            jitterRatio: z<number, number>;
+        }>>;
+    }>>;
+    visibility: z<Schemastery.ObjectS<{
+        /** Read-only glob patterns; only \`*\` is a metacharacter. */
+        hiddenPatterns: z<string[], string[]>;
+    }>, Schemastery.ObjectT<{
+        /** Read-only glob patterns; only \`*\` is a metacharacter. */
+        hiddenPatterns: z<string[], string[]>;
+    }>>;
+    /**
+     * Standalone recovery budget. `auto` engages only when the
+     * `agent/request-error` waterfall reaches no downstream retry decision;
+     * `off` never retries; a number caps retries per step.
+     */
+    reactiveRetry: z<number | "auto" | "off", number | "auto" | "off">;
+}>, Schemastery.ObjectT<{
+    queue: z<Schemastery.ObjectS<{
+        /**
+         * Per-provider concurrency. The reserved key `default` applies to every
+         * provider without an explicit entry; free routes fall back to 1.
+         */
+        perProviderConcurrency: z<import("@deepseek-ai/cosmokit").Dict<number, string>, import("@deepseek-ai/cosmokit").Dict<number, string>>;
+        maxQueueDepth: z<number, number>;
+        maxWaitMs: z<number, number>;
+        honorRetryAfter: z<boolean, boolean>;
+        backoff: z<Schemastery.ObjectS<{
+            initialDelayMs: z<number, number>;
+            maxDelayMs: z<number, number>;
+            jitterRatio: z<number, number>;
+        }>, Schemastery.ObjectT<{
+            initialDelayMs: z<number, number>;
+            maxDelayMs: z<number, number>;
+            jitterRatio: z<number, number>;
+        }>>;
+    }>, Schemastery.ObjectT<{
+        /**
+         * Per-provider concurrency. The reserved key `default` applies to every
+         * provider without an explicit entry; free routes fall back to 1.
+         */
+        perProviderConcurrency: z<import("@deepseek-ai/cosmokit").Dict<number, string>, import("@deepseek-ai/cosmokit").Dict<number, string>>;
+        maxQueueDepth: z<number, number>;
+        maxWaitMs: z<number, number>;
+        honorRetryAfter: z<boolean, boolean>;
+        backoff: z<Schemastery.ObjectS<{
+            initialDelayMs: z<number, number>;
+            maxDelayMs: z<number, number>;
+            jitterRatio: z<number, number>;
+        }>, Schemastery.ObjectT<{
+            initialDelayMs: z<number, number>;
+            maxDelayMs: z<number, number>;
+            jitterRatio: z<number, number>;
+        }>>;
+    }>>;
+    visibility: z<Schemastery.ObjectS<{
+        /** Read-only glob patterns; only \`*\` is a metacharacter. */
+        hiddenPatterns: z<string[], string[]>;
+    }>, Schemastery.ObjectT<{
+        /** Read-only glob patterns; only \`*\` is a metacharacter. */
+        hiddenPatterns: z<string[], string[]>;
+    }>>;
+    /**
+     * Standalone recovery budget. `auto` engages only when the
+     * `agent/request-error` waterfall reaches no downstream retry decision;
+     * `off` never retries; a number caps retries per step.
+     */
+    reactiveRetry: z<number | "auto" | "off", number | "auto" | "off">;
+}>>;
+/** Normalized configuration used by the runtime. */
+export interface ResolvedConfig {
+    queue: {
+        perProviderConcurrency: Record<string, number>;
+        maxQueueDepth: number;
+        maxWaitMs: number;
+        honorRetryAfter: boolean;
+        backoff: BackoffConfig;
+    };
+    /** `auto` is resolved to a numeric cap; 0 means disabled. */
+    reactiveRetryLimit: number;
+    reactiveRetryMode: 'auto' | 'off' | number;
+    /** Composition-level hide patterns (read-only for the user layer). */
+    hiddenPatterns: readonly string[];
+}
+/** Configuration shape accepted by {@link resolveConfig}. */
+export interface ConfigInput {
+    queue?: {
+        perProviderConcurrency?: Record<string, number>;
+        maxQueueDepth?: number;
+        maxWaitMs?: number;
+        honorRetryAfter?: boolean;
+        backoff?: Partial<BackoffConfig>;
+    };
+    reactiveRetry?: 'auto' | 'off' | number;
+    visibility?: {
+        hiddenPatterns?: readonly string[];
+    };
+}
+/** Normalize raw plugin config, applying every documented default. */
+export declare function resolveConfig(input: ConfigInput | undefined): ResolvedConfig;

package/lib/config.js

@@ -0,0 +1,67 @@
+/**
+ * Plugin configuration schema and normalization.
+ *
+ * @module dsh-llm-ctl/config
+ */
+import z from '@deepseek-ai/schemastery';
+export { UNLIMITED_CONCURRENCY, concurrencyFor } from "./concurrency.js";
+/** Single wait budget covering both queue patience and honored cooldown. */
+export const DEFAULT_MAX_WAIT_MS = 120_000;
+/** Default bounded budget for standalone recovery when no retry executor is mounted. */
+export const DEFAULT_REACTIVE_RETRIES = 3;
+/** Local backoff used when a provider supplies no hint. */
+export const BackoffConfigSchema = z.object({
+    initialDelayMs: z.number().min(0).default(500),
+    maxDelayMs: z.number().min(0).default(10_000),
+    jitterRatio: z.number().min(0).max(1).default(0.1),
+});
+/** Admission queue configuration. */
+export const QueueConfigSchema = z.object({
+    /**
+     * Per-provider concurrency. The reserved key `default` applies to every
+     * provider without an explicit entry; free routes fall back to 1.
+     */
+    perProviderConcurrency: z.dict(z.number().step(1).min(0)).default({}),
+    maxQueueDepth: z.number().step(1).min(1).default(50),
+    maxWaitMs: z.number().min(0).default(DEFAULT_MAX_WAIT_MS),
+    honorRetryAfter: z.boolean().default(true),
+    backoff: BackoffConfigSchema,
+});
+/** Visibility presets owned by the composition, not by the user layer. */
+export const VisibilityConfigSchema = z.object({
+    /** Read-only glob patterns; only \`*\` is a metacharacter. */
+    hiddenPatterns: z.array(z.string()).default([]),
+});
+/** Whole-plugin configuration. */
+export const Config = z.object({
+    queue: QueueConfigSchema,
+    visibility: VisibilityConfigSchema,
+    /**
+     * Standalone recovery budget. `auto` engages only when the
+     * `agent/request-error` waterfall reaches no downstream retry decision;
+     * `off` never retries; a number caps retries per step.
+     */
+    reactiveRetry: z.union(['auto', 'off', z.number().step(1).min(0)]).default('auto'),
+});
+/** Normalize raw plugin config, applying every documented default. */
+export function resolveConfig(input) {
+    const queue = input?.queue ?? {};
+    const backoffInput = queue.backoff ?? {};
+    const reactiveRetryMode = input?.reactiveRetry ?? 'auto';
+    return {
+        queue: {
+            perProviderConcurrency: { ...(queue.perProviderConcurrency ?? {}) },
+            maxQueueDepth: queue.maxQueueDepth ?? 50,
+            maxWaitMs: queue.maxWaitMs ?? DEFAULT_MAX_WAIT_MS,
+            honorRetryAfter: queue.honorRetryAfter ?? true,
+            backoff: {
+                initialDelayMs: backoffInput.initialDelayMs ?? 500,
+                maxDelayMs: backoffInput.maxDelayMs ?? 10_000,
+                jitterRatio: backoffInput.jitterRatio ?? 0.1,
+            },
+        },
+        reactiveRetryMode,
+        hiddenPatterns: [...(input?.visibility?.hiddenPatterns ?? [])],
+        reactiveRetryLimit: reactiveRetryMode === 'off' ? 0 : reactiveRetryMode === 'auto' ? DEFAULT_REACTIVE_RETRIES : reactiveRetryMode,
+    };
+}

package/lib/controller.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Host half of the browser control surface: a Typert Remote namespace that
+ * reports queue state and cancels a queued request.
+ *
+ * The `@Remote` marker is applied programmatically rather than with decorator
+ * syntax: the marker is a prototype descriptor, and avoiding decorators keeps
+ * the source runnable by Node's type-stripping test runner without a build step.
+ *
+ * @module dsh-llm-ctl/controller
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import type { CtlEvent } from './events.ts';
+import type { GateSnapshot } from './queue.ts';
+/** Everything the browser may read about the control plane. */
+export interface LlmCtlSnapshot {
+    at: number;
+    queue: GateSnapshot;
+    events: CtlEvent[];
+    reactive: {
+        mode: 'auto' | 'off' | number;
+        limit: number;
+    };
+}
+/** Dependencies supplied by the host plugin. */
+export interface ControllerDeps {
+    snapshot: () => LlmCtlSnapshot;
+    cancel: (queueId: string) => boolean;
+}
+/** `ctx.remote.llmCtl` — the namespace the web client polls. */
+export declare class LlmCtlController extends TypertRemoteService {
+    private readonly deps;
+    constructor(ctx: Context, deps: ControllerDeps);
+    /** Current queue, cooldown, and recent control-plane facts. */
+    snapshot(): LlmCtlSnapshot;
+    /** Cancel one still-queued request; false when it already started or vanished. */
+    cancel(request: {
+        queueId: string;
+    }): {
+        cancelled: boolean;
+    };
+}

package/lib/controller.js

@@ -0,0 +1,51 @@
+import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+/**
+ * Mark one public instance method as a Remote export.
+ *
+ * @param instance - service instance whose prototype receives the marker.
+ * @param name - public method name exported under the namespace.
+ */
+function markRemote(instance, name) {
+    const method = instance[name];
+    if (typeof method !== 'function')
+        throw new TypeError(`llm-ctl: remote method "${name}" is missing`);
+    const context = {
+        kind: 'method',
+        name,
+        static: false,
+        private: false,
+        access: {
+            has: (target) => name in target,
+            get: (target) => target[name],
+        },
+        metadata: {},
+        addInitializer(initializer) {
+            initializer.call(instance);
+        },
+    };
+    Remote(method, context);
+}
+/** `ctx.remote.llmCtl` — the namespace the web client polls. */
+export class LlmCtlController extends TypertRemoteService {
+    deps;
+    constructor(ctx, deps) {
+        super(ctx, 'llmCtlController', { namespace: 'llmCtl' });
+        this.deps = deps;
+        markRemote(this, 'snapshot');
+        markRemote(this, 'cancel');
+    }
+    /** Current queue, cooldown, and recent control-plane facts. */
+    snapshot() {
+        return this.deps.snapshot();
+    }
+    /** Cancel one still-queued request; false when it already started or vanished. */
+    cancel(request) {
+        if (request === null ||
+            typeof request !== 'object' ||
+            typeof request.queueId !== 'string' ||
+            request.queueId.length === 0) {
+            return { cancelled: false };
+        }
+        return { cancelled: this.deps.cancel(request.queueId) };
+    }
+}

package/lib/delay.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Delay resolution ladder for rate-limit recovery.
+ *
+ * Every source normalizes to milliseconds. Levels 2-6 need an adapter to expose
+ * raw response headers through `LlmError.details`; the parsers ship now so M2 is
+ * only wiring, while M1 uses level 1 (the adapter's parsed hint) and level 7
+ * (local bounded backoff).
+ *
+ * @module dsh-llm-ctl/delay
+ */
+/** Local bounded exponential backoff with symmetric jitter. */
+export interface BackoffConfig {
+    initialDelayMs: number;
+    maxDelayMs: number;
+    jitterRatio: number;
+}
+/** Where the resolved delay came from, for observability and tests. */
+export type DelaySource = 'provider-retry-after-ms' | 'retry-after-ms' | 'retry-after' | 'ratelimit-reset' | 'go-duration' | 'rfc3339-reset' | 'backoff';
+/** One resolved wait, already normalized to milliseconds. */
+export interface DelayResolution {
+    delayMs: number;
+    source: DelaySource;
+    /** True when the provider asked for longer than the single wait budget. */
+    overBudget: boolean;
+}
+/** Inputs to one delay resolution. */
+export interface DelayLadderInput {
+    /** Delay the adapter already parsed out of the provider response. */
+    providerRetryAfterMs?: number | undefined;
+    /**
+     * Raw provider response headers. M1 adapters do not expose these; the ladder
+     * accepts them so M2 only has to pass them through.
+     */
+    headers?: Record<string, string | undefined> | undefined;
+    /** 1-based attempt number used by the local backoff. */
+    attempt: number;
+    backoff: BackoffConfig;
+    /** Single wait budget shared by queueing and cooldown. */
+    maxWaitMs: number;
+    honorRetryAfter: boolean;
+    random: () => number;
+    /** Clock used by absolute-time headers; defaults to Date.now. */
+    now?: () => number;
+}
+/** Seconds or HTTP-date, per RFC 9110. Returns undefined for unusable values. */
+export declare function parseRetryAfterHeader(value: string | undefined, now?: number): number | undefined;
+/** `retry-after-ms` carries milliseconds directly. */
+export declare function parseRetryAfterMsHeader(value: string | undefined): number | undefined;
+/**
+ * A numeric reset header: small values are seconds, large ones are an epoch in
+ * seconds (OpenRouter). The 3600s boundary keeps ordinary second values exact.
+ */
+export declare function parseNumericResetHeader(value: string | undefined, now?: number): number | undefined;
+/** Go duration strings used by OpenAI and Groq reset headers, e.g. `6m0s`. */
+export declare function parseGoDurationMs(value: string | undefined): number | undefined;
+/** RFC 3339 absolute reset instant (Anthropic), converted against the local clock. */
+export declare function parseRfc3339ResetHeader(value: string | undefined, now?: number): number | undefined;
+/** Local bounded exponential backoff with symmetric jitter. */
+export declare function backoffDelay(attempt: number, config: BackoffConfig, random: () => number): number;
+/**
+ * Resolve the wait for one failed request.
+ *
+ * Priority: adapter-parsed provider hint, then raw headers (ms, Retry-After,
+ * numeric reset, Go duration, RFC 3339 reset), then local backoff. A resolved
+ * delay above `maxWaitMs` is reported as over budget so the caller can fail
+ * fast instead of waiting out a budget it can never satisfy.
+ */
+export declare function resolveDelay(input: DelayLadderInput): DelayResolution;

package/lib/delay.js

@@ -0,0 +1,134 @@
+/**
+ * Delay resolution ladder for rate-limit recovery.
+ *
+ * Every source normalizes to milliseconds. Levels 2-6 need an adapter to expose
+ * raw response headers through `LlmError.details`; the parsers ship now so M2 is
+ * only wiring, while M1 uses level 1 (the adapter's parsed hint) and level 7
+ * (local bounded backoff).
+ *
+ * @module dsh-llm-ctl/delay
+ */
+/** Seconds or HTTP-date, per RFC 9110. Returns undefined for unusable values. */
+export function parseRetryAfterHeader(value, now = Date.now()) {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    if (/^\d+$/.test(trimmed)) {
+        const seconds = Number(trimmed);
+        return Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : undefined;
+    }
+    const at = Date.parse(trimmed);
+    if (!Number.isFinite(at))
+        return undefined;
+    const delta = at - now;
+    return delta > 0 ? delta : undefined;
+}
+/** `retry-after-ms` carries milliseconds directly. */
+export function parseRetryAfterMsHeader(value) {
+    if (value === undefined)
+        return undefined;
+    const ms = Number(value.trim());
+    return Number.isFinite(ms) && ms > 0 ? ms : undefined;
+}
+/**
+ * A numeric reset header: small values are seconds, large ones are an epoch in
+ * seconds (OpenRouter). The 3600s boundary keeps ordinary second values exact.
+ */
+export function parseNumericResetHeader(value, now = Date.now()) {
+    if (value === undefined)
+        return undefined;
+    const raw = Number(value.trim());
+    if (!Number.isFinite(raw) || raw <= 0)
+        return undefined;
+    if (raw > 3600) {
+        const delta = raw * 1000 - now;
+        return delta > 0 ? delta : undefined;
+    }
+    return raw * 1000;
+}
+/** Go duration strings used by OpenAI and Groq reset headers, e.g. `6m0s`. */
+export function parseGoDurationMs(value) {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    const units = { ns: 1e-6, us: 1e-3, 'µs': 1e-3, ms: 1, s: 1000, m: 60_000, h: 3_600_000 };
+    const pattern = /(\d+(?:\.\d+)?)(ns|us|µs|ms|s|m|h)/g;
+    let total = 0;
+    let matched = 0;
+    let consumed = 0;
+    for (const match of trimmed.matchAll(pattern)) {
+        const amount = Number(match[1]);
+        const unit = units[match[2] ?? ''];
+        if (!Number.isFinite(amount) || unit === undefined)
+            return undefined;
+        total += amount * unit;
+        matched += 1;
+        consumed += match[0].length;
+    }
+    if (matched === 0 || consumed !== trimmed.length)
+        return undefined;
+    return total > 0 ? total : undefined;
+}
+/** RFC 3339 absolute reset instant (Anthropic), converted against the local clock. */
+export function parseRfc3339ResetHeader(value, now = Date.now()) {
+    if (value === undefined)
+        return undefined;
+    const at = Date.parse(value.trim());
+    if (!Number.isFinite(at))
+        return undefined;
+    const delta = at - now;
+    return delta > 0 ? delta : undefined;
+}
+/** Local bounded exponential backoff with symmetric jitter. */
+export function backoffDelay(attempt, config, random) {
+    const exponent = Math.min(Math.max(attempt - 1, 0), 16);
+    const exponential = Math.min(config.initialDelayMs * 2 ** exponent, config.maxDelayMs);
+    const jitter = 1 - config.jitterRatio + 2 * config.jitterRatio * random();
+    return Math.max(0, Math.min(exponential * jitter, config.maxDelayMs));
+}
+/**
+ * Resolve the wait for one failed request.
+ *
+ * Priority: adapter-parsed provider hint, then raw headers (ms, Retry-After,
+ * numeric reset, Go duration, RFC 3339 reset), then local backoff. A resolved
+ * delay above `maxWaitMs` is reported as over budget so the caller can fail
+ * fast instead of waiting out a budget it can never satisfy.
+ */
+export function resolveDelay(input) {
+    const nowMs = (input.now ?? Date.now)();
+    const finish = (delayMs, source) => ({
+        delayMs,
+        source,
+        overBudget: delayMs > input.maxWaitMs,
+    });
+    if (input.honorRetryAfter) {
+        const hint = input.providerRetryAfterMs;
+        if (hint !== undefined && Number.isFinite(hint) && hint > 0)
+            return finish(hint, 'provider-retry-after-ms');
+        const headers = input.headers;
+        if (headers !== undefined) {
+            const read = (name) => headers[name] ?? headers[name.toLowerCase()];
+            const afterMs = parseRetryAfterMsHeader(read('retry-after-ms'));
+            if (afterMs !== undefined)
+                return finish(afterMs, 'retry-after-ms');
+            const after = parseRetryAfterHeader(read('retry-after'), nowMs);
+            if (after !== undefined)
+                return finish(after, 'retry-after');
+            const numericReset = parseNumericResetHeader(read('x-ratelimit-reset'), nowMs);
+            if (numericReset !== undefined)
+                return finish(numericReset, 'ratelimit-reset');
+            const goDuration = parseGoDurationMs(read('x-ratelimit-reset-requests') ?? read('x-ratelimit-reset-tokens'));
+            if (goDuration !== undefined)
+                return finish(goDuration, 'go-duration');
+            const rfcReset = parseRfc3339ResetHeader(read('anthropic-ratelimit-requests-reset'), nowMs) ??
+                parseRfc3339ResetHeader(read('anthropic-ratelimit-tokens-reset'), nowMs);
+            if (rfcReset !== undefined)
+                return finish(rfcReset, 'rfc3339-reset');
+        }
+    }
+    return finish(backoffDelay(input.attempt, input.backoff, input.random), 'backoff');
+}