@graphrefly/graphrefly 0.45.0 → 0.47.0

package/dist/breaker-ugSdq54q.d.cts

@@ -0,0 +1,175 @@
+import { Node } from '@graphrefly/pure-ts/core';
+import { N as NodeOrValue } from './_internal-B23BagFd.cjs';
+import { B as BackoffStrategy } from './backoff-Bnb9OoPh.cjs';
+
+/**
+ * Central gate-state vocabulary for resilience primitives.
+ *
+ * **DS-13.5.B follow-on (locked 2026-05-01).** Two-state base enum
+ * (`"open" | "closed"`) used as the literal vocabulary inside
+ * gate-shaped `<Primitive>State` companions on `budgetGate`. Other
+ * primitives extend this base with primitive-specific values:
+ *
+ * - `rateLimiter` → `GateState | "throttled"`.
+ * - `circuitBreaker` → `GateState | "half-open"`.
+ *
+ * Keeping the base as a separate exported type lets callers narrow
+ * generic gate-state consumers without coupling to any one primitive's
+ * extension axis.
+ *
+ * @category extra/resilience
+ */
+type GateState = "open" | "closed";
+
+/**
+ * Circuit breaker — open/half-open/closed state machine + companion bundle.
+ *
+ * - {@link circuitBreaker} returns a synchronous breaker handle (counters,
+ *   state machine, optional reactive-options subscription).
+ * - {@link withBreaker} wraps a `Node<T>` and surfaces a reactive
+ *   `Node<CircuitState>` companion (`bundle.breakerState`) for telemetry.
+ */
+
+type CircuitState = "closed" | "open" | "half-open";
+/**
+ * Lifecycle-shaped state companion emitted by {@link withBreaker}
+ * (DS-13.5.B, locked 2026-05-01). Pre-1.0 break vs the prior
+ * `Node<CircuitState>` (string-only) shape.
+ *
+ * `status` extends {@link GateState} with `"half-open"`. The numeric
+ * fields surface the breaker's full internal state for telemetry and
+ * `describe()` traversal.
+ *
+ * @category extra/resilience
+ */
+interface BreakerState {
+    readonly status: GateState | "half-open";
+    readonly failureCount: number;
+    readonly openCycle: number;
+    readonly lastOpenedAtNs: number;
+    readonly halfOpenAttempts: number;
+    readonly lastCooldownNs: number;
+}
+/**
+ * Thrown when {@link withBreaker} is configured with `onOpen: "error"` and the breaker rejects work.
+ *
+ * @category extra
+ */
+declare class CircuitOpenError extends Error {
+    name: string;
+    constructor();
+}
+interface CircuitBreakerOptions {
+    /** Number of consecutive failures before opening. Default: 5. */
+    failureThreshold?: number;
+    /** Base cooldown in nanoseconds before transitioning to half-open. Default: 30s. */
+    cooldownNs?: number;
+    /** Backoff strategy for cooldown escalation across consecutive open cycles. Overrides `cooldownNs` when provided. */
+    cooldown?: BackoffStrategy;
+    /** Max trial requests allowed in half-open state. Default: 1. */
+    halfOpenMax?: number;
+    /**
+     * Clock function returning **nanoseconds** with `monotonicNs()` semantics
+     * (monotonically non-decreasing; suitable for elapsed-time arithmetic — never
+     * use `Date.now()` because wall-clock skew can flip elapsed math negative).
+     * Default: `monotonicNs` from `core/clock`. Override for deterministic tests.
+     */
+    now?: () => number;
+}
+interface CircuitBreaker {
+    /** Whether a request should be allowed through. Triggers open→half-open transition when cooldown expires. */
+    canExecute(): boolean;
+    /** Record a successful execution. Resets to closed. */
+    recordSuccess(): void;
+    /** Record a failed execution. May transition to open. */
+    recordFailure(error?: unknown): void;
+    /**
+     * Current circuit state (read-only, does not trigger transitions).
+     *
+     * **Telemetry:** wrap with {@link withBreaker} to surface this as a reactive
+     * `Node<CircuitState>` companion (`bundle.breakerState`) — every state
+     * transition (`closed`/`open`/`half-open`) emits to subscribers.
+     */
+    readonly state: CircuitState;
+    /** Number of consecutive failures in the current closed period. */
+    readonly failureCount: number;
+    /** Manually reset to closed state, clearing all counters. */
+    reset(): void;
+    /**
+     * Release the reactive-options subscription (Tier 6.5 3.2.4, 2026-04-29).
+     * No-op when constructed with static options. Call when retiring a
+     * breaker whose options came from a `Node<CircuitBreakerOptions>` to
+     * avoid leaking the option-Node subscription.
+     */
+    dispose(): void;
+}
+/**
+ * Factory for a synchronous circuit breaker with `closed`, `open`, and `half-open` states.
+ *
+ * Supports escalating cooldown via an optional {@link BackoffStrategy} — each consecutive
+ * open→half-open→open cycle increments the backoff attempt.
+ *
+ * @param options - Threshold, cooldown, half-open limit, and optional clock
+ *   override; OR a `Node<CircuitBreakerOptions>` carrying the same shape
+ *   reactively (Tier 6.5 3.2.4).
+ * @returns {@link CircuitBreaker} instance.
+ *
+ * @remarks
+ * **Timing:** Uses `monotonicNs()` by default (nanoseconds). Override `now` for tests.
+ *
+ * **Reactive options (locked semantics, Tier 6.5 3.2.4, 2026-04-29).**
+ * When `options` is a `Node<CircuitBreakerOptions>`, the breaker
+ * subscribes at construction and re-reads `failureThreshold` /
+ * `cooldownNs` / `cooldown` / `halfOpenMax` / `now` on each DATA. **An
+ * option swap RESETS the breaker to `"closed"`** with all counters
+ * cleared — operators tuning a runaway breaker get a clean baseline.
+ * If retaining failure history across re-tunings matters, derive a new
+ * breaker per-tuning instead. Call `breaker.dispose()` when retiring to
+ * release the option-Node subscription.
+ *
+ * @example
+ * ```ts
+ * import { circuitBreaker, exponential, NS_PER_SEC } from "@graphrefly/graphrefly-ts";
+ *
+ * const b = circuitBreaker({
+ *   failureThreshold: 3,
+ *   cooldown: exponential({ baseNs: 1 * NS_PER_SEC }),
+ * });
+ * ```
+ *
+ * @category extra
+ */
+declare function circuitBreaker(options?: NodeOrValue<CircuitBreakerOptions>): CircuitBreaker;
+type WithBreakerBundle<T> = {
+    node: Node<T>;
+    breakerState: Node<BreakerState>;
+};
+/**
+ * Returns a unary wrapper that gates upstream `DATA` through a {@link CircuitBreaker}.
+ *
+ * @param breaker - Shared breaker instance (typically one per resource).
+ * @param options - `onOpen: "skip"` emits `RESOLVED` when open; `"error"` emits {@link CircuitOpenError}.
+ * @returns Function mapping `Node<T>` to `{ node, breakerState }` companion nodes.
+ *
+ * @remarks
+ * **Success path:** `COMPLETE` calls {@link CircuitBreaker.recordSuccess}. **Failure path:** upstream `ERROR` calls {@link CircuitBreaker.recordFailure} and is forwarded.
+ *
+ * **State telemetry:** `breakerState: Node<CircuitState>` is a reactive companion that mirrors `breaker.state` — every transition (`closed`/`open`/`half-open`) emits a `DATA`. Also accessible via `node.meta.breakerState` for `describe()` traversal.
+ *
+ * @example
+ * ```ts
+ * import { state, withBreaker, circuitBreaker } from "@graphrefly/graphrefly-ts";
+ *
+ * const b = circuitBreaker({ failureThreshold: 2 });
+ * const s = state(1);
+ * const { node, breakerState } = withBreaker(b)(s);
+ * ```
+ *
+ * @category extra
+ */
+declare function withBreaker<T>(breaker: CircuitBreaker, options?: {
+    onOpen?: "skip" | "error";
+    meta?: Record<string, unknown>;
+}): (source: Node<T>) => WithBreakerBundle<T>;
+
+export { type BreakerState as B, type CircuitBreaker as C, type GateState as G, type WithBreakerBundle as W, type CircuitBreakerOptions as a, CircuitOpenError as b, type CircuitState as c, circuitBreaker as d, withBreaker as w };

package/dist/cascading-CSSbKGrJ.d.ts

@@ -0,0 +1,199 @@
+import { L as LLMAdapter, a as ChatMessage, b as LLMInvokeOptions } from './types-BB5Lw-pB.js';
+import { a as CircuitBreakerOptions, C as CircuitBreaker } from './breaker-C9skL3d8.js';
+
+/**
+ * OpenAICompatAdapter — default fetch-backed, optional SDK-backed.
+ *
+ * Covers any provider that speaks OpenAI chat/completions. Preset base URLs
+ * for OpenAI, OpenRouter, Groq, Ollama, DeepSeek, xAI Grok (all expose the
+ * same `/v1/chat/completions` shape).
+ *
+ * Token usage mapping:
+ * - `prompt_tokens`                                     → `input.regular` (minus cached_tokens)
+ * - `prompt_tokens_details.cached_tokens`               → `input.cacheRead`
+ * - `prompt_tokens_details.audio_tokens`                → `input.audio`
+ * - `completion_tokens`                                 → `output.regular` (minus reasoning)
+ * - `completion_tokens_details.reasoning_tokens`        → `output.reasoning`
+ * - `completion_tokens_details.audio_tokens`            → `output.audio`
+ * - `completion_tokens_details.accepted_prediction_tokens` → `output.predictionAccepted`
+ * - `completion_tokens_details.rejected_prediction_tokens` → `output.predictionRejected`
+ *
+ * DeepSeek compatibility: `prompt_cache_hit_tokens` / `prompt_cache_miss_tokens`
+ * are surfaced in the `raw` field of `TokenUsage`; when present we prefer
+ * them over the OpenAI-style `cached_tokens` for cache-read attribution.
+ */
+
+type OpenAICompatPreset = "openai" | "openrouter" | "groq" | "ollama" | "deepseek" | "xai";
+interface OpenAICompatAdapterOptions {
+    preset?: OpenAICompatPreset;
+    /** Explicit provider label (defaults to preset's provider). */
+    provider?: string;
+    /** API key. Falls back to the preset's default env var on Node. */
+    apiKey?: string;
+    model?: string;
+    /** Override base URL (wins over `preset`). */
+    baseURL?: string;
+    /** Extra request headers. */
+    headers?: Record<string, string>;
+    /** Extra request-body fields merged on every request (OpenRouter routing etc.). */
+    bodyExtras?: Record<string, unknown>;
+    /** User-provided SDK instance (OpenAI-family shape). */
+    sdk?: OpenAISdkLike;
+    /** Custom fetch (for tests). */
+    fetchImpl?: typeof fetch;
+}
+interface OpenAISdkLike {
+    chat: {
+        completions: {
+            create(params: Record<string, unknown>, opts?: {
+                signal?: AbortSignal;
+            }): Promise<OpenAIChatResponse>;
+        };
+    };
+}
+interface OpenAIChatResponse {
+    id: string;
+    choices: ReadonlyArray<{
+        message: {
+            role: string;
+            content?: string | null;
+            tool_calls?: ReadonlyArray<{
+                id: string;
+                type: "function";
+                function: {
+                    name: string;
+                    arguments: string;
+                };
+            }>;
+            reasoning_content?: string;
+        };
+        finish_reason?: string;
+    }>;
+    usage?: OpenAIUsage;
+    model?: string;
+}
+interface OpenAIUsage {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    total_tokens?: number;
+    prompt_tokens_details?: {
+        cached_tokens?: number;
+        audio_tokens?: number;
+    };
+    completion_tokens_details?: {
+        reasoning_tokens?: number;
+        audio_tokens?: number;
+        accepted_prediction_tokens?: number;
+        rejected_prediction_tokens?: number;
+    };
+    prompt_cache_hit_tokens?: number;
+    prompt_cache_miss_tokens?: number;
+}
+declare function openAICompatAdapter(opts?: OpenAICompatAdapterOptions): LLMAdapter;
+
+/**
+ * `createAdapter` — provider-dispatching factory.
+ *
+ * One entry point, one config object. Picks the right concrete adapter by
+ * `provider`, forwards everything else. Users who want finer control import
+ * the concrete adapter directly (`anthropicAdapter`, `openAICompatAdapter`,
+ * `googleAdapter`, `dryRunAdapter`, `webllmAdapter`, `chromeNanoAdapter`).
+ */
+
+type AdapterProvider = "anthropic" | OpenAICompatPreset | "google" | "dry-run" | "fallback";
+interface CreateAdapterOptions {
+    provider: AdapterProvider;
+    apiKey?: string;
+    model?: string;
+    baseURL?: string;
+    headers?: Record<string, string>;
+    /** OpenAI-compat bodyExtras (OpenRouter routing, etc.). */
+    bodyExtras?: Record<string, unknown>;
+    /** Provider-specific SDK instance (any of AnthropicSdkLike / OpenAISdkLike / GoogleSdkLike). */
+    sdk?: unknown;
+    /** Custom fetch (for tests). */
+    fetchImpl?: typeof fetch;
+    /** Extra per-provider options forwarded verbatim. */
+    extras?: Record<string, unknown>;
+}
+declare function createAdapter(opts: CreateAdapterOptions): LLMAdapter;
+
+/**
+ * `cascadingLlmAdapter` — N-tier fallback over any mix of LLM adapters.
+ *
+ * Same structural pattern as `cascadingCache` and `Graph.attachSnapshotStorage`:
+ * ordered list, first-success wins, per-tier breaker optional, filter gates
+ * per request. Semantics:
+ *
+ * - `invoke()`: try tier 0 first. On error (or breaker-open), fall through
+ *   to tier 1, 2, ... until one succeeds or all fail.
+ * - `stream()`: tries to start the stream on tier 0; once tokens begin, it
+ *   commits — failures in mid-stream surface rather than re-starting on the
+ *   next tier (would double-bill and confuse consumers). **State-machine
+ *   consumers (usage accounting, UI accumulators) must handle errors in a
+ *   catch block — no synthetic `{type: "finish"}` is emitted after a thrown
+ *   stream error.**
+ * - `filter`: skips a tier for requests that use features it doesn't
+ *   support (e.g., Chrome Nano can't do tool use).
+ * - `breaker`: per-tier circuit; when open, cascade treats the tier as
+ *   unavailable and moves on immediately.
+ *
+ * On exhaustion, throws `AllTiersExhaustedError` with separate `skipped` and
+ * `failed` collections so consumers can distinguish "no tier applicable"
+ * from "all tiers failed".
+ */
+
+interface AdapterTier {
+    name: string;
+    adapter: LLMAdapter;
+    /** Per-tier circuit breaker. If omitted, no breaker on this tier. */
+    breaker?: CircuitBreakerOptions | CircuitBreaker;
+    /** Skip this tier when the request doesn't fit (e.g. Chrome Nano + tools). */
+    filter?: (messages: readonly ChatMessage[], opts?: LLMInvokeOptions) => boolean;
+}
+interface CascadeExhaustionReport {
+    /** Tiers that never ran (filter returned false, or breaker was open). */
+    readonly skipped: ReadonlyArray<{
+        name: string;
+        reason: "filter" | "breaker";
+    }>;
+    /** Tiers that ran and threw. */
+    readonly failed: ReadonlyMap<string, unknown>;
+}
+interface CascadingLlmAdapterOptions {
+    onFallback?: (from: string, to: string, error: unknown) => void;
+    onExhausted?: (report: CascadeExhaustionReport) => void;
+    /** Whether to attempt stream retry on subsequent tiers before first chunk. Default true. */
+    streamRetryBeforeFirstChunk?: boolean;
+}
+declare class AllTiersExhaustedError extends Error {
+    name: string;
+    readonly skipped: ReadonlyArray<{
+        name: string;
+        reason: "filter" | "breaker";
+    }>;
+    readonly failed: ReadonlyMap<string, unknown>;
+    constructor(report: CascadeExhaustionReport);
+}
+declare function cascadingLlmAdapter(tiers: readonly AdapterTier[], opts?: CascadingLlmAdapterOptions): LLMAdapter;
+/**
+ * Tiny type-safe constructor for an {@link AdapterTier}. Cleans up the
+ * heterogeneous array-type cast users (and `browser-presets.ts`) had to write
+ * by hand. Per Wave A Unit 13 decision.
+ *
+ * @example
+ * ```ts
+ * cascadingLlmAdapter([
+ *   tier("local", webllmAdapter(...)),
+ *   tier("cloud", anthropicAdapter(...), { breaker: { failureThreshold: 5 } }),
+ * ]);
+ * ```
+ *
+ * @category ai
+ */
+declare function tier(name: string, adapter: LLMAdapter, opts?: {
+    breaker?: CircuitBreakerOptions | CircuitBreaker;
+    filter?: AdapterTier["filter"];
+}): AdapterTier;
+
+export { type AdapterProvider as A, type CascadeExhaustionReport as C, type OpenAICompatAdapterOptions as O, type AdapterTier as a, AllTiersExhaustedError as b, type CascadingLlmAdapterOptions as c, type CreateAdapterOptions as d, type OpenAICompatPreset as e, type OpenAISdkLike as f, cascadingLlmAdapter as g, createAdapter as h, openAICompatAdapter as o, tier as t };

package/dist/cascading-baGkiihI.d.cts

@@ -0,0 +1,199 @@
+import { L as LLMAdapter, a as ChatMessage, b as LLMInvokeOptions } from './types-BB5Lw-pB.cjs';
+import { a as CircuitBreakerOptions, C as CircuitBreaker } from './breaker-ugSdq54q.cjs';
+
+/**
+ * OpenAICompatAdapter — default fetch-backed, optional SDK-backed.
+ *
+ * Covers any provider that speaks OpenAI chat/completions. Preset base URLs
+ * for OpenAI, OpenRouter, Groq, Ollama, DeepSeek, xAI Grok (all expose the
+ * same `/v1/chat/completions` shape).
+ *
+ * Token usage mapping:
+ * - `prompt_tokens`                                     → `input.regular` (minus cached_tokens)
+ * - `prompt_tokens_details.cached_tokens`               → `input.cacheRead`
+ * - `prompt_tokens_details.audio_tokens`                → `input.audio`
+ * - `completion_tokens`                                 → `output.regular` (minus reasoning)
+ * - `completion_tokens_details.reasoning_tokens`        → `output.reasoning`
+ * - `completion_tokens_details.audio_tokens`            → `output.audio`
+ * - `completion_tokens_details.accepted_prediction_tokens` → `output.predictionAccepted`
+ * - `completion_tokens_details.rejected_prediction_tokens` → `output.predictionRejected`
+ *
+ * DeepSeek compatibility: `prompt_cache_hit_tokens` / `prompt_cache_miss_tokens`
+ * are surfaced in the `raw` field of `TokenUsage`; when present we prefer
+ * them over the OpenAI-style `cached_tokens` for cache-read attribution.
+ */
+
+type OpenAICompatPreset = "openai" | "openrouter" | "groq" | "ollama" | "deepseek" | "xai";
+interface OpenAICompatAdapterOptions {
+    preset?: OpenAICompatPreset;
+    /** Explicit provider label (defaults to preset's provider). */
+    provider?: string;
+    /** API key. Falls back to the preset's default env var on Node. */
+    apiKey?: string;
+    model?: string;
+    /** Override base URL (wins over `preset`). */
+    baseURL?: string;
+    /** Extra request headers. */
+    headers?: Record<string, string>;
+    /** Extra request-body fields merged on every request (OpenRouter routing etc.). */
+    bodyExtras?: Record<string, unknown>;
+    /** User-provided SDK instance (OpenAI-family shape). */
+    sdk?: OpenAISdkLike;
+    /** Custom fetch (for tests). */
+    fetchImpl?: typeof fetch;
+}
+interface OpenAISdkLike {
+    chat: {
+        completions: {
+            create(params: Record<string, unknown>, opts?: {
+                signal?: AbortSignal;
+            }): Promise<OpenAIChatResponse>;
+        };
+    };
+}
+interface OpenAIChatResponse {
+    id: string;
+    choices: ReadonlyArray<{
+        message: {
+            role: string;
+            content?: string | null;
+            tool_calls?: ReadonlyArray<{
+                id: string;
+                type: "function";
+                function: {
+                    name: string;
+                    arguments: string;
+                };
+            }>;
+            reasoning_content?: string;
+        };
+        finish_reason?: string;
+    }>;
+    usage?: OpenAIUsage;
+    model?: string;
+}
+interface OpenAIUsage {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    total_tokens?: number;
+    prompt_tokens_details?: {
+        cached_tokens?: number;
+        audio_tokens?: number;
+    };
+    completion_tokens_details?: {
+        reasoning_tokens?: number;
+        audio_tokens?: number;
+        accepted_prediction_tokens?: number;
+        rejected_prediction_tokens?: number;
+    };
+    prompt_cache_hit_tokens?: number;
+    prompt_cache_miss_tokens?: number;
+}
+declare function openAICompatAdapter(opts?: OpenAICompatAdapterOptions): LLMAdapter;
+
+/**
+ * `createAdapter` — provider-dispatching factory.
+ *
+ * One entry point, one config object. Picks the right concrete adapter by
+ * `provider`, forwards everything else. Users who want finer control import
+ * the concrete adapter directly (`anthropicAdapter`, `openAICompatAdapter`,
+ * `googleAdapter`, `dryRunAdapter`, `webllmAdapter`, `chromeNanoAdapter`).
+ */
+
+type AdapterProvider = "anthropic" | OpenAICompatPreset | "google" | "dry-run" | "fallback";
+interface CreateAdapterOptions {
+    provider: AdapterProvider;
+    apiKey?: string;
+    model?: string;
+    baseURL?: string;
+    headers?: Record<string, string>;
+    /** OpenAI-compat bodyExtras (OpenRouter routing, etc.). */
+    bodyExtras?: Record<string, unknown>;
+    /** Provider-specific SDK instance (any of AnthropicSdkLike / OpenAISdkLike / GoogleSdkLike). */
+    sdk?: unknown;
+    /** Custom fetch (for tests). */
+    fetchImpl?: typeof fetch;
+    /** Extra per-provider options forwarded verbatim. */
+    extras?: Record<string, unknown>;
+}
+declare function createAdapter(opts: CreateAdapterOptions): LLMAdapter;
+
+/**
+ * `cascadingLlmAdapter` — N-tier fallback over any mix of LLM adapters.
+ *
+ * Same structural pattern as `cascadingCache` and `Graph.attachSnapshotStorage`:
+ * ordered list, first-success wins, per-tier breaker optional, filter gates
+ * per request. Semantics:
+ *
+ * - `invoke()`: try tier 0 first. On error (or breaker-open), fall through
+ *   to tier 1, 2, ... until one succeeds or all fail.
+ * - `stream()`: tries to start the stream on tier 0; once tokens begin, it
+ *   commits — failures in mid-stream surface rather than re-starting on the
+ *   next tier (would double-bill and confuse consumers). **State-machine
+ *   consumers (usage accounting, UI accumulators) must handle errors in a
+ *   catch block — no synthetic `{type: "finish"}` is emitted after a thrown
+ *   stream error.**
+ * - `filter`: skips a tier for requests that use features it doesn't
+ *   support (e.g., Chrome Nano can't do tool use).
+ * - `breaker`: per-tier circuit; when open, cascade treats the tier as
+ *   unavailable and moves on immediately.
+ *
+ * On exhaustion, throws `AllTiersExhaustedError` with separate `skipped` and
+ * `failed` collections so consumers can distinguish "no tier applicable"
+ * from "all tiers failed".
+ */
+
+interface AdapterTier {
+    name: string;
+    adapter: LLMAdapter;
+    /** Per-tier circuit breaker. If omitted, no breaker on this tier. */
+    breaker?: CircuitBreakerOptions | CircuitBreaker;
+    /** Skip this tier when the request doesn't fit (e.g. Chrome Nano + tools). */
+    filter?: (messages: readonly ChatMessage[], opts?: LLMInvokeOptions) => boolean;
+}
+interface CascadeExhaustionReport {
+    /** Tiers that never ran (filter returned false, or breaker was open). */
+    readonly skipped: ReadonlyArray<{
+        name: string;
+        reason: "filter" | "breaker";
+    }>;
+    /** Tiers that ran and threw. */
+    readonly failed: ReadonlyMap<string, unknown>;
+}
+interface CascadingLlmAdapterOptions {
+    onFallback?: (from: string, to: string, error: unknown) => void;
+    onExhausted?: (report: CascadeExhaustionReport) => void;
+    /** Whether to attempt stream retry on subsequent tiers before first chunk. Default true. */
+    streamRetryBeforeFirstChunk?: boolean;
+}
+declare class AllTiersExhaustedError extends Error {
+    name: string;
+    readonly skipped: ReadonlyArray<{
+        name: string;
+        reason: "filter" | "breaker";
+    }>;
+    readonly failed: ReadonlyMap<string, unknown>;
+    constructor(report: CascadeExhaustionReport);
+}
+declare function cascadingLlmAdapter(tiers: readonly AdapterTier[], opts?: CascadingLlmAdapterOptions): LLMAdapter;
+/**
+ * Tiny type-safe constructor for an {@link AdapterTier}. Cleans up the
+ * heterogeneous array-type cast users (and `browser-presets.ts`) had to write
+ * by hand. Per Wave A Unit 13 decision.
+ *
+ * @example
+ * ```ts
+ * cascadingLlmAdapter([
+ *   tier("local", webllmAdapter(...)),
+ *   tier("cloud", anthropicAdapter(...), { breaker: { failureThreshold: 5 } }),
+ * ]);
+ * ```
+ *
+ * @category ai
+ */
+declare function tier(name: string, adapter: LLMAdapter, opts?: {
+    breaker?: CircuitBreakerOptions | CircuitBreaker;
+    filter?: AdapterTier["filter"];
+}): AdapterTier;
+
+export { type AdapterProvider as A, type CascadeExhaustionReport as C, type OpenAICompatAdapterOptions as O, type AdapterTier as a, AllTiersExhaustedError as b, type CascadingLlmAdapterOptions as c, type CreateAdapterOptions as d, type OpenAICompatPreset as e, type OpenAISdkLike as f, cascadingLlmAdapter as g, createAdapter as h, openAICompatAdapter as o, tier as t };