@axlsdk/axl 0.20.0 → 0.20.1

package/dist/index.d.cts

@@ -112,6 +112,8 @@ type StreamChunk = {
         total_tokens: number;
         reasoning_tokens?: number;
         cached_tokens?: number;
+        /** Tokens written to a provider prompt cache during this call, when reported. */
+        cache_write_tokens?: number;
     };
     /** Estimated cost in USD for this call, computed the same way as ProviderResponse.cost. */
     cost?: number;
@@ -859,6 +861,8 @@ type AxlEventBase = {
         input?: number;
         output?: number;
         reasoning?: number;
+        cached?: number;
+        cacheWrite?: number;
     };
     /** Duration in ms (set on `_end` variants and a few single-point events). */
     duration?: number;
@@ -944,6 +948,8 @@ type LegacyAxlEventPayloadV1 = (AxlEventBase & {
         input?: number;
         output?: number;
         reasoning?: number;
+        cached?: number;
+        cacheWrite?: number;
     };
     /** Response-side payload — response text, thinking. */
     data: AgentCallEndData;
@@ -1296,6 +1302,8 @@ type ProviderResponse = {
         total_tokens: number;
         reasoning_tokens?: number;
         cached_tokens?: number;
+        /** Tokens written to a provider prompt cache during this call, when reported. */
+        cache_write_tokens?: number;
     };
     cost?: number;
     /** Provider-specific opaque metadata that needs to round-trip through conversation history. */
@@ -1949,6 +1957,8 @@ type PricingTable = Record<string, [number, number, number]>;
 type PricingSource = {
     kind: 'table';
     table: PricingTable;
+    /** Exact matching prevents a future sibling from inheriting a base price. */
+    match?: 'prefix' | 'exact';
 }
 /** Provider reports per-call cost in `usage.cost` (OpenRouter credits ≈ USD). */
  | {
@@ -2075,7 +2085,7 @@ type ProviderProfile = {
  * versioned snapshots like `gpt-4o-2024-05-13`). Returns `undefined` on a miss —
  * callers MUST treat that as "unknown cost", never as free.
  */
-declare function priceFromTable(table: PricingTable, model: string, promptTokens: number, completionTokens: number, cachedTokens?: number): number | undefined;
+declare function priceFromTable(table: PricingTable, model: string, promptTokens: number, completionTokens: number, cachedTokens?: number, match?: 'prefix' | 'exact'): number | undefined;
 /**
  * Incremental scanner that separates streamed content into visible text and
  * `<think>…</think>` reasoning, tolerating tags split across chunks.
@@ -2147,11 +2157,21 @@ declare class OpenAICompatibleProvider implements Provider {
     protected buildRequestBody(messages: ChatMessage[], options: ChatOptions, stream: boolean): Record<string, unknown>;
     protected formatMessage(msg: ChatMessage, model: string): Record<string, unknown>;
     protected extractErrorMessage(body: string, status: number): string;
+    private requestModel;
     private toUsage;
-    private computeCost;
-    protected parseResponse(json: OpenAIChatResponse, model: string): ProviderResponse;
+    private reportedCost;
+    /**
+     * The generic profile path stays flat and public. Native subclasses may
+     * override this protected seam to use a provider-internal estimator without
+     * widening `PricingSource` or `ProviderProfile`.
+     */
+    protected computeCost(model: string, usage: ProviderResponse['usage'], reportedCost: number | undefined, context?: {
+        request?: Record<string, unknown>;
+        response?: OpenAIModelResponse;
+    }): number | undefined;
+    protected parseResponse(json: OpenAIChatResponse, model: string, request?: Record<string, unknown>): ProviderResponse;
     private roundTripMetadata;
-    protected parseSSEStream(body: ReadableStream<Uint8Array>, model: string): AsyncGenerator<StreamChunk>;
+    protected parseSSEStream(body: ReadableStream<Uint8Array>, model: string, request?: Record<string, unknown>): AsyncGenerator<StreamChunk>;
 }
 type OpenAIUsage = {
     prompt_tokens: number;
@@ -2162,9 +2182,15 @@ type OpenAIUsage = {
     };
     prompt_tokens_details?: {
         cached_tokens?: number;
+        cache_write_tokens?: number;
     };
     /** OpenRouter / Vercel Gateway: per-call cost in USD. */
     cost?: number;
+    /** xAI: exact billed USD cost in ten-billionths of a dollar. */
+    cost_in_usd_ticks?: number;
+    /** DeepSeek: normalized cache hit/miss split for table pricing. */
+    prompt_cache_hit_tokens?: number;
+    prompt_cache_miss_tokens?: number;
 };
 type OpenAIChatMessage = {
     content: string | null | Array<string | {
@@ -2189,6 +2215,12 @@ type OpenAIChatResponse = {
         finish_reason: string;
     }>;
     usage?: OpenAIUsage;
+} & OpenAIModelResponse;
+type OpenAIModelResponse = {
+    model?: string;
+    service_tier?: unknown;
+    serviceTier?: unknown;
+    usage?: OpenAIUsage;
 };
 
 /** A pending human decision awaiting resolution. */
@@ -4461,6 +4493,8 @@ declare function hasPositiveTokens(event: {
         input?: number;
         output?: number;
         reasoning?: number;
+        cached?: number;
+        cacheWrite?: number;
     } | null;
 }): boolean;
 /**
@@ -4524,6 +4558,8 @@ declare function isUnpricedLeaf(event: {
         input?: number;
         output?: number;
         reasoning?: number;
+        cached?: number;
+        cacheWrite?: number;
     } | null;
 }): boolean;
 /**
@@ -4739,6 +4775,15 @@ declare class ProviderError extends AxlError {
 declare function isRetryableStatus(status: number): boolean;
 
 declare const OPENAI_PRICING: PricingTable;
+type DirectOpenAIPricingContext = {
+    /** Only the canonical direct API endpoint has a usable catalog. */
+    baseUrl?: string;
+    request?: Record<string, unknown>;
+    response?: {
+        service_tier?: unknown;
+        serviceTier?: unknown;
+    };
+};
 /**
  * Estimate OpenAI call cost from token usage. Exact match first, then
  * longest-prefix match for versioned models (e.g. `gpt-4o-2024-05-13`).
@@ -4770,6 +4815,7 @@ declare class OpenAIProvider extends OpenAICompatibleProvider {
         baseUrl?: string;
         rateLimit?: RateLimitConfig;
     });
+    protected computeCost(model: string, usage: ProviderResponse['usage'], _reportedCost: number | undefined, context?: DirectOpenAIPricingContext): number | undefined;
 }
 
 /**
@@ -4798,6 +4844,7 @@ declare class OpenAIResponsesProvider implements Provider {
     chat(messages: ChatMessage[], options: ChatOptions): Promise<ProviderResponse>;
     stream(messages: ChatMessage[], options: ChatOptions): AsyncGenerator<StreamChunk>;
     private buildRequestBody;
+    private requestModel;
     private buildInput;
     /**
      * The Responses API uses `text.format` instead of `response_format`.
@@ -4856,6 +4903,7 @@ declare class AnthropicProvider implements Provider {
      * - tool messages (tool results) -> user messages with tool_result content blocks
      */
     private mapMessages;
+    private getReplayedThinkingBlocks;
     /**
      * Merge consecutive messages with the same role into a single message.
      * This handles cases where multiple tool_result blocks need to be in one user message.
@@ -4916,6 +4964,11 @@ declare class GeminiProvider implements Provider {
     stream(messages: ChatMessage[], options: ChatOptions): AsyncGenerator<StreamChunk>;
     private buildHeaders;
     private extractErrorMessage;
+    private pricingContext;
+    private requestModel;
+    private assertSafeGemini3Continuation;
+    private isTextOnlyClientRequest;
+    private isNonTextGeminiPart;
     private buildRequestBody;
     /**
      * Map OpenAI-format ChatMessages to Gemini content format.
@@ -4945,6 +4998,7 @@ declare class GeminiProvider implements Provider {
     private mapToolChoice;
     private mapToolDefinition;
     private parseResponse;
+    private isTextOnlyGeminiResponse;
     private parseSSEStream;
 }
 
@@ -4954,9 +5008,9 @@ declare class GeminiProvider implements Provider {
  * - Reasoning is the unified `reasoning` object (`{ effort }` XOR `{ max_tokens }`,
  *   or `{ enabled: false }`); reasoning text comes back in `message.reasoning`
  *   with a structured `reasoning_details[]` we round-trip on tool-call turns.
- * - Cost is provider-reported: `usage: { include: true }` makes OpenRouter return
- *   `usage.cost` (USD), so Axl keeps cost-as-a-primitive working across the whole
- *   catalog where a static table never could.
+ * - Cost is provider-reported in `usage.cost` (USD), so Axl keeps
+ *   cost-as-a-primitive working across the whole catalog where a static table
+ *   never could. OpenRouter now returns it automatically; no request opt-in.
  * - Model ids are `vendor/model` slugs (e.g. `anthropic/claude-opus-4.7`); the
  *   registry's first-colon split keeps `openrouter:anthropic/claude-…` intact.
  *
@@ -4978,20 +5032,17 @@ declare const OPENROUTER_PROFILE: ProviderProfile;
  * Entra/AAD bearer-token auth uses the async key callback plus an `authHeader:
  * 'bearer'` override.
  *
- * Azure serves OpenAI models, so the OpenAI reasoning logic and pricing table
- * are reused. Caveat: deployment names are arbitrary, so o-series/GPT-5
- * detection and pricing only fire when the deployment is named after the model;
- * otherwise effort is a no-op and cost is `undefined` (honest, not a fake $0).
+ * Azure can share OpenAI's wire reasoning behavior, but never its direct-API
+ * price catalog: model meters, deployment types, regions, and agreements vary.
  */
 declare const AZURE_PROFILE: ProviderProfile;
 
 /**
- * xAI (Grok). OpenAI-compatible at `https://api.x.ai/v1`.
+ * xAI (Grok) Chat Completions at `https://api.x.ai/v1`.
  *
- * - `reasoning_effort` (`low` for effort `low`, else `high`) for grok-3-mini;
- *   omitted for grok-4* (auto-reasoning) and non-reasoning models.
- * - `stop` + penalty params are stripped on reasoning models (they 400).
- *   Penalties aren't engine-computed, so they only matter if a user adds them.
+ * Pricing is the exact response total in `usage.cost_in_usd_ticks`; it already
+ * includes cache, service-tier, and server-side-tool charges. Grok 4.20
+ * multi-agent is Responses-only, so it deliberately has no Chat descriptor.
  */
 declare const XAI_PROFILE: ProviderProfile;
 

package/dist/index.d.ts

@@ -112,6 +112,8 @@ type StreamChunk = {
         total_tokens: number;
         reasoning_tokens?: number;
         cached_tokens?: number;
+        /** Tokens written to a provider prompt cache during this call, when reported. */
+        cache_write_tokens?: number;
     };
     /** Estimated cost in USD for this call, computed the same way as ProviderResponse.cost. */
     cost?: number;
@@ -859,6 +861,8 @@ type AxlEventBase = {
         input?: number;
         output?: number;
         reasoning?: number;
+        cached?: number;
+        cacheWrite?: number;
     };
     /** Duration in ms (set on `_end` variants and a few single-point events). */
     duration?: number;
@@ -944,6 +948,8 @@ type LegacyAxlEventPayloadV1 = (AxlEventBase & {
         input?: number;
         output?: number;
         reasoning?: number;
+        cached?: number;
+        cacheWrite?: number;
     };
     /** Response-side payload — response text, thinking. */
     data: AgentCallEndData;
@@ -1296,6 +1302,8 @@ type ProviderResponse = {
         total_tokens: number;
         reasoning_tokens?: number;
         cached_tokens?: number;
+        /** Tokens written to a provider prompt cache during this call, when reported. */
+        cache_write_tokens?: number;
     };
     cost?: number;
     /** Provider-specific opaque metadata that needs to round-trip through conversation history. */
@@ -1949,6 +1957,8 @@ type PricingTable = Record<string, [number, number, number]>;
 type PricingSource = {
     kind: 'table';
     table: PricingTable;
+    /** Exact matching prevents a future sibling from inheriting a base price. */
+    match?: 'prefix' | 'exact';
 }
 /** Provider reports per-call cost in `usage.cost` (OpenRouter credits ≈ USD). */
  | {
@@ -2075,7 +2085,7 @@ type ProviderProfile = {
  * versioned snapshots like `gpt-4o-2024-05-13`). Returns `undefined` on a miss —
  * callers MUST treat that as "unknown cost", never as free.
  */
-declare function priceFromTable(table: PricingTable, model: string, promptTokens: number, completionTokens: number, cachedTokens?: number): number | undefined;
+declare function priceFromTable(table: PricingTable, model: string, promptTokens: number, completionTokens: number, cachedTokens?: number, match?: 'prefix' | 'exact'): number | undefined;
 /**
  * Incremental scanner that separates streamed content into visible text and
  * `<think>…</think>` reasoning, tolerating tags split across chunks.
@@ -2147,11 +2157,21 @@ declare class OpenAICompatibleProvider implements Provider {
     protected buildRequestBody(messages: ChatMessage[], options: ChatOptions, stream: boolean): Record<string, unknown>;
     protected formatMessage(msg: ChatMessage, model: string): Record<string, unknown>;
     protected extractErrorMessage(body: string, status: number): string;
+    private requestModel;
     private toUsage;
-    private computeCost;
-    protected parseResponse(json: OpenAIChatResponse, model: string): ProviderResponse;
+    private reportedCost;
+    /**
+     * The generic profile path stays flat and public. Native subclasses may
+     * override this protected seam to use a provider-internal estimator without
+     * widening `PricingSource` or `ProviderProfile`.
+     */
+    protected computeCost(model: string, usage: ProviderResponse['usage'], reportedCost: number | undefined, context?: {
+        request?: Record<string, unknown>;
+        response?: OpenAIModelResponse;
+    }): number | undefined;
+    protected parseResponse(json: OpenAIChatResponse, model: string, request?: Record<string, unknown>): ProviderResponse;
     private roundTripMetadata;
-    protected parseSSEStream(body: ReadableStream<Uint8Array>, model: string): AsyncGenerator<StreamChunk>;
+    protected parseSSEStream(body: ReadableStream<Uint8Array>, model: string, request?: Record<string, unknown>): AsyncGenerator<StreamChunk>;
 }
 type OpenAIUsage = {
     prompt_tokens: number;
@@ -2162,9 +2182,15 @@ type OpenAIUsage = {
     };
     prompt_tokens_details?: {
         cached_tokens?: number;
+        cache_write_tokens?: number;
     };
     /** OpenRouter / Vercel Gateway: per-call cost in USD. */
     cost?: number;
+    /** xAI: exact billed USD cost in ten-billionths of a dollar. */
+    cost_in_usd_ticks?: number;
+    /** DeepSeek: normalized cache hit/miss split for table pricing. */
+    prompt_cache_hit_tokens?: number;
+    prompt_cache_miss_tokens?: number;
 };
 type OpenAIChatMessage = {
     content: string | null | Array<string | {
@@ -2189,6 +2215,12 @@ type OpenAIChatResponse = {
         finish_reason: string;
     }>;
     usage?: OpenAIUsage;
+} & OpenAIModelResponse;
+type OpenAIModelResponse = {
+    model?: string;
+    service_tier?: unknown;
+    serviceTier?: unknown;
+    usage?: OpenAIUsage;
 };
 
 /** A pending human decision awaiting resolution. */
@@ -4461,6 +4493,8 @@ declare function hasPositiveTokens(event: {
         input?: number;
         output?: number;
         reasoning?: number;
+        cached?: number;
+        cacheWrite?: number;
     } | null;
 }): boolean;
 /**
@@ -4524,6 +4558,8 @@ declare function isUnpricedLeaf(event: {
         input?: number;
         output?: number;
         reasoning?: number;
+        cached?: number;
+        cacheWrite?: number;
     } | null;
 }): boolean;
 /**
@@ -4739,6 +4775,15 @@ declare class ProviderError extends AxlError {
 declare function isRetryableStatus(status: number): boolean;
 
 declare const OPENAI_PRICING: PricingTable;
+type DirectOpenAIPricingContext = {
+    /** Only the canonical direct API endpoint has a usable catalog. */
+    baseUrl?: string;
+    request?: Record<string, unknown>;
+    response?: {
+        service_tier?: unknown;
+        serviceTier?: unknown;
+    };
+};
 /**
  * Estimate OpenAI call cost from token usage. Exact match first, then
  * longest-prefix match for versioned models (e.g. `gpt-4o-2024-05-13`).
@@ -4770,6 +4815,7 @@ declare class OpenAIProvider extends OpenAICompatibleProvider {
         baseUrl?: string;
         rateLimit?: RateLimitConfig;
     });
+    protected computeCost(model: string, usage: ProviderResponse['usage'], _reportedCost: number | undefined, context?: DirectOpenAIPricingContext): number | undefined;
 }
 
 /**
@@ -4798,6 +4844,7 @@ declare class OpenAIResponsesProvider implements Provider {
     chat(messages: ChatMessage[], options: ChatOptions): Promise<ProviderResponse>;
     stream(messages: ChatMessage[], options: ChatOptions): AsyncGenerator<StreamChunk>;
     private buildRequestBody;
+    private requestModel;
     private buildInput;
     /**
      * The Responses API uses `text.format` instead of `response_format`.
@@ -4856,6 +4903,7 @@ declare class AnthropicProvider implements Provider {
      * - tool messages (tool results) -> user messages with tool_result content blocks
      */
     private mapMessages;
+    private getReplayedThinkingBlocks;
     /**
      * Merge consecutive messages with the same role into a single message.
      * This handles cases where multiple tool_result blocks need to be in one user message.
@@ -4916,6 +4964,11 @@ declare class GeminiProvider implements Provider {
     stream(messages: ChatMessage[], options: ChatOptions): AsyncGenerator<StreamChunk>;
     private buildHeaders;
     private extractErrorMessage;
+    private pricingContext;
+    private requestModel;
+    private assertSafeGemini3Continuation;
+    private isTextOnlyClientRequest;
+    private isNonTextGeminiPart;
     private buildRequestBody;
     /**
      * Map OpenAI-format ChatMessages to Gemini content format.
@@ -4945,6 +4998,7 @@ declare class GeminiProvider implements Provider {
     private mapToolChoice;
     private mapToolDefinition;
     private parseResponse;
+    private isTextOnlyGeminiResponse;
     private parseSSEStream;
 }
 
@@ -4954,9 +5008,9 @@ declare class GeminiProvider implements Provider {
  * - Reasoning is the unified `reasoning` object (`{ effort }` XOR `{ max_tokens }`,
  *   or `{ enabled: false }`); reasoning text comes back in `message.reasoning`
  *   with a structured `reasoning_details[]` we round-trip on tool-call turns.
- * - Cost is provider-reported: `usage: { include: true }` makes OpenRouter return
- *   `usage.cost` (USD), so Axl keeps cost-as-a-primitive working across the whole
- *   catalog where a static table never could.
+ * - Cost is provider-reported in `usage.cost` (USD), so Axl keeps
+ *   cost-as-a-primitive working across the whole catalog where a static table
+ *   never could. OpenRouter now returns it automatically; no request opt-in.
  * - Model ids are `vendor/model` slugs (e.g. `anthropic/claude-opus-4.7`); the
  *   registry's first-colon split keeps `openrouter:anthropic/claude-…` intact.
  *
@@ -4978,20 +5032,17 @@ declare const OPENROUTER_PROFILE: ProviderProfile;
  * Entra/AAD bearer-token auth uses the async key callback plus an `authHeader:
  * 'bearer'` override.
  *
- * Azure serves OpenAI models, so the OpenAI reasoning logic and pricing table
- * are reused. Caveat: deployment names are arbitrary, so o-series/GPT-5
- * detection and pricing only fire when the deployment is named after the model;
- * otherwise effort is a no-op and cost is `undefined` (honest, not a fake $0).
+ * Azure can share OpenAI's wire reasoning behavior, but never its direct-API
+ * price catalog: model meters, deployment types, regions, and agreements vary.
  */
 declare const AZURE_PROFILE: ProviderProfile;
 
 /**
- * xAI (Grok). OpenAI-compatible at `https://api.x.ai/v1`.
+ * xAI (Grok) Chat Completions at `https://api.x.ai/v1`.
  *
- * - `reasoning_effort` (`low` for effort `low`, else `high`) for grok-3-mini;
- *   omitted for grok-4* (auto-reasoning) and non-reasoning models.
- * - `stop` + penalty params are stripped on reasoning models (they 400).
- *   Penalties aren't engine-computed, so they only matter if a user adds them.
+ * Pricing is the exact response total in `usage.cost_in_usd_ticks`; it already
+ * includes cache, service-tier, and server-side-tool charges. Grok 4.20
+ * multi-agent is Responses-only, so it deliberately has no Chat descriptor.
  */
 declare const XAI_PROFILE: ProviderProfile;