@prometheus-ai/ai 0.5.3 → 0.5.8

package/dist/types/types.d.ts

@@ -1,9 +1,15 @@
+export * from "@prometheus-ai/catalog/effort";
+export * from "@prometheus-ai/catalog/types";
+import type { DeleteArgs, DeleteResult, DiagnosticsArgs, DiagnosticsResult, GrepArgs, GrepResult, LsArgs, LsResult, McpResult, ReadArgs, ReadResult, ShellArgs, ShellResult, WriteArgs, WriteResult } from "@prometheus-ai/catalog/discovery/cursor-gen/agent_pb";
+import type { Effort } from "@prometheus-ai/catalog/effort";
+import type { Api, FetchImpl, Model, Provider, ThinkingBudgets, Usage } from "@prometheus-ai/catalog/types";
 import type { ZodType, z } from "zod/v4";
+import type { ApiKey } from "./auth-retry";
 import type { BedrockOptions } from "./providers/amazon-bedrock";
 import type { AnthropicOptions } from "./providers/anthropic";
+import type { StopDetails } from "./providers/anthropic-wire";
 import type { AzureOpenAIResponsesOptions } from "./providers/azure-openai-responses";
 import type { CursorOptions } from "./providers/cursor";
-import type { DeleteArgs, DeleteResult, DiagnosticsArgs, DiagnosticsResult, GrepArgs, GrepResult, LsArgs, LsResult, McpResult, ReadArgs, ReadResult, ShellArgs, ShellResult, WriteArgs, WriteResult } from "./providers/cursor/gen/agent_pb";
 import type { GoogleOptions } from "./providers/google";
 import type { GoogleGeminiCliOptions } from "./providers/google-gemini-cli";
 import type { GoogleVertexOptions } from "./providers/google-vertex";
@@ -12,9 +18,20 @@ import type { OpenAICodexResponsesOptions } from "./providers/openai-codex-respo
 import type { OpenAICompletionsOptions } from "./providers/openai-completions";
 import type { OpenAIResponsesOptions } from "./providers/openai-responses";
 import type { AssistantMessageEventStream } from "./utils/event-stream";
+export type { StopDetails } from "./providers/anthropic-wire";
 export type { AssistantMessageEventStream } from "./utils/event-stream";
-export type KnownApi = "openai-completions" | "openai-responses" | "openai-codex-responses" | "azure-openai-responses" | "anthropic-messages" | "bedrock-converse-stream" | "google-generative-ai" | "google-gemini-cli" | "google-vertex" | "ollama-chat" | "cursor-agent";
-export type Api = KnownApi | (string & {});
+/**
+ * Ceiling on the output-token count prometheus requests from any OpenAI-family endpoint
+ * (openai-responses, azure/xai responses, and openai-completions). Mirrors
+ * Anthropic's {@link CLAUDE_CODE_MAX_OUTPUT_TOKENS}.
+ *
+ * Catalog `maxTokens` frequently reflects a model's context window rather than a
+ * given upstream's real per-request output cap. OpenRouter, for instance,
+ * advertises 131072 output tokens for `z-ai/glm-4.7`, but the Cerebras upstream
+ * only allows ~131072 tokens total — so requesting the full ceiling overflows
+ * with a 400. Requested output is clamped to this value (and to `model.maxTokens`).
+ */
+export declare const OPENAI_MAX_OUTPUT_TOKENS = 64000;
 export interface ApiOptionsMap {
     "anthropic-messages": AnthropicOptions;
     "bedrock-converse-stream": BedrockOptions;
@@ -29,32 +46,6 @@ export interface ApiOptionsMap {
     "cursor-agent": CursorOptions;
 }
 export type OptionsForApi<TApi extends Api> = StreamOptions | (TApi extends keyof ApiOptionsMap ? ApiOptionsMap[TApi] : never);
-/** Canonical thinking transport used by a model. */
-export type ThinkingControlMode = "effort" | "budget" | "google-level" | "anthropic-adaptive" | "anthropic-budget-effort";
-/** Per-model thinking capabilities used to clamp and map user-facing effort levels. */
-export interface ThinkingConfig {
-    /** Least intensive supported user-facing effort level. */
-    minLevel: Effort;
-    /** Most intensive supported user-facing effort level. */
-    maxLevel: Effort;
-    /**
-     * Optional explicit list of supported levels. When present, takes precedence over
-     * the `minLevel`..`maxLevel` range — used to encode discrete sets with gaps
-     * (e.g. Gemini 3 Pro supports `low` and `high` but not `medium`).
-     */
-    levels?: readonly Effort[];
-    /** Optional default effort applied when this model is selected. Falls back to global default if absent. */
-    defaultLevel?: Effort;
-    /** Provider-specific transport used to encode the selected effort. */
-    mode: ThinkingControlMode;
-}
-export type KnownProvider = "alibaba-coding-plan" | "amazon-bedrock" | "anthropic" | "google" | "google-gemini-cli" | "google-antigravity" | "google-vertex" | "openai" | "openai-codex" | "kimi-code" | "minimax-code" | "minimax-code-cn" | "github-copilot" | "fireworks" | "firepass" | "gitlab-duo" | "cursor" | "deepseek" | "xai" | "xai-oauth" | "groq" | "cerebras" | "openrouter" | "kilo" | "vercel-ai-gateway" | "zai" | "zhipu-coding-plan" | "mistral" | "minimax" | "opencode-go" | "opencode-zen" | "synthetic" | "cloudflare-ai-gateway" | "huggingface" | "litellm" | "moonshot" | "nvidia" | "nanogpt" | "ollama" | "ollama-cloud" | "qianfan" | "qwen-portal" | "together" | "venice" | "vllm" | "xiaomi" | "xiaomi-token-plan-sgp" | "xiaomi-token-plan-ams" | "xiaomi-token-plan-cn" | "wafer-pass" | "wafer-serverless" | "zenmux" | "lm-studio";
-export type Provider = KnownProvider | string;
-import type { Effort } from "./model-thinking";
-/** Token budgets for each thinking level (token-based providers only) */
-export type ThinkingBudgets = {
-    [key in Effort]?: number;
-};
 export interface TokenTaskBudget {
     type: "tokens";
     total: number;
@@ -129,14 +120,6 @@ export interface RawSseEvent {
     data: string;
     raw: string[];
 }
-/**
- * `fetch`-compatible function. Accepts any callable matching the standard
- * fetch signature; `preconnect` is optional because non-Bun runtimes (browsers,
- * test mocks) won't expose it.
- */
-export type FetchImpl = ((input: string | URL | Request, init?: RequestInit) => Promise<Response>) & {
-    preconnect?: typeof globalThis.fetch.preconnect;
-};
 export interface StreamOptions {
     temperature?: number;
     topP?: number;
@@ -159,12 +142,6 @@ export interface StreamOptions {
     maxTokens?: number;
     signal?: AbortSignal;
     apiKey?: string;
-    /**
-     * Called when a provider returns 401 before any replay-unsafe assistant
-     * event has been emitted. Returning a different key retries the provider
-     * request once.
-     */
-    onAuthError?: (provider: string, apiKey: string, error: unknown) => Promise<string | undefined>;
     cacheRetention?: CacheRetention;
     /**
      * Additional headers to include in provider requests.
@@ -274,7 +251,21 @@ export interface StreamOptions {
     /** Cursor exec/MCP tool handlers (cursor-agent only). */
     execHandlers?: CursorExecHandlers;
 }
-export interface SimpleStreamOptions extends StreamOptions {
+export interface SimpleStreamOptions extends Omit<StreamOptions, "apiKey"> {
+    /**
+     * API key for the request: either a static bearer string, or an
+     * {@link ApiKeyResolver} that mints/rotates the key across the central
+     * a/b/c auth-retry policy. `streamSimple`/`completeSimple` resolve a
+     * resolver to a string before per-provider dispatch, so providers only
+     * ever see the resolved {@link StreamOptions.apiKey} string.
+     */
+    apiKey?: ApiKey;
+    /**
+     * Legacy static-key retry hook. New callers should pass an {@link ApiKeyResolver}
+     * as `apiKey`; `streamSimple` adapts this hook into that resolver shape for
+     * older Prometheus runtime paths.
+     */
+    onAuthError?: (provider: string, oldKey: string, error: unknown) => Promise<string | undefined> | string | undefined;
     reasoning?: Effort;
     /**
      * Force-disable reasoning for the request even when the model supports it.
@@ -345,6 +336,12 @@ export interface ImageContent {
     type: "image";
     data: string;
     mimeType: string;
+    /**
+     * OpenAI-only resolution hint. `"original"` preserves native resolution
+     * (required for snapcompact frames, whose glyphs do not survive the
+     * default `auto` downscale). Providers without a detail knob ignore it.
+     */
+    detail?: "auto" | "low" | "high" | "original";
 }
 export interface ToolCall {
     type: "toolCall";
@@ -362,52 +359,6 @@ export interface ToolCall {
      */
     customWireName?: string;
 }
-export interface Usage {
-    /** Non-cached input tokens (matches the bucket the provider bills as new input). */
-    input: number;
-    /** Total output tokens for the turn, including thinking, assistant text, and tool-call argument tokens. */
-    output: number;
-    /** Tokens read from the prompt cache. */
-    cacheRead: number;
-    /** Tokens written to the prompt cache (cache creation). */
-    cacheWrite: number;
-    /** Sum of input + output + cacheRead + cacheWrite. */
-    totalTokens: number;
-    /** Copilot premium-request counter, when applicable. */
-    premiumRequests?: number;
-    /**
-     * Reasoning/thinking tokens included in `output`, when the provider reports them
-     * (OpenAI `output_tokens_details.reasoning_tokens`, Google `thoughtsTokenCount`).
-     * Always a subset of `output` — non-reasoning output is `output - reasoningTokens`.
-     *
-     * Providers that don't expose this leave it undefined rather than guessing;
-     * `undefined` means unknown, NOT zero.
-     */
-    reasoningTokens?: number;
-    /**
-     * Cache-write TTL breakdown (Anthropic only). When set, the components sum to
-     * `cacheWrite`. Absent providers do not populate this.
-     */
-    cttl?: {
-        ephemeral5m?: number;
-        ephemeral1h?: number;
-    };
-    /**
-     * Server-side tool invocations made during this turn (Anthropic web_search /
-     * web_fetch, OpenAI built-in tools when reported). Counts requests, not tokens.
-     */
-    server?: {
-        webSearch?: number;
-        webFetch?: number;
-    };
-    cost: {
-        input: number;
-        output: number;
-        cacheRead: number;
-        cacheWrite: number;
-        total: number;
-    };
-}
 export type StopReason = "stop" | "length" | "toolUse" | "error" | "aborted";
 export interface OpenAIResponsesHistoryPayload {
     type: "openaiResponsesHistory";
@@ -445,8 +396,17 @@ export interface AssistantMessage {
     provider: Provider;
     model: string;
     responseId?: string;
+    /**
+     * Name of the upstream provider an aggregator routed this request to, as
+     * reported in the response (e.g. OpenRouter's top-level `provider` field:
+     * `"OpenAI"`, `"Anthropic"`, `"Together"`). Distinct from `provider`, which
+     * is the configured gateway we called (`"openrouter"`). Undefined for direct
+     * providers that expose no such field.
+     */
+    upstreamProvider?: string;
     usage: Usage;
     stopReason: StopReason;
+    stopDetails?: StopDetails | null;
     errorMessage?: string;
     /** HTTP status surfaced by the provider when the request failed. Populated by every provider's catch block alongside `errorMessage` so consumers (auth retry, telemetry, UI) can branch without regex-scraping the message. */
     errorStatus?: number;
@@ -475,6 +435,12 @@ export interface ToolResultMessage<TDetails = any> {
     attribution?: MessageAttribution;
     /** Timestamp when output was pruned (ms since epoch). Undefined if unpruned. */
     prunedAt?: number;
+    /**
+     * Tool-declared: this result carried no information worth retaining once
+     * consumed (zero matches, elapsed wait). Compaction passes may elide it.
+     * Never set together with isError.
+     */
+    useless?: boolean;
     timestamp: number;
 }
 export type Message = UserMessage | DeveloperMessage | AssistantMessage | ToolResultMessage;
@@ -612,208 +578,3 @@ export type AssistantMessageEvent = {
     reason: Extract<StopReason, "aborted" | "error">;
     error: AssistantMessage;
 };
-/**
- * Compatibility settings for openai-completions API.
- * Use this to override URL-based auto-detection for custom providers.
- */
-export interface OpenAICompat {
-    /** Whether the provider supports the `store` field. Default: auto-detected from URL. */
-    supportsStore?: boolean;
-    /** Whether the provider supports the `developer` role (vs `system`). Default: auto-detected from URL. */
-    supportsDeveloperRole?: boolean;
-    /**
-     * Whether the provider's chat-completions endpoint accepts multiple
-     * leading `system`/`developer` messages. When false, ordered system
-     * prompts are coalesced into a single message joined by `\n\n` so
-     * strict chat templates (e.g. Qwen-served via vLLM, MiniMax) accept
-     * the request. Default: detected per provider/baseUrl. Canonical
-     * OpenAI/Azure/OpenRouter/Cerebras/Together/Fireworks/Groq/DeepSeek/
-     * Mistral/xAI/Z.ai/GitHub Copilot/Zenmux are treated as `true`;
-     * unknown or strict-template hosts default to `false`. Setting this
-     * to `true` preserves separate blocks, which is preferred for
-     * KV-cache reuse when the trailing prompt changes between calls.
-     */
-    supportsMultipleSystemMessages?: boolean;
-    /** Whether the provider supports `reasoning_effort`. Default: auto-detected from URL. */
-    supportsReasoningEffort?: boolean;
-    /** Optional mapping from Prometheus AI reasoning levels to provider/model-specific `reasoning_effort` values. */
-    reasoningEffortMap?: Partial<Record<Effort, string>>;
-    /** Whether the provider supports `stream_options: { include_usage: true }` for token usage in streaming responses. Default: true. */
-    supportsUsageInStreaming?: boolean;
-    /** Which field to use for max tokens. Default: auto-detected from URL. */
-    maxTokensField?: "max_completion_tokens" | "max_tokens";
-    /** Whether tool results require the `name` field. Default: auto-detected from URL. */
-    requiresToolResultName?: boolean;
-    /** Whether a user message after tool results requires an assistant message in between. Default: auto-detected from URL. */
-    requiresAssistantAfterToolResult?: boolean;
-    /** Whether thinking blocks must be converted to text blocks with <thinking> delimiters. Default: auto-detected from URL. */
-    requiresThinkingAsText?: boolean;
-    /** Whether tool call IDs must be normalized to Mistral format (exactly 9 alphanumeric chars). Default: auto-detected from URL. */
-    requiresMistralToolIds?: boolean;
-    /** Format for reasoning/thinking parameter. "openai" uses reasoning_effort, "openrouter" uses reasoning: { effort }, "zai" uses thinking: { type: "enabled" | "disabled" } (also used by Moonshot Kimi), "qwen" uses top-level enable_thinking, and "qwen-chat-template" uses chat_template_kwargs.enable_thinking. Default: "openai". */
-    thinkingFormat?: "openai" | "openrouter" | "zai" | "qwen" | "qwen-chat-template";
-    /** Optional `thinking.keep` value for Z.ai/Moonshot-style thinking params. Set false to suppress auto-detected keep. Default: auto-detected. */
-    thinkingKeep?: "all" | false;
-    /** Which reasoning content field to emit on assistant messages. Default: auto-detected. */
-    reasoningContentField?: "reasoning_content" | "reasoning" | "reasoning_text";
-    /** Whether assistant tool-call messages must include reasoning content. Default: false. */
-    requiresReasoningContentForToolCalls?: boolean;
-    /** Whether the provider accepts a synthetic placeholder (e.g. ".") for missing reasoning_content on tool-call turns. Default: true. Set to false for providers like DeepSeek that validate the exact reasoning_content value. */
-    allowsSyntheticReasoningContentForToolCalls?: boolean;
-    /** Whether assistant tool-call messages must include non-empty content. Default: false. */
-    requiresAssistantContentForToolCalls?: boolean;
-    /** Whether the provider supports the `tool_choice` parameter. Default: true. */
-    supportsToolChoice?: boolean;
-    /**
-     * Drop reasoning fields (`reasoning_effort`, OpenRouter `reasoning`) for
-     * the request when `tool_choice` forces a tool call. Mirrors the Anthropic
-     * `disableThinkingIfToolChoiceForced` rule for backends like Kimi that
-     * 400 with `tool_choice 'specified' is incompatible with thinking
-     * enabled` whenever both are present. Default: auto-detected (Kimi).
-     */
-    disableReasoningOnForcedToolChoice?: boolean;
-    /**
-     * Drop reasoning fields (`reasoning_effort`, OpenRouter `reasoning`) for
-     * any request that sends `tool_choice`. Use for providers/models that accept
-     * tools and `tool_choice`, but reject `tool_choice` while thinking is enabled.
-     * Default: auto-detected (DeepSeek reasoning models).
-     */
-    disableReasoningOnToolChoice?: boolean;
-    /** OpenRouter-specific routing preferences. Only used when baseUrl points to OpenRouter. */
-    openRouterRouting?: OpenRouterRouting;
-    /** Vercel AI Gateway routing preferences. Only used when baseUrl points to Vercel AI Gateway. */
-    vercelGatewayRouting?: VercelGatewayRouting;
-    /** Extra fields to include in request body (e.g. gateway routing hints for OpenClaw-style proxies). */
-    extraBody?: Record<string, unknown>;
-    /** Whether chat-completions payloads should include provider-specific prompt-cache markers. */
-    cacheControlFormat?: "anthropic" | undefined;
-    /** Whether the provider supports the `strict` field in tool definitions. Default: auto-detected per provider/baseUrl (conservative for unknown providers). */
-    supportsStrictMode?: boolean;
-    /** Whether tool schemas must be sent either all strict or all non-strict. Undefined keeps the existing per-tool mixed behavior. */
-    toolStrictMode?: "all_strict" | "none";
-}
-/**
- * Compatibility settings for anthropic-messages API.
- * Use this to disable features that strict-by-default Anthropic accepts but
- * that proxy gateways (Vertex AI, AWS Bedrock-style fronts, etc.) reject.
- */
-export interface AnthropicCompat {
-    /**
-     * Drop the top-level `strict: true` field on tool definitions. Vertex AI's
-     * Anthropic-compatible endpoint rejects unknown tool fields with
-     * `tools.<n>.custom.strict: Extra inputs are not permitted`.
-     */
-    disableStrictTools?: boolean;
-    /**
-     * Map adaptive thinking (`thinking: { type: "adaptive" }`) to
-     * `{ type: "enabled", budget_tokens }`. Vertex AI rejects the `adaptive`
-     * tag with `Input tag 'adaptive' ... does not match any of the expected
-     * tags: 'disabled', 'enabled'`.
-     */
-    disableAdaptiveThinking?: boolean;
-    /** Whether tools may include Anthropic's per-tool eager_input_streaming flag. Default: true. */
-    supportsEagerToolInputStreaming?: boolean;
-    /** Whether long prompt-cache retention (`ttl: "1h"`) is supported. Default: true for canonical Anthropic API. */
-    supportsLongCacheRetention?: boolean;
-    /**
-     * Whether mid-conversation `role: "system"` messages are accepted in the
-     * `messages` array (Claude Opus 4.8+ on the first-party Claude API and
-     * Claude Platform on AWS). When unset, auto-detected from the model id and
-     * base URL. Not available on Bedrock, Vertex AI, or Microsoft Foundry.
-     */
-    supportsMidConversationSystem?: boolean;
-}
-/**
- * OpenRouter provider routing preferences.
- * Controls which upstream providers OpenRouter routes requests to.
- * @see https://openrouter.ai/docs/provider-routing
- */
-export interface OpenRouterRouting {
-    /** List of provider slugs to exclusively use for this request (e.g., ["amazon-bedrock", "anthropic"]). */
-    only?: string[];
-    /** List of provider slugs to try in order (e.g., ["anthropic", "openai"]). */
-    order?: string[];
-}
-/**
- * Vercel AI Gateway routing preferences.
- * Controls which upstream providers the gateway routes requests to.
- * @see https://vercel.com/docs/ai-gateway/models-and-providers/provider-options
- */
-export interface VercelGatewayRouting {
-    /** List of provider slugs to exclusively use for this request (e.g., ["bedrock", "anthropic"]). */
-    only?: string[];
-    /** List of provider slugs to try in order (e.g., ["anthropic", "openai"]). */
-    order?: string[];
-}
-export interface Model<TApi extends Api = any> {
-    id: string;
-    name: string;
-    api: TApi;
-    provider: Provider;
-    baseUrl: string;
-    reasoning: boolean;
-    input: ("text" | "image")[];
-    cost: {
-        input: number;
-        output: number;
-        cacheRead: number;
-        cacheWrite: number;
-    };
-    /** Premium Copilot requests charged per user-initiated request (defaults to 1). */
-    premiumMultiplier?: number;
-    contextWindow: number;
-    maxTokens: number;
-    /**
-     * When `true`, providers MUST omit `max_output_tokens` (Responses) /
-     * `max_tokens` / `max_completion_tokens` (Completions) from the outbound
-     * request and let the upstream API decide the per-response cap. `maxTokens`
-     * is still used locally for budgeting (compaction, context promotion); only
-     * the wire field is suppressed.
-     *
-     * Use this for proxies (notably Ollama) that forward to a backend whose true
-     * output limit Prometheus cannot discover — sending the wrong value triggers 400s
-     * from the upstream provider.
-     */
-    omitMaxOutputTokens?: boolean;
-    headers?: Record<string, string>;
-    /**
-     * Streaming transport override. When `"prometheus-native"`, `streamSimple` routes
-     * the request to the model's `baseUrl` via the auth-gateway's
-     * `POST /v1/prometheus/stream` endpoint instead of dispatching the per-API
-     * provider client. The `baseUrl` must point at an `prometheus auth-gateway`
-     * (or compatible) host; `headers.Authorization` (or `apiKey` resolved by
-     * the registry) carries the gateway bearer.
-     *
-     * Used by containerized prometheus installs (e.g. roboprometheus slots) to route every
-     * LLM call through a sidecar gateway that holds the real provider
-     * credentials. The model's other metadata (pricing, context window,
-     * thinking config, …) still resolves locally; only the streaming
-     * dispatch is redirected.
-     */
-    transport?: "prometheus-native";
-    /** Hint that websocket transport should be preferred when supported by the provider implementation. */
-    preferWebsockets?: boolean;
-    /** Preferred model to switch to when context promotion is triggered (model id or provider/id). */
-    contextPromotionTarget?: string;
-    /** Provider-assigned priority value (lower = higher priority). */
-    priority?: number;
-    /** Canonical thinking capability metadata for this model. */
-    thinking?: ThinkingConfig;
-    /** Compatibility overrides per API. If not set, auto-detected from baseUrl. */
-    compat?: TApi extends "openai-completions" | "openai-responses" ? OpenAICompat : TApi extends "anthropic-messages" ? AnthropicCompat : never;
-    /**
-     * Which shape to use when exposing the Codex `apply_patch` tool to this model.
-     * Generated catalog policy sets `"freeform"` for first-party GPT-5 Responses
-     * models that support OpenAI custom tools with a Lark grammar. The freeform
-     * variant sends a raw patch string with no JSON envelope.
-     * - `"function"` or undefined: JSON function-tool with `{input: string}` (spec §1.2).
-     */
-    applyPatchToolType?: "freeform" | "function";
-    /**
-     * Force OAuth-style request shaping for providers whose API key prefix doesn't
-     * match an OAuth token (e.g. routing Anthropic traffic through a proxy that
-     * expects Claude Code framing). When true, the streaming layer sets
-     * `options.isOAuth = true` for the underlying provider call.
-     */
-    isOAuth?: boolean;
-}

package/dist/types/usage/google-antigravity.d.ts

@@ -1,2 +1,16 @@
-import type { UsageProvider } from "../usage";
+import type { CredentialRankingStrategy, UsageProvider } from "../usage";
 export declare const antigravityUsageProvider: UsageProvider;
+/**
+ * Antigravity quotas reset daily and are returned per backend counter
+ * (Anthropic / Google / OpenAI) without a fixed "primary vs secondary"
+ * split. `fetchAntigravityUsage` already sorts `limits` ascending by
+ * `remainingFraction`; after model-family scoping, the most-pressured
+ * relevant counter is index 0.
+ *
+ * Leave `secondary` unset: AuthStorage compares secondary metrics before
+ * primary metrics, which is correct for providers with explicit long-window
+ * limits but wrong here. Ranking Antigravity by the bottleneck counter first
+ * avoids preferring an account at 95% Gemini / 0% Claude over one at
+ * 80% Gemini / 70% Claude.
+ */
+export declare const antigravityRankingStrategy: CredentialRankingStrategy;

package/dist/types/usage/openai-codex-reset.d.ts

@@ -0,0 +1,79 @@
+/**
+ * OpenAI Codex "saved rate limit reset" redemption client.
+ *
+ * OpenAI lets paid Codex accounts bank a usage-window reset and spend it on
+ * demand (announced 2026-06-11). The count is surfaced on `/wham/usage` as
+ * `rate_limit_reset_credits.available_count` (see `./openai-codex.ts`), but the
+ * actual credit objects and the redeem action live on two dedicated routes:
+ *
+ *   GET  /wham/rate-limit-reset-credits           → list redeemable credits
+ *   POST /wham/rate-limit-reset-credits/consume   → spend one credit
+ *        body: { credit_id, redeem_request_id }
+ *
+ * `redeem_request_id` is a client-generated idempotency key (UUID). The consume
+ * response carries a `code`: `"reset"` on success, otherwise a business reason
+ * (`already_redeemed`, `no_credit`, `nothing_to_reset`).
+ *
+ * These are thin, dependency-light functions so both the interactive session
+ * (the `/usage reset` command + auto-redeem) and any out-of-band tooling can
+ * share one wire contract.
+ */
+import type { FetchImpl } from "../types";
+/** A single redeemable (or already-spent) saved reset. */
+export interface CodexResetCredit {
+    /** Opaque credit id, e.g. `RateLimitResetCredit_…`. Pass to {@link consumeCodexResetCredit}. */
+    id: string;
+    /** Backend reset family, e.g. `codex_rate_limits`. */
+    resetType?: string;
+    /** `available`, `redeemed`, … */
+    status?: string;
+    grantedAt?: string;
+    expiresAt?: string;
+    redeemStartedAt?: string | null;
+    redeemedAt?: string | null;
+    /** Human-facing card title, e.g. "One free rate limit reset". */
+    title?: string;
+    description?: string;
+}
+/** Result of listing an account's saved resets. */
+export interface CodexResetCreditList {
+    credits: CodexResetCredit[];
+    /** Backend-reported count of credits redeemable right now. */
+    availableCount: number;
+}
+/**
+ * Consume outcome `code`. `reset` means a window was actually reset; the others
+ * are no-op business outcomes the caller should surface verbatim-ish to the user.
+ */
+export type CodexResetConsumeCode = "reset" | "already_redeemed" | "no_credit" | "nothing_to_reset" | (string & {});
+export interface CodexResetConsumeResult {
+    /** `true` only when `code === "reset"` (a reset was applied). */
+    ok: boolean;
+    code: CodexResetConsumeCode;
+    /** HTTP status of the consume call (for diagnostics). */
+    status: number;
+    raw?: unknown;
+}
+interface CodexResetAuth {
+    accessToken: string;
+    accountId?: string;
+    /** Provider base URL override; defaults to the Codex backend. */
+    baseUrl?: string;
+    fetch: FetchImpl;
+    signal?: AbortSignal;
+}
+/**
+ * List the account's saved rate-limit resets. Returns `null` on transport/auth
+ * failure (non-2xx or thrown), letting callers treat it the same as "no data".
+ */
+export declare function listCodexResetCredits(auth: CodexResetAuth): Promise<CodexResetCreditList | null>;
+/**
+ * Spend one saved reset. `redeemRequestId` is the idempotency key; one is
+ * generated when omitted, so retrying with the SAME id is safe and won't
+ * double-spend. The returned `code` is `"reset"` on success.
+ */
+export declare function consumeCodexResetCredit(auth: CodexResetAuth & {
+    creditId: string;
+    redeemRequestId?: string;
+}): Promise<CodexResetConsumeResult>;
+export {};

package/dist/types/usage/openai-codex.d.ts

@@ -1,3 +1,4 @@
 import type { CredentialRankingStrategy, UsageProvider } from "../usage";
+export declare function normalizeCodexBaseUrl(baseUrl?: string): string;
 export declare const openaiCodexUsageProvider: UsageProvider;
 export declare const codexRankingStrategy: CredentialRankingStrategy;

package/dist/types/usage.d.ts

@@ -4,8 +4,8 @@
  * Provides a normalized schema to represent multiple limit windows, model tiers,
  * and shared quotas across providers.
  */
-import * as z from "zod/v4";
-import type { Provider } from "./types";
+import { z } from "zod/v4";
+import type { FetchImpl, Provider } from "./types";
 export type UsageUnit = "percent" | "tokens" | "requests" | "usd" | "minutes" | "bytes" | "unknown";
 export type UsageStatus = "ok" | "warning" | "exhausted" | "unknown";
 /** Time window for a limit (e.g. 5h, 7d, monthly). */
@@ -57,14 +57,64 @@ export interface UsageLimit {
     status?: UsageStatus;
     notes?: string[];
 }
+/**
+ * Saved/banked rate-limit resets an account can redeem on demand.
+ *
+ * Surfaced by providers that let users defer a usage-window reset and spend it
+ * later (OpenAI Codex "saved rate limit resets"). The redeem itself is a
+ * separate, provider-specific action; this is the read-only count for display.
+ */
+export interface UsageResetCredits {
+    /** Number of resets available to redeem right now. */
+    availableCount: number;
+}
 /** Aggregated usage report for a provider. */
 export interface UsageReport {
     provider: Provider;
     fetchedAt: number;
     limits: UsageLimit[];
+    /** Saved rate-limit resets the account can redeem, when the provider reports them. */
+    resetCredits?: UsageResetCredits;
     metadata?: Record<string, unknown>;
     raw?: unknown;
 }
+/**
+ * Resolve a limit's used fraction (0..1; >1 means overage) from whichever
+ * amount fields the provider populated. Precedence mirrors the usage UIs:
+ * explicit fraction > used/limit > percent-unit used > inverted remaining.
+ */
+export declare function resolveUsedFraction(limit: UsageLimit): number | undefined;
+/**
+ * One recorded usage-limit snapshot: a single limit window of one account at
+ * a point in time. The usage cache itself is latest-snapshot-only; history
+ * rows are appended by the auth storage layer whenever a fresh report is
+ * fetched, so limit utilization stays inspectable over time.
+ */
+export interface UsageHistoryEntry {
+    /** Epoch ms the report was fetched. */
+    recordedAt: number;
+    provider: Provider;
+    /** Stable credential identity key (account/email/project derived). */
+    accountKey: string;
+    email?: string;
+    accountId?: string;
+    /** {@link UsageLimit.id} of the recorded window. */
+    limitId: string;
+    /** Human label of the limit. */
+    label: string;
+    windowLabel?: string;
+    /** Used fraction (0..1) when resolvable. */
+    usedFraction?: number;
+    status?: UsageStatus;
+    /** Epoch ms the window resets, when known. */
+    resetsAt?: number;
+}
+/** Filter for reading recorded usage history. */
+export interface UsageHistoryQuery {
+    provider?: string;
+    /** Inclusive lower bound on {@link UsageHistoryEntry.recordedAt} (epoch ms). */
+    sinceMs?: number;
+}
 export declare const usageUnitSchema: z.ZodEnum<{
     bytes: "bytes";
     minutes: "minutes";
@@ -155,6 +205,9 @@ export declare const usageLimitSchema: z.ZodObject<{
     }>>;
     notes: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
+export declare const usageResetCreditsSchema: z.ZodObject<{
+    availableCount: z.ZodNumber;
+}, z.core.$strip>;
 export declare const usageReportSchema: z.ZodObject<{
     provider: z.ZodString;
     fetchedAt: z.ZodNumber;
@@ -201,6 +254,9 @@ export declare const usageReportSchema: 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>;
@@ -231,7 +287,7 @@ export interface UsageFetchParams {
 }
 /** Shared runtime utilities for fetchers. */
 export interface UsageFetchContext {
-    fetch: typeof fetch;
+    fetch: FetchImpl;
     logger?: UsageLogger;
     retryWait?: (delayMs: number, signal?: AbortSignal) => Promise<void>;
 }
@@ -243,13 +299,30 @@ export interface UsageProvider {
     parseRateLimitHeaders?(headers: Record<string, string>, now?: number): UsageReport | null;
     supports?(params: UsageFetchParams): boolean;
 }
+/** Request context used when ranking usage for a specific model. */
+export interface CredentialRankingContext {
+    /** Provider model id, when the caller is selecting a credential for one model. */
+    modelId?: string;
+}
 /** Strategy for usage-based credential ranking. Providers implement this to opt into smart credential selection. */
 export interface CredentialRankingStrategy {
     /** Extract the primary (short) and secondary (long) window limits from a usage report. */
-    findWindowLimits(report: UsageReport): {
+    findWindowLimits(report: UsageReport, context?: CredentialRankingContext): {
         primary?: UsageLimit;
         secondary?: UsageLimit;
     };
+    /**
+     * Restrict limits to the ones relevant for the requested model before
+     * credential-wide exhaustion checks and ranking. Providers with shared
+     * account-wide quotas can omit this and use all limits.
+     */
+    scopeLimits?(report: UsageReport, context?: CredentialRankingContext): UsageLimit[];
+    /**
+     * Return a provider-local backoff scope for the requested model. Providers
+     * with backend-specific quotas use this so one exhausted model family does
+     * not block unrelated families on the same OAuth credential.
+     */
+    blockScope?(context?: CredentialRankingContext): string | undefined;
     /** Fallback window durations (ms) when limits don't specify durationMs. */
     windowDefaults: {
         primaryMs: number;