@prometheus-ai/ai 0.5.4 → 0.5.8

package/dist/types/auth-broker/remote-store.d.ts

@@ -1,7 +1,7 @@
 import { type AuthCredential, type AuthCredentialStore, type OAuthCredential, type StoredAuthCredential } from "../auth-storage";
+import type { OAuthCredentials } from "../registry/oauth/types";
 import type { Provider } from "../types";
 import type { UsageReport } from "../usage";
-import type { OAuthCredentials } from "../utils/oauth/types";
 import { type AuthBrokerClient } from "./client";
 import type { SnapshotResponse } from "./types";
 export interface RemoteAuthCredentialStoreOptions {
@@ -37,6 +37,7 @@ export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
      */
     updateAuthCredential(id: number, credential: AuthCredential): void;
     deleteAuthCredential(id: number, disabledCause: string): void;
+    deleteAuthCredentialRemote(id: number, disabledCause: string): Promise<boolean>;
     tryDisableAuthCredentialIfMatches(id: number, _expectedData: string, disabledCause: string): boolean;
     waitForFreshSnapshot(maxWaitMs: number, opts?: {
         signal?: AbortSignal;

package/dist/types/auth-broker/wire-schemas.d.ts

@@ -10,7 +10,7 @@
  * keys are rejected — the previous implementation used a hand-rolled
  * `hasOnlyFields` allowlist for the same effect.
  */
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 /** Real OAuth credential (broker-side) — refresh token is the actual upstream value. */
 export declare const oauthCredentialSchema: z.ZodObject<{
     type: z.ZodLiteral<"oauth">;
@@ -344,6 +344,9 @@ export declare const usageResponseSchema: z.ZodObject<{
             }>>;
             notes: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>;
+        resetCredits: z.ZodOptional<z.ZodObject<{
+            availableCount: z.ZodNumber;
+        }, z.core.$strip>>;
         metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         raw: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strip>>;

package/dist/types/auth-gateway/server.d.ts

@@ -1,3 +1,22 @@
+/**
+ * prometheus auth-gateway HTTP server.
+ *
+ * Accepts any provider-format request (OpenAI chat-completions, Anthropic
+ * messages, OpenAI Responses) and dispatches through Prometheus AI's `streamSimple()`
+ * — which handles credential injection, anthropic-beta headers, codex
+ * websocket transport, and all the per-provider intricacies. The gateway is
+ * pure protocol translation: foreign wire → prometheus Context → Prometheus AI stream() →
+ * prometheus events → foreign wire.
+ *
+ * Endpoints:
+ *   GET  /healthz                          → unauth; ok + version
+ *   GET  /v1/usage                         → aggregated provider usage (5-min per-credential cache via AuthStorage)
+ *   GET  /v1/credentials/check             → per-credential auth probe (diagnose 401s in a multi-account pool)
+ *   GET  /v1/models                        → list known models from the registry
+ *   POST /v1/chat/completions              → OpenAI chat-completions in/out
+ *   POST /v1/messages                      → Anthropic messages in/out
+ *   POST /v1/responses                     → OpenAI Responses in/out
+ */
 import type { AuthStorage } from "../auth-storage";
 import type { Api, Model } from "../types";
 import type { AuthGatewayServerHandle, AuthGatewayServerOptions } from "./types";

package/dist/types/auth-gateway/types.d.ts

@@ -1,4 +1,4 @@
-import type { Effort } from "../model-thinking";
+import type { Effort } from "@prometheus-ai/catalog/effort";
 import type { AssistantMessage, AssistantMessageEventStream, CacheRetention, Context, ServiceTier, TokenTaskBudget } from "../types";
 /**
  * Wire types for the prometheus auth-gateway.
@@ -6,7 +6,7 @@ import type { AssistantMessage, AssistantMessageEventStream, CacheRetention, Con
  * The gateway sits between unauthenticated clients (containerized prometheus,
  * llm-git, …) and the broker. It accepts provider-format HTTP requests
  * (OpenAI chat-completions / Anthropic messages / OpenAI Responses),
- * dispatches them through @prometheus-ai/ai's `streamSimple()`, and translates the
+ * dispatches them through Prometheus AI's `streamSimple()`, and translates the
  * canonical event stream back to the matching wire format. The gateway
  * injects `Authorization` server-side so clients never see access tokens.
  */
@@ -90,10 +90,16 @@ export interface AuthGatewayParsedRequest {
     stream: boolean;
     options: AuthGatewayParsedRequestOptions;
 }
+export interface AuthGatewayStreamControl {
+    /** Gateway request signal. Encoders stop producing frames when it aborts. */
+    signal?: AbortSignal;
+    /** Called when the HTTP response body is cancelled by the client. */
+    onCancel?: (reason?: unknown) => void;
+}
 export interface AuthGatewayFormatModule {
     parseRequest(body: unknown, headers?: Headers): AuthGatewayParsedRequest;
     encodeResponse(message: AssistantMessage, requestedModelId: string): Record<string, unknown>;
-    encodeStream(events: AssistantMessageEventStream, requestedModelId: string, options?: AuthGatewayParsedRequestOptions): ReadableStream<Uint8Array>;
+    encodeStream(events: AssistantMessageEventStream, requestedModelId: string, options?: AuthGatewayParsedRequestOptions, control?: AuthGatewayStreamControl): ReadableStream<Uint8Array>;
     /**
      * Emit a protocol-specific error envelope. OpenAI returns
      * `{ error: { message, type } }`; Anthropic returns

package/dist/types/auth-retry.d.ts

@@ -0,0 +1,119 @@
+import type { OAuthAccess } from "./auth-storage";
+/**
+ * Context passed to an {@link ApiKeyResolver} on each resolution attempt.
+ *
+ * The `error`/`lastChance` pair drives the central a/b/c retry policy shared by
+ * the streaming ({@link streamSimple}) and non-streaming ({@link withAuth})
+ * drivers:
+ * - `error === undefined` → **initial resolve** (no force-refresh; cheap, may
+ *   return a locally-cached not-yet-expired token).
+ * - `error !== undefined && !lastChance` → **step (b): refresh the SAME
+ *   account** (force a token re-mint / await an in-flight broker refresh).
+ * - `error !== undefined && lastChance` → **step (c): switch account**
+ *   (invalidate/usage-limit the current credential and rotate to a sibling).
+ *
+ * The resolver returns the bearer to send, or `undefined` to stop retrying and
+ * surface the last error to the caller.
+ */
+export interface ApiKeyResolveContext {
+    /** True on the final retry step — the resolver should rotate to a sibling credential. */
+    lastChance: boolean;
+    /** The auth error that triggered this re-resolution, or `undefined` on the initial resolve. */
+    error: unknown;
+    /** Caller cancel signal, threaded into any credential refresh / rotation work. */
+    signal?: AbortSignal;
+}
+/**
+ * Resolves the API key to send for a request, retried through the a/b/c policy
+ * described on {@link ApiKeyResolveContext}.
+ */
+export type ApiKeyResolver = (ctx: ApiKeyResolveContext) => Promise<string | undefined> | string | undefined;
+/** A static bearer string, or a {@link ApiKeyResolver} that mints/rotates one. */
+export type ApiKey = string | ApiKeyResolver;
+/** Narrows {@link ApiKey} to its resolver form. */
+export declare function isApiKeyResolver(key: ApiKey | undefined): key is ApiKeyResolver;
+/**
+ * Performs the initial resolve of an {@link ApiKey} (`error: undefined`,
+ * `lastChance: false`). Static keys pass through unchanged.
+ */
+export declare function resolveApiKeyOnce(key: ApiKey | undefined, signal?: AbortSignal): Promise<string | undefined>;
+/**
+ * Classifies whether an error should trigger a credential refresh/rotation
+ * retry: a hard `401`, or a rotatable usage-limit ("usage_limit_reached",
+ * Codex's "you have hit your ChatGPT usage limit", etc.).
+ */
+export declare function isAuthRetryableError(error: unknown): boolean;
+/**
+ * The ordered `lastChance` values for the retry steps after the initial
+ * attempt fails: `false` → step (b) refresh-same, `true` → step (c) switch.
+ * Shared by {@link withAuth} and the streaming retry driver so both run the
+ * same policy.
+ */
+export declare const AUTH_RETRY_STEPS: readonly boolean[];
+/** Resolve a single retry step, swallowing resolver failures into `undefined`. */
+export declare function resolveRetryKey(resolver: ApiKeyResolver, lastChance: boolean, error: unknown, signal?: AbortSignal): Promise<string | undefined>;
+/**
+ * Runs an auth-protected operation through the central a/b/c retry policy.
+ *
+ * - A static string key (or any non-resolver) → a single `attempt` with no
+ *   retry (identical to the legacy static-key path).
+ * - A resolver → initial `attempt`, then on a retryable auth error up to two
+ *   more attempts (refresh-same, then switch). A step is skipped when the
+ *   resolver returns the same key it just tried or `undefined`; non-auth errors
+ *   propagate immediately.
+ *
+ * Used by non-streaming consumers (image generation, web search, completion
+ * helpers). The streaming driver in `stream.ts` implements the same policy with
+ * its replay-safe buffering machinery.
+ */
+export declare function withAuth<T>(key: ApiKey | undefined, attempt: (key: string) => Promise<T>, opts?: {
+    isAuthError?: (error: unknown) => boolean;
+    signal?: AbortSignal;
+    missingKeyMessage?: string;
+}): Promise<T>;
+/**
+ * Minimal structural slice of `AuthStorage` consumed by {@link withOAuthAccess}.
+ * Typed structurally (and importing only the `OAuthAccess` type) so this module
+ * never takes a runtime dependency on `./auth-storage`.
+ */
+export interface OAuthAccessSource {
+    getOAuthAccess(provider: string, sessionId?: string, options?: {
+        forceRefresh?: boolean;
+        signal?: AbortSignal;
+    }): Promise<OAuthAccess | undefined>;
+    rotateSessionCredential(provider: string, sessionId: string | undefined, options?: {
+        error?: unknown;
+        signal?: AbortSignal;
+    }): Promise<boolean>;
+}
+export interface WithOAuthAccessOptions {
+    /** Session id for credential stickiness, threaded into every resolve. */
+    sessionId?: string;
+    signal?: AbortSignal;
+    /** Override the retryable-error classifier (default {@link isAuthRetryableError}). */
+    isAuthError?: (error: unknown) => boolean;
+    /**
+     * Pre-resolved access used for the initial attempt. Callers that already
+     * resolved access for an availability gate pass it here so the helper
+     * doesn't double-resolve (mirrors the gateway resolver's `initialKey`).
+     */
+    seed?: OAuthAccess;
+    missingAccessMessage?: string;
+}
+/**
+ * {@link withAuth} for OAuth-access consumers: runs an auth-protected
+ * operation through the central a/b/c retry policy, handing the attempt the
+ * full {@link OAuthAccess} (bearer + identity metadata: `accountId`,
+ * `projectId`, `enterpriseUrl`) instead of bare API-key bytes.
+ *
+ * - initial → `getOAuthAccess` (or `opts.seed`).
+ * - step (b) → `getOAuthAccess` with `forceRefresh: true` (re-mint the SAME
+ *   account; picks up peer/broker rotations).
+ * - step (c) → `rotateSessionCredential` then re-resolve (switch to a sibling).
+ *
+ * A step is skipped when it yields no access or the same `accessToken` that
+ * just failed; non-auth errors propagate immediately. Use this instead of
+ * hand-rolled `getOAuthAccess` + fetch flows so 401s and usage-limits rotate
+ * credentials instead of failing the call.
+ */
+export declare function withOAuthAccess<T>(storage: OAuthAccessSource, provider: string, attempt: (access: OAuthAccess) => Promise<T>, opts?: WithOAuthAccessOptions): Promise<T>;

package/dist/types/auth-storage.d.ts

@@ -8,9 +8,11 @@
  * - `SqliteAuthCredentialStore`: concrete SQLite-backed implementation
  */
 import { Database } from "bun:sqlite";
+import type { ApiKeyResolver } from "./auth-retry";
+import type { OAuthController, OAuthCredentials, OAuthProviderId } from "./registry/oauth/types";
 import type { Provider } from "./types";
-import type { CredentialRankingStrategy, UsageLogger, UsageProvider, UsageReport } from "./usage";
-import type { OAuthController, OAuthCredentials, OAuthProviderId } from "./utils/oauth/types";
+import type { CredentialRankingStrategy, UsageHistoryEntry, UsageHistoryQuery, UsageLogger, UsageProvider, UsageReport } from "./usage";
+import { type CodexResetConsumeCode, type CodexResetCredit } from "./usage/openai-codex-reset";
 export type ApiKeyCredential = {
     type: "api_key";
     key: string;
@@ -21,6 +23,21 @@ export type OAuthCredential = {
 export type AuthCredential = ApiKeyCredential | OAuthCredential;
 export type AuthCredentialEntry = AuthCredential | AuthCredential[];
 export type AuthStorageData = Record<string, AuthCredentialEntry>;
+/**
+ * Cascade leg that supplies a provider's active credential, highest precedence
+ * first — mirrors {@link AuthStorage.getApiKey}'s resolution order.
+ */
+export type CredentialOriginKind = "runtime" | "config" | "oauth" | "api_key" | "env" | "fallback";
+/**
+ * Structured provenance for a provider's auth, for UI that needs a machine
+ * tag (the `/login` provider list) rather than the prose of
+ * {@link AuthStorage.describeCredentialSource}.
+ */
+export interface CredentialOrigin {
+    kind: CredentialOriginKind;
+    /** Env var name when `kind === "env"` and a single named variable backs it. */
+    envVar?: string;
+}
 /**
  * Serialized representation of AuthStorage for passing to subagent workers.
  * Contains only the essential credential data, not runtime state.
@@ -209,6 +226,14 @@ export interface AuthCredentialStore {
     }): string | null;
     setCache(key: string, value: string, expiresAtSec: number): void;
     cleanExpiredCache(): void;
+    /**
+     * Append usage-limit snapshots for trend history. Optional: stores without
+     * durable storage (e.g. the broker remote store) omit it and recording is
+     * skipped — the broker host records into its own database instead.
+     */
+    recordUsageSnapshots?(entries: UsageHistoryEntry[]): void;
+    /** Read recorded usage-limit snapshots, oldest first. */
+    listUsageHistory?(query?: UsageHistoryQuery): UsageHistoryEntry[];
     /**
      * Optional store-supplied OAuth refresh. When present, `AuthStorage` uses
      * it before the per-provider local refresh path. `RemoteAuthCredentialStore`
@@ -283,6 +308,11 @@ export interface AuthCredentialStore {
      * `replaceAuthCredentialsForProvider`.
      */
     replaceAuthCredentialsRemote?(provider: string, credentials: AuthCredential[]): Promise<StoredAuthCredential[]>;
+    /**
+     * Optional async write hook for disabling one stored credential. Remote stores
+     * use it to await broker persistence before AuthStorage updates its snapshot.
+     */
+    deleteAuthCredentialRemote?(id: number, disabledCause: string): Promise<boolean>;
     /**
      * Optional async write hook for clearing every credential for a provider
      * (logout). When present, `AuthStorage.remove` routes through this instead
@@ -341,7 +371,7 @@ export type AuthStorageOptions = {
      *
      * Examples:
      * - `"local ~/.prometheus/agent/agent.db"`
-     * - `"broker http://can.internal:8765"`
+     * - `"broker http://auth-broker.internal:8765"`
      */
     sourceLabel?: string;
     /**
@@ -349,7 +379,7 @@ export type AuthStorageOptions = {
      * calls this instead of fanning out per-credential. The primary use case is
      * routing through a broker that egresses from a less-throttled IP — e.g. a
      * residential laptop trips Anthropic's per-IP rate limit on the usage
-     * endpoint and drops 2-of-5 credentials, while the VPS broker gets all 5.
+     * endpoint and drops 2-of-5 credentials, while the broker gets all 5.
      *
      * Implementations may return null when no usage data is available; the
      * AuthStorage caller surfaces that to its own consumer unchanged.
@@ -357,6 +387,22 @@ export type AuthStorageOptions = {
     fetchUsageReports?: (signal?: AbortSignal) => Promise<UsageReport[] | null>;
 };
 export declare function isDefinitiveOAuthFailure(errorMsg: string): boolean;
+/**
+ * Outcome of {@link AuthStorage.markUsageLimitReached}.
+ *
+ * `switched` is `true` when an unblocked same-type sibling credential is
+ * available right now, so the caller can retry immediately and the next
+ * `getApiKey` will hand it out. When `false`, `retryAtMs` (epoch ms) carries
+ * the earliest moment any same-type sibling's temporary block expires —
+ * callers should prefer waiting until then over the provider's (often
+ * multi-hour) retry-after when it is sooner. `retryAtMs` is `undefined` when
+ * no sibling credentials exist at all, or when the session has no tracked
+ * credential to rotate away from.
+ */
+export interface UsageLimitMarkResult {
+    switched: boolean;
+    retryAtMs?: number;
+}
 type AuthApiKeyOptions = {
     baseUrl?: string;
     modelId?: string;
@@ -366,6 +412,13 @@ type AuthApiKeyOptions = {
      * stranding the caller for `timeoutMs * (maxRetries + 1)`.
      */
     signal?: AbortSignal;
+    /**
+     * Force a re-mint of the session-preferred OAuth credential's access token,
+     * bypassing the not-yet-expired short-circuit. Powers step (b) of the
+     * auth-retry policy ("refresh the SAME account") so a locally-cached token
+     * that a peer/broker rotated out from under us is replaced before retrying.
+     */
+    forceRefresh?: boolean;
 };
 /**
  * Refreshed OAuth access plus identity metadata returned by
@@ -391,6 +444,17 @@ export interface OAuthAccessFailure {
     enterpriseUrl?: string;
     error: string;
 }
+/**
+ * Identity of the OAuth credential a session is currently routed to. Read-only
+ * display/metadata shape: `accountId` is the provider's account UUID, `email`
+ * the user-facing login, `projectId` the GCP-style project for providers that
+ * key usage on it (Gemini CLI / Antigravity).
+ */
+export interface OAuthAccountIdentity {
+    accountId?: string;
+    email?: string;
+    projectId?: string;
+}
 export type OAuthAccessResolution = ({
     ok: true;
 } & OAuthAccess) | ({
@@ -400,6 +464,44 @@ export interface InvalidateCredentialMatchingOptions {
     signal?: AbortSignal;
     sessionId?: string;
 }
+/**
+ * Identifies which stored account to redeem a saved rate-limit reset for.
+ * Any one field is enough; `credentialId` is the most precise.
+ */
+export interface ResetCreditTarget {
+    credentialId?: number;
+    accountId?: string;
+    email?: string;
+}
+/** Outcome of {@link AuthStorage.redeemResetCredit}. */
+export interface ResetCreditRedeemOutcome {
+    /** `true` only when a reset was actually applied (`code === "reset"`). */
+    ok: boolean;
+    /**
+     * Result code. Backend codes: `reset` (success), `already_redeemed`,
+     * `no_credit`, `nothing_to_reset`. Locally-synthesized: `no_account`
+     * (target not found), `account_unavailable` (token refresh failed),
+     * `http_<status>` (unexpected HTTP).
+     */
+    code: CodexResetConsumeCode;
+    accountId?: string;
+    email?: string;
+    /** The credit that was spent (when one was). */
+    creditId?: string;
+}
+/** One stored account's live saved-reset status, from {@link AuthStorage.listResetCredits}. */
+export interface ResetCreditAccountStatus {
+    credentialId?: number;
+    accountId?: string;
+    email?: string;
+    /** Resets redeemable for this account right now (live, not cached). */
+    availableCount: number;
+    credits: CodexResetCredit[];
+    /** Whether this is the given session's active account. */
+    active: boolean;
+    /** Set when the account's token refresh or list call failed. */
+    error?: string;
+}
 /**
  * Credential storage backed by an AuthCredentialStore.
  * Reads from storage on reload(), manages round-robin credential selection,
@@ -410,7 +512,7 @@ export declare class AuthStorage {
     constructor(store: AuthCredentialStore, options?: AuthStorageOptions);
     /**
      * Create an AuthStorage instance backed by a AuthCredentialStore.
-     * Convenience factory for standalone use (e.g., @prometheus-ai/ai CLI).
+     * Convenience factory for standalone use (e.g., Prometheus AI CLI).
      * @param dbPath - Path to SQLite database
      */
     static create(dbPath: string, options?: AuthStorageOptions): Promise<AuthStorage>;
@@ -488,10 +590,18 @@ export declare class AuthStorage {
      * Set credential for a provider.
      */
     set(provider: string, credential: AuthCredentialEntry): Promise<void>;
+    /**
+     * List stored credential rows, optionally filtered by provider.
+     */
+    listStoredCredentials(provider?: string): StoredAuthCredential[];
     /**
      * Remove credential for a provider.
      */
     remove(provider: string): Promise<void>;
+    /**
+     * Remove one stored credential for a provider.
+     */
+    removeCredential(provider: string, credentialId: number): Promise<boolean>;
     /**
      * List all providers with credentials.
      */
@@ -517,6 +627,15 @@ export declare class AuthStorage {
      * silently satisfies xai-oauth and routes around `providers.xai.baseUrl`.
      */
     hasNonEnvCredential(provider: string): boolean;
+    /**
+     * Classify where a provider's auth comes from, following the same precedence
+     * as {@link AuthStorage.getApiKey}: runtime override → config override →
+     * stored credential (api_key before oauth, matching getApiKey) → env var →
+     * fallback resolver. Returns undefined when no auth is configured.
+     *
+     * Compact, structured counterpart to {@link describeCredentialSource}.
+     */
+    getCredentialOrigin(provider: string): CredentialOrigin | undefined;
     /**
      * Check if OAuth credentials are configured for a provider.
      */
@@ -533,6 +652,12 @@ export declare class AuthStorage {
      * Returns `undefined` when no OAuth credential carries an `accountId`.
      */
     getOAuthAccountId(provider: string, sessionId?: string): string | undefined;
+    /**
+     * Get the OAuth account identity for a provider, preferring the credential that
+     * is session-sticky for `sessionId`. This is a read-only lookup for display and
+     * metadata paths; it does not refresh tokens, rank usage, or advance selection.
+     */
+    getOAuthAccountIdentity(provider: string, sessionId?: string): OAuthAccountIdentity | undefined;
     /**
      * Get all credentials.
      */
@@ -556,6 +681,11 @@ export declare class AuthStorage {
      * Logout from a provider.
      */
     logout(provider: string): Promise<void>;
+    /**
+     * Recorded usage-limit snapshots, oldest first. Empty when the underlying
+     * store has no durable history (e.g. a broker-backed remote store).
+     */
+    listUsageHistory(query?: UsageHistoryQuery): UsageHistoryEntry[];
     ingestUsageHeaders(provider: Provider, headers: Record<string, string>, options?: {
         sessionId?: string;
         baseUrl?: string;
@@ -595,13 +725,16 @@ export declare class AuthStorage {
     /**
      * Marks the current session's credential as temporarily blocked due to usage limits.
      * Uses usage reports to determine accurate reset time when available.
-     * Returns true if a credential was blocked, enabling automatic fallback to the next credential.
+     * Returns whether a sibling credential is available now; when none is, also
+     * reports the earliest time a blocked sibling becomes available again so
+     * callers can wait for the sibling instead of the provider's full window.
      */
     markUsageLimitReached(provider: string, sessionId: string | undefined, options?: {
         retryAfterMs?: number;
         baseUrl?: string;
+        modelId?: string;
         signal?: AbortSignal;
-    }): Promise<boolean>;
+    }): Promise<UsageLimitMarkResult>;
     /**
      * Peek at API key for a provider without refreshing OAuth tokens.
      * Used for model discovery where we only need to know if credentials exist
@@ -645,8 +778,76 @@ export declare class AuthStorage {
      * exercise each stored account exactly once.
      */
     getOAuthAccesses(provider: string, options?: AuthApiKeyOptions): Promise<OAuthAccessResolution[]>;
+    /**
+     * List saved rate-limit resets for every stored OAuth account of `provider`
+     * (Codex), fetched LIVE from the dedicated `rate-limit-reset-credits` route.
+     *
+     * This deliberately bypasses the usage-report cache: `/wham/usage` is
+     * IP-rate-limited and may serve stale (or pre-feature) snapshots when many
+     * accounts are polled, which would hide redeemable credits. One entry per
+     * account, with the session's active account flagged and unreachable
+     * accounts carrying an `error`.
+     */
+    listResetCredits(options?: {
+        provider?: string;
+        sessionId?: string;
+        baseUrlResolver?: (provider: string) => string | undefined;
+        signal?: AbortSignal;
+    }): Promise<ResetCreditAccountStatus[]>;
+    /**
+     * Redeem one saved rate-limit reset (OpenAI Codex "saved resets") for a
+     * specific stored account.
+     *
+     * Resolves a fresh access token for the target account, picks an available
+     * credit (the given `creditId`, else the first redeemable one), spends it,
+     * and invalidates the cached usage report so the next `/usage` reflects the
+     * reset. Never throws for business outcomes — inspect the returned `code`.
+     */
+    redeemResetCredit(options: {
+        target: ResetCreditTarget;
+        provider?: string;
+        creditId?: string;
+        baseUrlResolver?: (provider: string) => string | undefined;
+        signal?: AbortSignal;
+    }): Promise<ResetCreditRedeemOutcome>;
     invalidateCredentialMatching(provider: string, apiKey: string, options?: InvalidateCredentialMatchingOptions): Promise<boolean>;
     invalidateCredentialMatching(provider: string, apiKey: string, signal?: AbortSignal): Promise<boolean>;
+    /**
+     * Rotate away from the session's current credential after a retryable auth
+     * error — step (c) of the auth-retry policy. Stateless: looks up the
+     * session-sticky credential (no API-key matching needed), applies the
+     * storage action for the error class, then clears the sticky so the next
+     * {@link AuthStorage.getApiKey} for this session picks a sibling.
+     *
+     * - usage-limit / account-rate-limit error → {@link AuthStorage.markUsageLimitReached}
+     *   (temporary block via its own backoff — default plus server usage-report
+     *   reset; sticky left intact so the next resolve re-ranks around the block).
+     * - otherwise (hard 401 / auth failure) → mark the credential suspect (or
+     *   reload when no broker hook is wired) and block it, then drop the sticky.
+     *
+     * Returns whether another usable credential of the same type remains.
+     */
+    rotateSessionCredential(provider: string, sessionId: string | undefined, options?: {
+        error?: unknown;
+        modelId?: string;
+        signal?: AbortSignal;
+    }): Promise<boolean>;
+    /**
+     * Build an {@link ApiKeyResolver} backed by this storage, implementing the
+     * central a/b/c auth-retry policy:
+     *
+     * - initial (`error: undefined`) → resolve the session credential.
+     * - step (b) `!lastChance` → force-refresh the SAME session-sticky credential.
+     * - step (c) `lastChance` → rotate to a sibling credential, then re-resolve.
+     *
+     * Used by web-search providers and other consumers that hold an AuthStorage
+     * directly (no ModelRegistry in scope).
+     */
+    resolver(provider: string, options?: {
+        sessionId?: string;
+        baseUrl?: string;
+        modelId?: string;
+    }): ApiKeyResolver;
     /**
      * Build a redacted snapshot of all loaded credentials for the auth-broker
      * wire. OAuth refresh tokens are replaced with {@link REMOTE_REFRESH_SENTINEL}
@@ -702,10 +903,16 @@ export declare class AuthStorage {
      */
     describeCredentialSource(provider: string, sessionId?: string): string | undefined;
 }
+/**
+ * SQLite's busy result code family — base `SQLITE_BUSY` plus the extended
+ * variants `SQLITE_BUSY_RECOVERY` (concurrent WAL recovery), `SQLITE_BUSY_SNAPSHOT`,
+ * and `SQLITE_BUSY_TIMEOUT`. All warrant the same backoff-and-retry treatment.
+ */
+export declare function isSqliteBusyError(err: unknown): boolean;
 /**
  * Default SQLite-backed implementation of {@link AuthCredentialStore}.
  *
- * Used by the @prometheus-ai/ai CLI and as the default store for `AuthStorage.create()`.
+ * Used by the Prometheus AI CLI and as the default store for `AuthStorage.create()`.
  * Also exposes convenience methods (`saveOAuth`, `getOAuth`, `saveApiKey`,
  * `getApiKey`, `listProviders`, `deleteProvider`) that callers can use directly
  * without going through `AuthStorage`.
@@ -732,6 +939,8 @@ export declare class SqliteAuthCredentialStore implements AuthCredentialStore {
     }): string | null;
     setCache(key: string, value: string, expiresAtSec: number): void;
     cleanExpiredCache(): void;
+    recordUsageSnapshots(entries: UsageHistoryEntry[]): void;
+    listUsageHistory(query?: UsageHistoryQuery): UsageHistoryEntry[];
     /**
      * Save OAuth credentials for a provider.
      * Preserves unrelated identities and replaces only the matching credential.

package/dist/types/errors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Structured HTTP errors thrown by provider clients.
+ *
+ * Downstream classification reads these fields structurally rather than via
+ * `instanceof`: `extractHttpStatusFromError` (@prometheus-ai/utils) reads `status`,
+ * `getHeadersFromError` (retry-after extraction) reads `headers`, and retry
+ * policies such as `isCopilotTransientModelError` read `code`. Per-provider
+ * subclasses exist so call sites can narrow with `instanceof` and logs carry
+ * a meaningful `error.name`.
+ */
+export interface ProviderHttpErrorOptions {
+    /** Response headers; enables `retry-after`/rate-limit extraction downstream. */
+    headers?: Headers;
+    /** Machine-readable error code from the response body (`error.code` / `error.type`). */
+    code?: string;
+    cause?: unknown;
+}
+/** Non-2xx HTTP response from a provider endpoint. */
+export declare class ProviderHttpError extends Error {
+    readonly status: number;
+    readonly headers: Headers | undefined;
+    readonly code: string | undefined;
+    constructor(message: string, status: number, options?: ProviderHttpErrorOptions);
+}

package/dist/types/index.d.ts

@@ -1,15 +1,13 @@
+export { ANTIGRAVITY_SYSTEM_INSTRUCTION, getAntigravityUserAgent, getGeminiCliHeaders, } from "@prometheus-ai/catalog/wire/gemini-headers";
 export { type ZodType, z } from "zod/v4";
 export * from "./api-registry";
 export * from "./auth-broker";
 export { type AuthGatewayBootOptions, type ModelResolver, startAuthGateway } from "./auth-gateway/server";
 export * from "./auth-gateway/types";
+export * from "./auth-retry";
 export * from "./auth-storage";
-export * from "./model-cache";
-export * from "./model-manager";
-export * from "./model-thinking";
-export * from "./models";
+export * from "./errors";
 export * from "./provider-details";
-export * from "./provider-models";
 export * from "./providers/anthropic";
 export * from "./providers/anthropic-client";
 export * from "./providers/azure-openai-responses";
@@ -17,7 +15,6 @@ export type * from "./providers/cursor";
 export * from "./providers/gitlab-duo";
 export type * from "./providers/google";
 export type * from "./providers/google-gemini-cli";
-export * from "./providers/google-gemini-headers";
 export type * from "./providers/google-vertex";
 export * from "./providers/kimi";
 export * from "./providers/mock";
@@ -27,6 +24,7 @@ export * from "./providers/openai-completions";
 export * from "./providers/openai-responses";
 export * from "./providers/synthetic";
 export * from "./rate-limit-utils";
+export * from "./registry";
 export * from "./stream";
 export * from "./types";
 export * from "./usage";
@@ -37,12 +35,10 @@ export * from "./usage/google-antigravity";
 export * from "./usage/kimi";
 export * from "./usage/minimax-code";
 export * from "./usage/openai-codex";
+export * from "./usage/openai-codex-reset";
 export * from "./usage/zai";
 export * from "./utils/anthropic-auth";
-export * from "./utils/discovery";
 export * from "./utils/event-stream";
-export * from "./utils/oauth";
-export type { OAuthCredentials, OAuthProvider, OAuthProviderId, OAuthProviderInfo, } from "./utils/oauth/types";
 export * from "./utils/overflow";
 export * from "./utils/retry";
 export * from "./utils/schema";

package/dist/types/provider-details.d.ts

@@ -14,7 +14,7 @@ export interface ProviderDetailsContext {
     authMode?: string;
     /**
      * Human-readable description of the active credential, e.g.
-     * `"broker http://can.internal:8765 · oauth #5 (foo@bar.com)"`.
+     * `"broker http://auth-broker.internal:8765 - oauth #5 (foo@bar.com)"`.
      * Rendered as a `Source` field; omitted when undefined.
      */
     credentialSource?: string;