@jambonz/llm 0.5.7 → 0.6.1

package/dist/{types-rZZBXYhB.d.cts → types-Y0o6rN3B.d.cts}

@@ -84,6 +84,24 @@ interface PromptRequest {
     providerParams?: Record<string, unknown>;
     /** Abort the stream. Adapters MUST honor this and propagate to the vendor SDK. */
     signal?: AbortSignal;
+    /**
+     * Caller-supplied prompt-caching routing/grouping hint.
+     *
+     * NOT a secret and NOT a tenant isolation boundary. Cache hits still require
+     * a byte-identical prefix, and vendors isolate caches per org/workspace
+     * regardless of this value.
+     *
+     * Adapter behaviour:
+     *   - OpenAI-wire adapters (openai, azure-openai, groq, etc.) forward it as
+     *     `prompt_cache_key` on the request body.
+     *   - Anthropic and Bedrock (Claude) use its PRESENCE to enable native cache
+     *     breakpoints on the system prompt, the tool definitions, and the final
+     *     message — so the entire conversation prefix is cached each turn.
+     *   - Adapters without a caching mechanism (e.g. Google/Gemini) silently ignore it.
+     *
+     * The library never auto-derives this value from message content.
+     */
+    cacheKey?: string;
 }
 type LlmEvent = {
     type: 'token';
@@ -145,9 +163,26 @@ type ToolCallEvent = Extract<LlmEvent, {
 }>;
 type FinishReason = 'stop' | 'tool' | 'length' | 'filtered' | 'error' | 'aborted';
 interface Usage {
+    /**
+     * UNCACHED input tokens. The three input classes (uncached, cache read,
+     * cache write) are additive and each has its own vendor price, so callers
+     * can meter/bill them independently. Adapters normalize to this convention:
+     * Anthropic/Bedrock already report exclusively; OpenAI-wire and Gemini
+     * report an inclusive prompt total and the adapter subtracts the cached
+     * portion out.
+     */
     inputTokens?: number;
     outputTokens?: number;
+    /** Vendor-reported grand total across all token classes. */
     totalTokens?: number;
+    /** Input tokens served from the vendor's prompt cache (discounted). */
+    cacheReadTokens?: number;
+    /**
+     * Input tokens written to the vendor's prompt cache. Only Anthropic-family
+     * vendors bill cache writes (at a premium); vendors that don't report the
+     * class omit the field.
+     */
+    cacheWriteTokens?: number;
 }
 type AuthSpec = ApiKeyAuth | AzureOpenAIApiKeyAuth | BedrockIamAuth | BedrockApiKeyAuth | GoogleApiKeyAuth | GoogleServiceAccountAuth | VertexServiceAccountAuth;
 interface ApiKeyAuth {

package/dist/{types-rZZBXYhB.d.ts → types-Y0o6rN3B.d.ts}

@@ -84,6 +84,24 @@ interface PromptRequest {
     providerParams?: Record<string, unknown>;
     /** Abort the stream. Adapters MUST honor this and propagate to the vendor SDK. */
     signal?: AbortSignal;
+    /**
+     * Caller-supplied prompt-caching routing/grouping hint.
+     *
+     * NOT a secret and NOT a tenant isolation boundary. Cache hits still require
+     * a byte-identical prefix, and vendors isolate caches per org/workspace
+     * regardless of this value.
+     *
+     * Adapter behaviour:
+     *   - OpenAI-wire adapters (openai, azure-openai, groq, etc.) forward it as
+     *     `prompt_cache_key` on the request body.
+     *   - Anthropic and Bedrock (Claude) use its PRESENCE to enable native cache
+     *     breakpoints on the system prompt, the tool definitions, and the final
+     *     message — so the entire conversation prefix is cached each turn.
+     *   - Adapters without a caching mechanism (e.g. Google/Gemini) silently ignore it.
+     *
+     * The library never auto-derives this value from message content.
+     */
+    cacheKey?: string;
 }
 type LlmEvent = {
     type: 'token';
@@ -145,9 +163,26 @@ type ToolCallEvent = Extract<LlmEvent, {
 }>;
 type FinishReason = 'stop' | 'tool' | 'length' | 'filtered' | 'error' | 'aborted';
 interface Usage {
+    /**
+     * UNCACHED input tokens. The three input classes (uncached, cache read,
+     * cache write) are additive and each has its own vendor price, so callers
+     * can meter/bill them independently. Adapters normalize to this convention:
+     * Anthropic/Bedrock already report exclusively; OpenAI-wire and Gemini
+     * report an inclusive prompt total and the adapter subtracts the cached
+     * portion out.
+     */
     inputTokens?: number;
     outputTokens?: number;
+    /** Vendor-reported grand total across all token classes. */
     totalTokens?: number;
+    /** Input tokens served from the vendor's prompt cache (discounted). */
+    cacheReadTokens?: number;
+    /**
+     * Input tokens written to the vendor's prompt cache. Only Anthropic-family
+     * vendors bill cache writes (at a premium); vendors that don't report the
+     * class omit the field.
+     */
+    cacheWriteTokens?: number;
 }
 type AuthSpec = ApiKeyAuth | AzureOpenAIApiKeyAuth | BedrockIamAuth | BedrockApiKeyAuth | GoogleApiKeyAuth | GoogleServiceAccountAuth | VertexServiceAccountAuth;
 interface ApiKeyAuth {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jambonz/llm",
-  "version": "0.5.7",
+  "version": "0.6.1",
   "description": "Voice-oriented LLM adapter library — a uniform interface for streaming chat completions from multiple LLM vendors, with first-class support for tool calls, AbortSignal interruption, and lossless history round-tripping.",
   "type": "module",
   "main": "./dist/index.cjs",