@axlsdk/axl 0.20.0 → 0.21.0

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.
@@ -2117,6 +2127,8 @@ type OpenAICompatibleOptions = {
     /** API key or a per-request resolver (expiring tokens). See {@link ApiKeySource}. */
     apiKey?: ApiKeySource;
     baseUrl?: string;
+    /** Permit a non-loopback HTTP endpoint for this provider instance. */
+    dangerouslyAllowInsecureHttp?: boolean;
     /** Override the profile's auth header shape (e.g. Azure Entra bearer tokens). */
     authHeader?: AuthHeader;
     rateLimit?: RateLimitConfig;
@@ -2147,11 +2159,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 +2184,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 +2217,55 @@ type OpenAIChatResponse = {
         finish_reason: string;
     }>;
     usage?: OpenAIUsage;
+} & OpenAIModelResponse;
+type OpenAIModelResponse = {
+    model?: string;
+    service_tier?: unknown;
+    serviceTier?: unknown;
+    usage?: OpenAIUsage;
+};
+
+/**
+ * MCP (Model Context Protocol) types for tool discovery and execution.
+ */
+/** A tool definition discovered from an MCP server. */
+type McpToolDefinition = {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+};
+/** Configuration for connecting to an MCP server. */
+type McpServerConfig = {
+    name: string;
+    /** Command to spawn for stdio transport (e.g. "npx -y @modelcontextprotocol/server-fs") */
+    command?: string;
+    /** Arguments for the command */
+    args?: string[];
+    /** HTTP/SSE endpoint URI for HTTP transport */
+    uri?: string;
+    /** Allow this MCP server to use non-loopback HTTP. Prefer HTTPS. */
+    dangerouslyAllowInsecureHttp?: boolean;
+    /** Environment variables to pass to the spawned process */
+    env?: Record<string, string>;
+};
+/** Result from calling an MCP tool. */
+type McpToolResult = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    } | {
+        type: 'image';
+        data: string;
+        mimeType: string;
+    }>;
+    isError?: boolean;
+};
+/** A connected MCP server with its discovered tools. */
+type McpServer = {
+    name: string;
+    tools: McpToolDefinition[];
+    callTool(toolName: string, args: unknown): Promise<McpToolResult>;
+    close(): Promise<void>;
 };
 
 /** A pending human decision awaiting resolution. */
@@ -2438,6 +2515,11 @@ type ProviderConfig = {
      *  the common case. See {@link ApiKeySource}. */
     apiKey?: ApiKeySource;
     baseUrl?: string;
+    /**
+     * Allow a non-loopback HTTP endpoint for this provider. HTTP can expose
+     * prompts and credentials in transit; prefer HTTPS whenever possible.
+     */
+    dangerouslyAllowInsecureHttp?: boolean;
     /** OpenAI-compatible presets only: override the profile auth header shape. */
     authHeader?: AuthHeader;
     /**
@@ -2450,13 +2532,6 @@ type ProviderConfig = {
      */
     rateLimit?: RateLimitConfig;
 };
-/** MCP server configuration */
-type McpServerConfig$1 = {
-    name: string;
-    command?: string;
-    uri?: string;
-    env?: Record<string, string>;
-};
 /** Trace configuration */
 type TraceConfig = {
     enabled?: boolean;
@@ -2568,7 +2643,7 @@ type AxlConfig = {
     defaultProvider?: string;
     defaultModel?: string;
     mcp?: {
-        servers?: McpServerConfig$1[];
+        servers?: McpServerConfig[];
     };
     state?: StateConfig;
     trace?: TraceConfig;
@@ -2661,47 +2736,6 @@ declare class ProviderRegistry {
     clearFactories(): void;
 }
 
-/**
- * MCP (Model Context Protocol) types for tool discovery and execution.
- */
-/** A tool definition discovered from an MCP server. */
-type McpToolDefinition = {
-    name: string;
-    description: string;
-    inputSchema: unknown;
-};
-/** Configuration for connecting to an MCP server. */
-type McpServerConfig = {
-    name: string;
-    /** Command to spawn for stdio transport (e.g. "npx -y @modelcontextprotocol/server-fs") */
-    command?: string;
-    /** Arguments for the command */
-    args?: string[];
-    /** HTTP/SSE endpoint URI for HTTP transport */
-    uri?: string;
-    /** Environment variables to pass to the spawned process */
-    env?: Record<string, string>;
-};
-/** Result from calling an MCP tool. */
-type McpToolResult = {
-    content: Array<{
-        type: 'text';
-        text: string;
-    } | {
-        type: 'image';
-        data: string;
-        mimeType: string;
-    }>;
-    isError?: boolean;
-};
-/** A connected MCP server with its discovered tools. */
-type McpServer = {
-    name: string;
-    tools: McpToolDefinition[];
-    callTool(toolName: string, args: unknown): Promise<McpToolResult>;
-    close(): Promise<void>;
-};
-
 /**
  * Manages connections to multiple MCP servers.
  * Discovers tools, filters by agent config, and routes tool calls.
@@ -4402,7 +4436,14 @@ declare function registerConditions(conditions: string[]): Promise<void>;
  *    attempt-N text never leaks into attempt-N+1).
  *  - `ask_end` clears the per-ask accumulator (memory hygiene).
  *
- * Example (browser, consuming Studio's WS firehose):
+ * SECURITY: "browser-safe" here means this module has no Node runtime
+ * dependency. It does not redact or authorize the raw `AxlEvent` source.
+ * Prompts, system messages, tool data, and traces should remain on the trusted
+ * backend; public applications should relay an output-only DTO produced from a
+ * server-side curated view. Use this helper only when the browser is authorized
+ * to receive the underlying event stream.
+ *
+ * Example (trusted operator browser, consuming an authorized Studio WS firehose):
  *
  * ```ts
  * import { stringStreamFromEvents } from '@axlsdk/axl';
@@ -4461,6 +4502,8 @@ declare function hasPositiveTokens(event: {
         input?: number;
         output?: number;
         reasoning?: number;
+        cached?: number;
+        cacheWrite?: number;
     } | null;
 }): boolean;
 /**
@@ -4524,6 +4567,8 @@ declare function isUnpricedLeaf(event: {
         input?: number;
         output?: number;
         reasoning?: number;
+        cached?: number;
+        cacheWrite?: number;
     } | null;
 }): boolean;
 /**
@@ -4739,6 +4784,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`).
@@ -4768,8 +4822,10 @@ declare class OpenAIProvider extends OpenAICompatibleProvider {
     constructor(options?: {
         apiKey?: ApiKeySource;
         baseUrl?: string;
+        dangerouslyAllowInsecureHttp?: boolean;
         rateLimit?: RateLimitConfig;
     });
+    protected computeCost(model: string, usage: ProviderResponse['usage'], _reportedCost: number | undefined, context?: DirectOpenAIPricingContext): number | undefined;
 }
 
 /**
@@ -4789,6 +4845,7 @@ declare class OpenAIResponsesProvider implements Provider {
     constructor(options?: {
         apiKey?: ApiKeySource;
         baseUrl?: string;
+        dangerouslyAllowInsecureHttp?: boolean;
         rateLimit?: RateLimitConfig;
     });
     /** Resolve the API key for one request (supports an expiring-token callback). */
@@ -4798,6 +4855,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`.
@@ -4838,6 +4896,7 @@ declare class AnthropicProvider implements Provider {
     constructor(options?: {
         apiKey?: ApiKeySource;
         baseUrl?: string;
+        dangerouslyAllowInsecureHttp?: boolean;
         rateLimit?: RateLimitConfig;
     });
     /** Resolve the API key for one request (supports an expiring-token callback). */
@@ -4856,6 +4915,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.
@@ -4908,6 +4968,7 @@ declare class GeminiProvider implements Provider {
     constructor(options?: {
         apiKey?: ApiKeySource;
         baseUrl?: string;
+        dangerouslyAllowInsecureHttp?: boolean;
         rateLimit?: RateLimitConfig;
     });
     /** Resolve the API key for one request (supports an expiring-token callback). */
@@ -4916,6 +4977,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 +5011,7 @@ declare class GeminiProvider implements Provider {
     private mapToolChoice;
     private mapToolDefinition;
     private parseResponse;
+    private isTextOnlyGeminiResponse;
     private parseSSEStream;
 }
 
@@ -4954,9 +5021,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 +5045,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;
 
@@ -5458,6 +5522,7 @@ declare class OpenAIEmbedder implements Embedder {
         apiKey?: string;
         model?: string;
         baseUrl?: string;
+        dangerouslyAllowInsecureHttp?: boolean;
         dimensions?: number;
     });
     embed(texts: string[], signal?: AbortSignal): Promise<EmbedResult>;