@jaypie/llm 1.3.14 → 1.3.16

package/dist/cjs/index.d.cts

@@ -52,6 +52,61 @@ declare const MODEL: {
         SONNET: string;
     };
 };
+/** Price of one million tokens, in US dollars. */
+interface LlmModelCost {
+    /**
+     * Cache-read (cached input) tokens. Omitted when the provider does not price
+     * cache reads separately from uncached input.
+     */
+    cachedInputRead?: number;
+    /**
+     * Cache-write tokens. A scalar when the rate does not vary by TTL; keyed by
+     * the same `"5m"` / `"1h"` literals as `LlmCache` when it does, so a cost
+     * calculation reads the TTL straight off `OperateRequest.cache`. Omitted
+     * means cache writes bill at the `input` rate.
+     */
+    cachedInputWrite?: number | {
+        "1h": number;
+        "5m": number;
+    };
+    /** Uncached input tokens. */
+    input: number;
+    /** Output tokens. */
+    output: number;
+    /**
+     * Reasoning tokens, when billed at a rate other than `output`. Omitted means
+     * reasoning bills as output, which is true of every provider listed here.
+     */
+    reasoning?: number;
+}
+/**
+ * Standard list price per million tokens, keyed by literal model id (verified
+ * 2026-07-21). Keys are string literals rather than `MODEL.*` references so a
+ * model retired from the catalog keeps its price here: historic ids stay
+ * priceable after they leave `MODEL.*`, which is what makes replaying old
+ * usage records possible.
+ *
+ * Caveats the numbers cannot carry:
+ * - **Standard rate only.** Introductory, batch, flex, priority, fast-mode, and
+ *   data-residency rates are excluded. Sonnet 5 is listed at its standard
+ *   $3/$15, not the introductory rate.
+ * - **Cache writes are Anthropic-only.** Fireworks writes bill at the input
+ *   rate. OpenAI and xAI discount reads automatically and publish no write
+ *   premium. Google charges nothing to write an implicit cache; explicit
+ *   caching bills storage per hour, a unit this table does not carry (and one
+ *   `@jaypie/llm` does not wire).
+ * - **Short-context tier.** Long-prompt surcharges are not modeled: Gemini 3.1
+ *   Pro doubles above 200K, Grok doubles at 200K, GPT-5.5 is 2x in / 1.5x out
+ *   above 272K.
+ * - **Text rates.** Gemini prices audio input higher than text/image/video.
+ * - **Proxies are deliberately absent.** Bedrock (`PROVIDER.BEDROCK.*`) and
+ *   OpenRouter (`MODEL.OPENROUTER.*`) resell many vendors and price per backend
+ *   route, so no single rate is correct for a proxy id. Price those against the
+ *   backend model, or against the proxy's own published rate.
+ *
+ * Unlisted ids return `undefined` — callers must handle a miss.
+ */
+declare const COST: Record<string, LlmModelCost>;
 declare const PROVIDER: {
     readonly BEDROCK: {
         readonly DEFAULT: "amazon.nova-pro-v1:0";
@@ -206,22 +261,24 @@ declare const DEFAULT: {
  */
 declare const ALL: {
     readonly BASE: readonly ["claude-sonnet-4-6", "gemini-3.1-pro-preview", "gpt-5.4", "grok-latest"];
-    readonly COMBINED: readonly ("claude-opus-4-8" | "claude-haiku-4-5" | "gemini-3.5-flash" | "gemini-3.1-flash-lite" | "gemini-3.1-pro-preview" | "gpt-5.5" | "gpt-5.4-mini" | "gpt-5.4-nano" | "grok-latest" | "claude-sonnet-4-6" | "gpt-5.4" | "grok-4-1-fast-reasoning" | "grok-4-1-fast-non-reasoning")[];
+    readonly COMBINED: readonly ("claude-opus-4-8" | "claude-haiku-4-5" | "gemini-3.1-pro-preview" | "gpt-5.5" | "gpt-5.4-mini" | "gpt-5.4-nano" | "grok-latest" | "claude-sonnet-4-6" | "gemini-3.5-flash" | "gemini-3.1-flash-lite" | "gpt-5.4" | "grok-4-1-fast-reasoning" | "grok-4-1-fast-non-reasoning")[];
     readonly LARGE: readonly ["claude-opus-4-8", "gemini-3.1-pro-preview", "gpt-5.5", "grok-latest"];
     readonly SMALL: readonly ["claude-sonnet-4-6", "gemini-3.5-flash", "gpt-5.4-mini", "grok-4-1-fast-reasoning"];
     readonly TINY: readonly ["claude-haiku-4-5", "gemini-3.1-flash-lite", "gpt-5.4-nano", "grok-4-1-fast-non-reasoning"];
 };
 
 declare const constants_ALL: typeof ALL;
+declare const constants_COST: typeof COST;
 declare const constants_DEFAULT: typeof DEFAULT;
 declare const constants_EFFORT: typeof EFFORT;
 type constants_LlmEffort = LlmEffort;
+type constants_LlmModelCost = LlmModelCost;
 type constants_LlmProviderName = LlmProviderName;
 declare const constants_MODEL: typeof MODEL;
 declare const constants_PROVIDER: typeof PROVIDER;
 declare namespace constants {
-  export { constants_ALL as ALL, constants_DEFAULT as DEFAULT, constants_EFFORT as EFFORT, constants_MODEL as MODEL, constants_PROVIDER as PROVIDER };
-  export type { constants_LlmEffort as LlmEffort, constants_LlmProviderName as LlmProviderName };
+  export { constants_ALL as ALL, constants_COST as COST, constants_DEFAULT as DEFAULT, constants_EFFORT as EFFORT, constants_MODEL as MODEL, constants_PROVIDER as PROVIDER };
+  export type { constants_LlmEffort as LlmEffort, constants_LlmModelCost as LlmModelCost, constants_LlmProviderName as LlmProviderName };
 }
 
 interface LlmTool {
@@ -530,6 +587,7 @@ type LlmProgressCallback = (event: LlmProgressEvent) => unknown | Promise<unknow
  * `input` is the raw, pre-interpolation input with multimodal parts preserved.
  */
 interface LlmExchangeRequest {
+    cache?: LlmCache;
     data?: NaturalMap;
     effort?: LlmEffort;
     explain?: boolean;
@@ -600,7 +658,21 @@ interface LlmExchangeEnvelope {
     timing: LlmExchangeTiming;
 }
 type LlmExchangeCallback = (envelope: LlmExchangeEnvelope) => unknown | Promise<unknown>;
+/**
+ * Prompt-caching control for operate()/stream().
+ * - `true` / omitted → caching enabled at the default `"5m"` TTL
+ * - `false` / `0` → caching disabled
+ * - `"5m"` / `"1h"` → enabled at that TTL (TTL honored by Anthropic/OpenRouter;
+ *   other providers ignore it and cache with their own defaults)
+ */
+type LlmCache = boolean | 0 | "5m" | "1h";
 interface LlmOperateOptions {
+    /**
+     * Prompt caching for the stable request prefix (system prompt + tools).
+     * Enabled by default; pass `false`/`0` to opt out, or `"5m"`/`"1h"` to set
+     * the TTL. See {@link LlmCache}.
+     */
+    cache?: LlmCache;
     data?: NaturalMap;
     /**
      * Provider-neutral reasoning effort (lowest | low | medium | high | highest).
@@ -709,6 +781,10 @@ interface LlmUsageItem {
     output: number;
     reasoning: number;
     total: number;
+    /** Prompt-cache tokens served from cache this call (billed at ~0.1x input) */
+    cacheRead?: number;
+    /** Prompt-cache tokens written to cache this call (billed at ~1.25x input) */
+    cacheWrite?: number;
     provider?: string;
     model?: string;
 }
@@ -1023,4 +1099,4 @@ declare class XaiProvider implements LlmProvider {
 }
 
 export { BedrockProvider, ErrorCategory, FireworksProvider, GoogleProvider as GeminiProvider, GoogleProvider, JaypieToolkit, constants as LLM, Llm, LlmError, LlmMessageRole, LlmMessageType, LlmProgressEventType, LlmQuotaError, LlmRateLimitError, LlmStreamChunkType, LlmTransientError, LlmUnrecoverableError, OpenRouterProvider, Toolkit, XaiProvider, extractReasoning, isLlmOperateInput, isLlmOperateInputContent, isLlmOperateInputFile, isLlmOperateInputImage, jsonSchemaToNaturalSchema, naturalSchemaToJsonSchema, toolkit, tools };
-export type { LlmEffort, LlmErrorOptions, LlmExchangeCallback, LlmExchangeEnvelope, LlmExchangeRequest, LlmExchangeResolution, LlmExchangeResponse, LlmExchangeTiming, LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmModelOption, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProgressCallback, LlmProgressEvent, LlmProgressToolCall, LlmProvider, LlmStreamChunk, LlmStreamChunkDone, LlmStreamChunkError, LlmStreamChunkText, LlmStreamChunkToolCall, LlmStreamChunkToolResult, LlmTool };
+export type { LlmCache, LlmEffort, LlmErrorOptions, LlmExchangeCallback, LlmExchangeEnvelope, LlmExchangeRequest, LlmExchangeResolution, LlmExchangeResponse, LlmExchangeTiming, LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmModelCost, LlmModelOption, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProgressCallback, LlmProgressEvent, LlmProgressToolCall, LlmProvider, LlmStreamChunk, LlmStreamChunkDone, LlmStreamChunkError, LlmStreamChunkText, LlmStreamChunkToolCall, LlmStreamChunkToolResult, LlmTool };

package/dist/cjs/index.d.ts

@@ -1,7 +1,7 @@
 export { default as Llm } from "./Llm.js";
 export * as LLM from "./constants.js";
-export type { LlmEffort } from "./constants.js";
-export type { LlmExchangeCallback, LlmExchangeEnvelope, LlmExchangeRequest, LlmExchangeResolution, LlmExchangeResponse, LlmExchangeTiming, LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmModelOption, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProgressCallback, LlmProgressEvent, LlmProgressToolCall, LlmProvider, } from "./types/LlmProvider.interface.js";
+export type { LlmEffort, LlmModelCost } from "./constants.js";
+export type { LlmCache, LlmExchangeCallback, LlmExchangeEnvelope, LlmExchangeRequest, LlmExchangeResolution, LlmExchangeResponse, LlmExchangeTiming, LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmModelOption, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProgressCallback, LlmProgressEvent, LlmProgressToolCall, LlmProvider, } from "./types/LlmProvider.interface.js";
 export { LlmMessageRole, LlmMessageType, LlmProgressEventType, } from "./types/LlmProvider.interface.js";
 export { isLlmOperateInput, isLlmOperateInputContent, isLlmOperateInputFile, isLlmOperateInputImage, } from "./types/LlmOperateInput.guards.js";
 export type { LlmTool } from "./types/LlmTool.interface.js";

package/dist/cjs/operate/adapters/BedrockAdapter.d.ts

@@ -47,16 +47,24 @@ type BedrockRequest = Omit<ConverseCommandInput, "messages"> & {
 type AnnotatedBedrockResponse = ConverseCommandOutput & {
     __jaypieStructuredOutput?: boolean;
 };
+/** Exported for tests; not part of the package's public surface. */
+export declare function isCachePointUnsupportedError(error: unknown): boolean;
 export declare class BedrockAdapter extends BaseProviderAdapter {
     readonly name: "bedrock";
     readonly defaultModel: "amazon.nova-pro-v1:0";
     private _modelsFallbackToStructuredOutputTool;
     private _modelsWithoutTemperature;
+    private _modelsWithoutCachePoint;
+    private rememberModelRejectsCachePoint;
+    private supportsCachePoint;
     private rememberModelRejectsOutputConfig;
     private useFakeToolForStructuredOutput;
     private rememberModelRejectsTemperature;
     private supportsTemperature;
     buildRequest(request: OperateRequest): BedrockRequest;
+    /** Remove any cachePoint blocks so the request can be retried unsupported. */
+    private stripCachePoints;
+    private requestHasCachePoints;
     formatTools(toolkit: Toolkit): ProviderToolDefinition[];
     formatOutputSchema(schema: JsonObject | NaturalSchema | z.ZodType): JsonObject;
     executeRequest(client: unknown, request: unknown, signal?: AbortSignal): Promise<AnnotatedBedrockResponse>;

package/dist/cjs/operate/adapters/OpenAiAdapter.d.ts

@@ -21,6 +21,11 @@ export declare class OpenAiAdapter extends BaseProviderAdapter {
     private supportsTemperature;
     /** Whether `reasoning.effort` may be sent for this model. Overridden by xAI. */
     protected supportsReasoningEffort(model: string): boolean;
+    /**
+     * Whether to emit `prompt_cache_key` (OpenAI Responses API). Overridable by
+     * OpenAI-compatible subclasses whose backend rejects the field.
+     */
+    protected supportsPromptCacheKey(): boolean;
     /** Translate a normalized effort to this provider's `reasoning.effort` value. */
     protected mapReasoningEffort(effort: LlmEffort, model: string): LlmEffortMapping;
     buildRequest(request: OperateRequest): unknown;

package/dist/cjs/operate/adapters/OpenRouterAdapter.d.ts

@@ -42,6 +42,13 @@ interface OpenRouterUsage {
     completionTokensDetails?: {
         reasoningTokens?: number;
     };
+    promptTokensDetails?: {
+        cachedTokens?: number;
+        cached_tokens?: number;
+    };
+    prompt_tokens_details?: {
+        cached_tokens?: number;
+    };
 }
 interface OpenRouterResponse {
     id: string;
@@ -95,6 +102,10 @@ interface OpenRouterRequest {
 type OpenRouterContentPart = {
     type: "text";
     text: string;
+    cache_control?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h";
+    };
 } | {
     type: "image_url";
     imageUrl: {

package/dist/cjs/operate/types.d.ts

@@ -1,6 +1,6 @@
 import { JsonObject } from "@jaypie/types";
 import { type LlmEffort } from "../constants.js";
-import { LlmHistory, LlmMessageType, LlmOperateOptions, LlmUsageItem } from "../types/LlmProvider.interface.js";
+import { LlmCache, LlmHistory, LlmMessageType, LlmOperateOptions, LlmUsageItem } from "../types/LlmProvider.interface.js";
 import { Toolkit } from "../tools/Toolkit.class.js";
 /**
  * Standardized tool call representation across providers
@@ -73,6 +73,11 @@ export interface OperateRequest {
     effort?: LlmEffort;
     /** Provider-specific options */
     providerOptions?: JsonObject;
+    /**
+     * Prompt-caching control for the stable prefix (system + tools). `true`/
+     * omitted = enabled@5m, `false`/`0` = disabled, `"5m"`/`"1h"` = enabled@ttl.
+     */
+    cache?: LlmCache;
     /** Whether the request will execute over a streaming transport */
     stream?: boolean;
     /** Sampling temperature (0-2 for most providers) */

package/dist/cjs/providers/anthropic/types.d.ts

@@ -2,10 +2,20 @@ import { JsonObject } from "@jaypie/types";
 import { LlmMessageRole } from "../../types/LlmProvider.interface.js";
 export declare const ROLE_MAP: Record<LlmMessageRole, string>;
 export declare namespace Anthropic {
+    interface CacheControlEphemeral {
+        type: "ephemeral";
+        ttl?: "5m" | "1h";
+    }
     interface TextBlock {
         type: "text";
         text: string;
     }
+    /** Top-level `system` block form that can carry a cache breakpoint */
+    interface SystemTextBlockParam {
+        type: "text";
+        text: string;
+        cache_control?: CacheControlEphemeral;
+    }
     interface ToolUseBlock {
         type: "tool_use";
         id: string;
@@ -63,17 +73,20 @@ export declare namespace Anthropic {
         description?: string;
         input_schema: Messages.Tool.InputSchema;
         type?: "custom";
+        cache_control?: CacheControlEphemeral;
     }
     interface Usage {
         input_tokens: number;
         output_tokens: number;
         thinking_tokens?: number;
+        cache_read_input_tokens?: number;
+        cache_creation_input_tokens?: number;
     }
     interface MessageCreateParams {
         model: string;
         messages: MessageParam[];
         max_tokens: number;
-        system?: string;
+        system?: string | SystemTextBlockParam[];
         tools?: Tool[];
         tool_choice?: {
             type: "auto" | "any" | "tool";

package/dist/cjs/types/LlmProvider.interface.d.ts

@@ -217,6 +217,7 @@ export type LlmProgressCallback = (event: LlmProgressEvent) => unknown | Promise
  * `input` is the raw, pre-interpolation input with multimodal parts preserved.
  */
 export interface LlmExchangeRequest {
+    cache?: LlmCache;
     data?: NaturalMap;
     effort?: LlmEffort;
     explain?: boolean;
@@ -287,7 +288,21 @@ export interface LlmExchangeEnvelope {
     timing: LlmExchangeTiming;
 }
 export type LlmExchangeCallback = (envelope: LlmExchangeEnvelope) => unknown | Promise<unknown>;
+/**
+ * Prompt-caching control for operate()/stream().
+ * - `true` / omitted → caching enabled at the default `"5m"` TTL
+ * - `false` / `0` → caching disabled
+ * - `"5m"` / `"1h"` → enabled at that TTL (TTL honored by Anthropic/OpenRouter;
+ *   other providers ignore it and cache with their own defaults)
+ */
+export type LlmCache = boolean | 0 | "5m" | "1h";
 export interface LlmOperateOptions {
+    /**
+     * Prompt caching for the stable request prefix (system prompt + tools).
+     * Enabled by default; pass `false`/`0` to opt out, or `"5m"`/`"1h"` to set
+     * the TTL. See {@link LlmCache}.
+     */
+    cache?: LlmCache;
     data?: NaturalMap;
     /**
      * Provider-neutral reasoning effort (lowest | low | medium | high | highest).
@@ -396,6 +411,10 @@ export interface LlmUsageItem {
     output: number;
     reasoning: number;
     total: number;
+    /** Prompt-cache tokens served from cache this call (billed at ~0.1x input) */
+    cacheRead?: number;
+    /** Prompt-cache tokens written to cache this call (billed at ~1.25x input) */
+    cacheWrite?: number;
     provider?: string;
     model?: string;
 }

package/dist/cjs/util/cacheControl.d.ts

@@ -0,0 +1,21 @@
+import { type LlmCache } from "../types/LlmProvider.interface.js";
+export declare const CACHE_TTL_DEFAULT: "5m";
+export type CacheTtl = "5m" | "1h";
+export interface ResolvedCache {
+    enabled: boolean;
+    ttl: CacheTtl;
+}
+/**
+ * Normalize the caller-facing `cache` option into a concrete decision.
+ * - `undefined` / `true` → enabled at the default TTL
+ * - `false` / `0` → disabled
+ * - `"5m"` / `"1h"` → enabled at that TTL
+ */
+export declare function resolveCache(cache: LlmCache | undefined): ResolvedCache;
+/**
+ * Deterministic short key for providers with automatic, prefix-based caching
+ * (e.g. OpenAI `prompt_cache_key`). Derived from the stable prefix so the same
+ * system prompt + tools + model always routes to the same cache. Dependency-
+ * free FNV-1a; not cryptographic.
+ */
+export declare function promptCacheKey(seed: string): string;

package/dist/cjs/util/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./cacheControl.js";
 export * from "./determineModelProvider.js";
 export * from "./extractReasoning.js";
 export * from "./fillFormatArrays.js";

package/dist/esm/constants.d.ts

@@ -47,6 +47,61 @@ export declare const MODEL: {
         SONNET: string;
     };
 };
+/** Price of one million tokens, in US dollars. */
+export interface LlmModelCost {
+    /**
+     * Cache-read (cached input) tokens. Omitted when the provider does not price
+     * cache reads separately from uncached input.
+     */
+    cachedInputRead?: number;
+    /**
+     * Cache-write tokens. A scalar when the rate does not vary by TTL; keyed by
+     * the same `"5m"` / `"1h"` literals as `LlmCache` when it does, so a cost
+     * calculation reads the TTL straight off `OperateRequest.cache`. Omitted
+     * means cache writes bill at the `input` rate.
+     */
+    cachedInputWrite?: number | {
+        "1h": number;
+        "5m": number;
+    };
+    /** Uncached input tokens. */
+    input: number;
+    /** Output tokens. */
+    output: number;
+    /**
+     * Reasoning tokens, when billed at a rate other than `output`. Omitted means
+     * reasoning bills as output, which is true of every provider listed here.
+     */
+    reasoning?: number;
+}
+/**
+ * Standard list price per million tokens, keyed by literal model id (verified
+ * 2026-07-21). Keys are string literals rather than `MODEL.*` references so a
+ * model retired from the catalog keeps its price here: historic ids stay
+ * priceable after they leave `MODEL.*`, which is what makes replaying old
+ * usage records possible.
+ *
+ * Caveats the numbers cannot carry:
+ * - **Standard rate only.** Introductory, batch, flex, priority, fast-mode, and
+ *   data-residency rates are excluded. Sonnet 5 is listed at its standard
+ *   $3/$15, not the introductory rate.
+ * - **Cache writes are Anthropic-only.** Fireworks writes bill at the input
+ *   rate. OpenAI and xAI discount reads automatically and publish no write
+ *   premium. Google charges nothing to write an implicit cache; explicit
+ *   caching bills storage per hour, a unit this table does not carry (and one
+ *   `@jaypie/llm` does not wire).
+ * - **Short-context tier.** Long-prompt surcharges are not modeled: Gemini 3.1
+ *   Pro doubles above 200K, Grok doubles at 200K, GPT-5.5 is 2x in / 1.5x out
+ *   above 272K.
+ * - **Text rates.** Gemini prices audio input higher than text/image/video.
+ * - **Proxies are deliberately absent.** Bedrock (`PROVIDER.BEDROCK.*`) and
+ *   OpenRouter (`MODEL.OPENROUTER.*`) resell many vendors and price per backend
+ *   route, so no single rate is correct for a proxy id. Price those against the
+ *   backend model, or against the proxy's own published rate.
+ *
+ * Unlisted ids return `undefined` — callers must handle a miss.
+ */
+export declare const COST: Record<string, LlmModelCost>;
 export declare const PROVIDER: {
     readonly BEDROCK: {
         readonly DEFAULT: "amazon.nova-pro-v1:0";
@@ -201,7 +256,7 @@ export declare const DEFAULT: {
  */
 export declare const ALL: {
     readonly BASE: readonly ["claude-sonnet-4-6", "gemini-3.1-pro-preview", "gpt-5.4", "grok-latest"];
-    readonly COMBINED: readonly ("claude-opus-4-8" | "claude-haiku-4-5" | "gemini-3.5-flash" | "gemini-3.1-flash-lite" | "gemini-3.1-pro-preview" | "gpt-5.5" | "gpt-5.4-mini" | "gpt-5.4-nano" | "grok-latest" | "claude-sonnet-4-6" | "gpt-5.4" | "grok-4-1-fast-reasoning" | "grok-4-1-fast-non-reasoning")[];
+    readonly COMBINED: readonly ("claude-opus-4-8" | "claude-haiku-4-5" | "gemini-3.1-pro-preview" | "gpt-5.5" | "gpt-5.4-mini" | "gpt-5.4-nano" | "grok-latest" | "claude-sonnet-4-6" | "gemini-3.1-flash-lite" | "gemini-3.5-flash" | "gpt-5.4" | "grok-4-1-fast-non-reasoning" | "grok-4-1-fast-reasoning")[];
     readonly LARGE: readonly ["claude-opus-4-8", "gemini-3.1-pro-preview", "gpt-5.5", "grok-latest"];
     readonly SMALL: readonly ["claude-sonnet-4-6", "gemini-3.5-flash", "gpt-5.4-mini", "grok-4-1-fast-reasoning"];
     readonly TINY: readonly ["claude-haiku-4-5", "gemini-3.1-flash-lite", "gpt-5.4-nano", "grok-4-1-fast-non-reasoning"];

package/dist/esm/index.d.ts

@@ -52,6 +52,61 @@ declare const MODEL: {
         SONNET: string;
     };
 };
+/** Price of one million tokens, in US dollars. */
+interface LlmModelCost {
+    /**
+     * Cache-read (cached input) tokens. Omitted when the provider does not price
+     * cache reads separately from uncached input.
+     */
+    cachedInputRead?: number;
+    /**
+     * Cache-write tokens. A scalar when the rate does not vary by TTL; keyed by
+     * the same `"5m"` / `"1h"` literals as `LlmCache` when it does, so a cost
+     * calculation reads the TTL straight off `OperateRequest.cache`. Omitted
+     * means cache writes bill at the `input` rate.
+     */
+    cachedInputWrite?: number | {
+        "1h": number;
+        "5m": number;
+    };
+    /** Uncached input tokens. */
+    input: number;
+    /** Output tokens. */
+    output: number;
+    /**
+     * Reasoning tokens, when billed at a rate other than `output`. Omitted means
+     * reasoning bills as output, which is true of every provider listed here.
+     */
+    reasoning?: number;
+}
+/**
+ * Standard list price per million tokens, keyed by literal model id (verified
+ * 2026-07-21). Keys are string literals rather than `MODEL.*` references so a
+ * model retired from the catalog keeps its price here: historic ids stay
+ * priceable after they leave `MODEL.*`, which is what makes replaying old
+ * usage records possible.
+ *
+ * Caveats the numbers cannot carry:
+ * - **Standard rate only.** Introductory, batch, flex, priority, fast-mode, and
+ *   data-residency rates are excluded. Sonnet 5 is listed at its standard
+ *   $3/$15, not the introductory rate.
+ * - **Cache writes are Anthropic-only.** Fireworks writes bill at the input
+ *   rate. OpenAI and xAI discount reads automatically and publish no write
+ *   premium. Google charges nothing to write an implicit cache; explicit
+ *   caching bills storage per hour, a unit this table does not carry (and one
+ *   `@jaypie/llm` does not wire).
+ * - **Short-context tier.** Long-prompt surcharges are not modeled: Gemini 3.1
+ *   Pro doubles above 200K, Grok doubles at 200K, GPT-5.5 is 2x in / 1.5x out
+ *   above 272K.
+ * - **Text rates.** Gemini prices audio input higher than text/image/video.
+ * - **Proxies are deliberately absent.** Bedrock (`PROVIDER.BEDROCK.*`) and
+ *   OpenRouter (`MODEL.OPENROUTER.*`) resell many vendors and price per backend
+ *   route, so no single rate is correct for a proxy id. Price those against the
+ *   backend model, or against the proxy's own published rate.
+ *
+ * Unlisted ids return `undefined` — callers must handle a miss.
+ */
+declare const COST: Record<string, LlmModelCost>;
 declare const PROVIDER: {
     readonly BEDROCK: {
         readonly DEFAULT: "amazon.nova-pro-v1:0";
@@ -206,22 +261,24 @@ declare const DEFAULT: {
  */
 declare const ALL: {
     readonly BASE: readonly ["claude-sonnet-4-6", "gemini-3.1-pro-preview", "gpt-5.4", "grok-latest"];
-    readonly COMBINED: readonly ("claude-opus-4-8" | "claude-haiku-4-5" | "gemini-3.5-flash" | "gemini-3.1-flash-lite" | "gemini-3.1-pro-preview" | "gpt-5.5" | "gpt-5.4-mini" | "gpt-5.4-nano" | "grok-latest" | "claude-sonnet-4-6" | "gpt-5.4" | "grok-4-1-fast-reasoning" | "grok-4-1-fast-non-reasoning")[];
+    readonly COMBINED: readonly ("claude-opus-4-8" | "claude-haiku-4-5" | "gemini-3.1-pro-preview" | "gpt-5.5" | "gpt-5.4-mini" | "gpt-5.4-nano" | "grok-latest" | "claude-sonnet-4-6" | "gemini-3.5-flash" | "gemini-3.1-flash-lite" | "gpt-5.4" | "grok-4-1-fast-reasoning" | "grok-4-1-fast-non-reasoning")[];
     readonly LARGE: readonly ["claude-opus-4-8", "gemini-3.1-pro-preview", "gpt-5.5", "grok-latest"];
     readonly SMALL: readonly ["claude-sonnet-4-6", "gemini-3.5-flash", "gpt-5.4-mini", "grok-4-1-fast-reasoning"];
     readonly TINY: readonly ["claude-haiku-4-5", "gemini-3.1-flash-lite", "gpt-5.4-nano", "grok-4-1-fast-non-reasoning"];
 };
 
 declare const constants_ALL: typeof ALL;
+declare const constants_COST: typeof COST;
 declare const constants_DEFAULT: typeof DEFAULT;
 declare const constants_EFFORT: typeof EFFORT;
 type constants_LlmEffort = LlmEffort;
+type constants_LlmModelCost = LlmModelCost;
 type constants_LlmProviderName = LlmProviderName;
 declare const constants_MODEL: typeof MODEL;
 declare const constants_PROVIDER: typeof PROVIDER;
 declare namespace constants {
-  export { constants_ALL as ALL, constants_DEFAULT as DEFAULT, constants_EFFORT as EFFORT, constants_MODEL as MODEL, constants_PROVIDER as PROVIDER };
-  export type { constants_LlmEffort as LlmEffort, constants_LlmProviderName as LlmProviderName };
+  export { constants_ALL as ALL, constants_COST as COST, constants_DEFAULT as DEFAULT, constants_EFFORT as EFFORT, constants_MODEL as MODEL, constants_PROVIDER as PROVIDER };
+  export type { constants_LlmEffort as LlmEffort, constants_LlmModelCost as LlmModelCost, constants_LlmProviderName as LlmProviderName };
 }
 
 interface LlmTool {
@@ -530,6 +587,7 @@ type LlmProgressCallback = (event: LlmProgressEvent) => unknown | Promise<unknow
  * `input` is the raw, pre-interpolation input with multimodal parts preserved.
  */
 interface LlmExchangeRequest {
+    cache?: LlmCache;
     data?: NaturalMap;
     effort?: LlmEffort;
     explain?: boolean;
@@ -600,7 +658,21 @@ interface LlmExchangeEnvelope {
     timing: LlmExchangeTiming;
 }
 type LlmExchangeCallback = (envelope: LlmExchangeEnvelope) => unknown | Promise<unknown>;
+/**
+ * Prompt-caching control for operate()/stream().
+ * - `true` / omitted → caching enabled at the default `"5m"` TTL
+ * - `false` / `0` → caching disabled
+ * - `"5m"` / `"1h"` → enabled at that TTL (TTL honored by Anthropic/OpenRouter;
+ *   other providers ignore it and cache with their own defaults)
+ */
+type LlmCache = boolean | 0 | "5m" | "1h";
 interface LlmOperateOptions {
+    /**
+     * Prompt caching for the stable request prefix (system prompt + tools).
+     * Enabled by default; pass `false`/`0` to opt out, or `"5m"`/`"1h"` to set
+     * the TTL. See {@link LlmCache}.
+     */
+    cache?: LlmCache;
     data?: NaturalMap;
     /**
      * Provider-neutral reasoning effort (lowest | low | medium | high | highest).
@@ -709,6 +781,10 @@ interface LlmUsageItem {
     output: number;
     reasoning: number;
     total: number;
+    /** Prompt-cache tokens served from cache this call (billed at ~0.1x input) */
+    cacheRead?: number;
+    /** Prompt-cache tokens written to cache this call (billed at ~1.25x input) */
+    cacheWrite?: number;
     provider?: string;
     model?: string;
 }
@@ -1023,4 +1099,4 @@ declare class XaiProvider implements LlmProvider {
 }
 
 export { BedrockProvider, ErrorCategory, FireworksProvider, GoogleProvider as GeminiProvider, GoogleProvider, JaypieToolkit, constants as LLM, Llm, LlmError, LlmMessageRole, LlmMessageType, LlmProgressEventType, LlmQuotaError, LlmRateLimitError, LlmStreamChunkType, LlmTransientError, LlmUnrecoverableError, OpenRouterProvider, Toolkit, XaiProvider, extractReasoning, isLlmOperateInput, isLlmOperateInputContent, isLlmOperateInputFile, isLlmOperateInputImage, jsonSchemaToNaturalSchema, naturalSchemaToJsonSchema, toolkit, tools };
-export type { LlmEffort, LlmErrorOptions, LlmExchangeCallback, LlmExchangeEnvelope, LlmExchangeRequest, LlmExchangeResolution, LlmExchangeResponse, LlmExchangeTiming, LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmModelOption, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProgressCallback, LlmProgressEvent, LlmProgressToolCall, LlmProvider, LlmStreamChunk, LlmStreamChunkDone, LlmStreamChunkError, LlmStreamChunkText, LlmStreamChunkToolCall, LlmStreamChunkToolResult, LlmTool };
+export type { LlmCache, LlmEffort, LlmErrorOptions, LlmExchangeCallback, LlmExchangeEnvelope, LlmExchangeRequest, LlmExchangeResolution, LlmExchangeResponse, LlmExchangeTiming, LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmModelCost, LlmModelOption, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProgressCallback, LlmProgressEvent, LlmProgressToolCall, LlmProvider, LlmStreamChunk, LlmStreamChunkDone, LlmStreamChunkError, LlmStreamChunkText, LlmStreamChunkToolCall, LlmStreamChunkToolResult, LlmTool };