@deepstrike/sdk 0.2.60 → 0.2.61

package/dist/providers/model-registry.js

@@ -31,6 +31,54 @@ export const registryEvidence = [
         verifiedAt: "2026-08-12",
     },
 ];
+export const cacheCapabilityEvidence = [
+    {
+        endpointId: "anthropic.messages",
+        source: "https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching",
+        verifiedAt: "2026-08-26",
+        classification: "documentation",
+        usageFields: ["cache_read_input_tokens", "cache_creation_input_tokens"],
+    },
+    {
+        endpointId: "deepseek.openai",
+        source: "https://api-docs.deepseek.com/guides/kv_cache",
+        verifiedAt: "2026-08-26",
+        classification: "documentation",
+        usageFields: ["prompt_cache_hit_tokens", "prompt_cache_miss_tokens"],
+    },
+];
+export const tokenMeasurementEvidence = [
+    {
+        endpointId: "anthropic.messages",
+        source: "https://github.com/anthropics/anthropic-sdk-typescript/blob/main/api.md#count-tokens",
+        verifiedAt: "2026-08-26",
+        providerApiState: "supported",
+        adapterState: "available",
+        method: "provider_preflight",
+        coverage: ["system", "messages", "tools"],
+        sdk: "@anthropic-ai/sdk ^0.99.0",
+    },
+    {
+        endpointId: "gemini.google",
+        source: "https://ai.google.dev/api/tokens#method-models.countTokens",
+        verifiedAt: "2026-08-26",
+        providerApiState: "supported",
+        adapterState: "available",
+        method: "provider_preflight",
+        coverage: ["contents", "system", "tools", "provider_options"],
+        sdk: "@google/generative-ai ^0.24.1",
+    },
+    {
+        endpointId: "openai.responses",
+        source: "https://github.com/openai/openai-node/tree/master/src/resources/responses/input-tokens.ts",
+        verifiedAt: "2026-08-26",
+        providerApiState: "supported",
+        adapterState: "available",
+        method: "provider_preflight",
+        coverage: ["input", "instructions", "tools", "provider_options"],
+        sdk: "openai ^7.5.0",
+    },
+];
 const POLICY = {
     "anthropic/claude-opus-4-1": { maxTurns: 50 },
     "anthropic/claude-opus-4-7": { maxTurns: 50 },
@@ -114,11 +162,11 @@ const DEFAULT_ENDPOINT = {
     anthropic: "anthropic.messages",
     openai: "openai.chat",
     minimax: "minimax.anthropic",
-    deepseek: "deepseek.anthropic",
-    kimi: "kimi.anthropic",
-    qwen: "qwen.anthropic",
+    deepseek: "deepseek.openai",
+    kimi: "kimi.openai",
+    qwen: "qwen.dashscope",
     gemini: "gemini.google",
-    glm: "glm.anthropic",
+    glm: "glm.openai",
     baai: "baai.self-hosted.embeddings",
     ollama: "ollama.local",
 };
@@ -137,6 +185,9 @@ const DEFAULT_MODEL = {
 export function defaultModelForProvider(providerId) {
     return DEFAULT_MODEL[providerId];
 }
+export function defaultEndpointForProvider(providerId) {
+    return DEFAULT_ENDPOINT[providerId];
+}
 function endpointFor(providerId, modelId) {
     if (providerId === "openai") {
         if (modelId.startsWith("text-embedding-"))
@@ -225,8 +276,10 @@ export const protocolRuntimeCapabilities = {
     "ollama-chat": OLLAMA_PROTOCOL_CAPABILITIES,
 };
 export const endpointRuntimeCapabilities = {
-    "anthropic.messages": { nativeTokenCounting: true },
+    "anthropic.messages": { nativeTokenCounting: true, promptCaching: true },
+    "deepseek.openai": { promptCaching: true },
     "gemini.google": { nativeTokenCounting: true },
+    "openai.responses": { nativeTokenCounting: true },
 };
 export function resolveEffectiveCapability(layers) {
     const evidence = layers.filter(layer => layer.state !== "unknown").map(layer => layer.layer);
@@ -285,7 +338,14 @@ export function resolveEffectiveModelCapabilities(input) {
         ]),
         parallelToolCalls: protocolBoolean(protocol.parallelToolCalls, overrides?.parallelToolCalls),
         structuredOutput: protocolBoolean(protocol.structuredOutput, overrides?.structuredOutput),
-        promptCaching: protocolBoolean(protocol.promptCaching, overrides?.promptCaching),
+        promptCaching: resolveEffectiveCapability([
+            { layer: "protocol", state: booleanState(protocol.promptCaching), value: protocol.promptCaching },
+            {
+                layer: "endpoint",
+                state: booleanState(input.endpointCapabilities?.promptCaching),
+                value: input.endpointCapabilities?.promptCaching,
+            },
+        ]),
         nativeTokenCounting: resolveEffectiveCapability([
             { layer: "endpoint", state: booleanState(input.endpointCapabilities?.nativeTokenCounting) },
         ]),
@@ -307,8 +367,12 @@ export function generationProtocol(protocol) {
             return undefined;
     }
 }
-export function endpointCapabilitiesFor(endpointId, preserveEndpointIdentity) {
-    return preserveEndpointIdentity ? endpointRuntimeCapabilities[endpointId] : undefined;
+export function endpointCapabilitiesFor(endpointId, preserveEndpointIdentity, preserveCacheEvidence = preserveEndpointIdentity) {
+    const capabilities = preserveEndpointIdentity ? endpointRuntimeCapabilities[endpointId] : undefined;
+    if (!capabilities || preserveCacheEvidence)
+        return capabilities;
+    const { promptCaching: _promptCaching, ...withoutCacheEvidence } = capabilities;
+    return withoutCacheEvidence;
 }
 export function isKnownProviderId(value) {
     return value in DEFAULT_ENDPOINT;

package/dist/providers/ollama-adapter.js

@@ -40,8 +40,8 @@ function validCount(raw, field) {
     const value = raw[field];
     if (value === undefined)
         return undefined;
-    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
-        throw new ProtocolResponseError("ollama-chat", `${field} must be a non-negative finite number`);
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        throw new ProtocolResponseError("ollama-chat", `${field} must be a non-negative safe integer`);
     }
     return value;
 }

package/dist/providers/openai-chat.js

@@ -2,6 +2,7 @@ import { assistantReplayKey } from "../runtime/provider-replay.js";
 import { openAICachedPromptTokens, stablePromptCacheKey, ThinkingTagStreamExtractor, } from "./base.js";
 import { normalizeCanonicalContext, projectToolOutputToText } from "./content-normalization.js";
 import { normalizeToolCall } from "./base.js";
+import { normalizeOpenAIUsage } from "./usage-normalizer.js";
 import { DEGRADED_REASONING_PLACEHOLDER, assessReasoningReplay, validateOpenAIChatReplay, } from "./replay-validator.js";
 import { ProtocolResponseError, } from "./protocol-adapter.js";
 import { OPENAI_CHAT_PROTOCOL_CAPABILITIES } from "./protocol-capabilities.js";
@@ -349,6 +350,8 @@ export class OpenAIChatAdapter {
                 ...(stopReason ? { stopReason } : {}),
                 ...(state.finishReason ? { rawStopReason: state.finishReason } : {}),
                 ...(providerUsage ? { providerUsage } : {}),
+                ...(providerUsage?.cacheTelemetryStatus ? { cacheTelemetryStatus: providerUsage.cacheTelemetryStatus } : {}),
+                ...(providerUsage?.cacheTelemetrySource ? { cacheTelemetrySource: providerUsage.cacheTelemetrySource } : {}),
             });
         }
         const replay = streamReplay(state);
@@ -371,12 +374,7 @@ export class OpenAIChatAdapter {
         const reasoningTokens = details && typeof details === "object"
             ? numberField(details, "reasoning_tokens")
             : undefined;
-        return {
-            inputTokens: inputTokens ?? 0,
-            outputTokens: outputTokens ?? 0,
-            ...(cacheReadInputTokens > 0 ? { cacheReadInputTokens } : {}),
-            ...(reasoningTokens !== undefined ? { reasoningTokens } : {}),
-        };
+        return normalizeOpenAIUsage(usage);
     }
     normalizeStopReason(raw) {
         if (raw === undefined)

package/dist/providers/openai-responses-adapter.js

@@ -1,13 +1,14 @@
 import { normalizeCanonicalContext } from "./content-normalization.js";
 import { normalizeToolCall, UnsupportedModalityError } from "./base.js";
+import { normalizeOpenAIUsage } from "./usage-normalizer.js";
 import { ProtocolResponseError, } from "./protocol-adapter.js";
 import { OPENAI_RESPONSES_PROTOCOL_CAPABILITIES } from "./protocol-capabilities.js";
 function numberField(raw, field) {
     const value = raw[field];
     if (value === undefined || value === null)
         return undefined;
-    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
-        throw new ProtocolResponseError("openai-responses", `usage.${field} must be a non-negative finite number`);
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        throw new ProtocolResponseError("openai-responses", `usage.${field} must be a non-negative safe integer`);
     }
     return value;
 }
@@ -267,6 +268,12 @@ export class OpenAIResponsesAdapter {
                         ...(inputTokens ? { inputTokens } : {}),
                         ...(outputTokens ? { outputTokens } : {}),
                         ...(cacheReadInputTokens ? { cacheReadInputTokens } : {}),
+                        ...(providerUsage?.cacheTelemetryStatus
+                            ? { cacheTelemetryStatus: providerUsage.cacheTelemetryStatus }
+                            : {}),
+                        ...(providerUsage?.cacheTelemetrySource
+                            ? { cacheTelemetrySource: providerUsage.cacheTelemetrySource }
+                            : {}),
                         ...(providerUsage && (inputTokens || outputTokens) ? { providerUsage } : {}),
                         ...(stopReason ? { stopReason } : {}),
                         ...(rawStopReason ? { rawStopReason } : {}),
@@ -294,16 +301,11 @@ export class OpenAIResponsesAdapter {
             throw new ProtocolResponseError("openai-responses", "usage.output_tokens_details must be an object");
         }
         cacheReadTokens(usage);
-        const reasoningTokens = outputDetails
-            ? numberField(outputDetails, "reasoning_tokens")
-            : undefined;
+        if (outputDetails)
+            numberField(outputDetails, "reasoning_tokens");
         if (inputTokens === undefined && outputTokens === undefined)
             return undefined;
-        return {
-            inputTokens: inputTokens ?? 0,
-            outputTokens: outputTokens ?? 0,
-            ...(reasoningTokens !== undefined ? { reasoningTokens } : {}),
-        };
+        return normalizeOpenAIUsage(usage);
     }
     normalizeStopReason(raw) {
         if (raw === undefined)

package/dist/providers/openai-responses.d.ts

@@ -1,5 +1,5 @@
 import OpenAI from "openai";
-import type { LLMProvider, Message, ProviderRunState, RenderedContext, RuntimePolicy, StreamEvent, ToolSchema } from "../types.js";
+import type { LLMProvider, Message, PromptMeasurement, ProviderRunState, RenderedContext, RuntimePolicy, StreamEvent, ToolSchema } from "../types.js";
 import { CircuitBreaker } from "./base.js";
 import { type CanonicalAdapterInput } from "./content-normalization.js";
 import { OpenAIResponsesAdapter, type OpenAIResponsesRunState } from "./openai-responses-adapter.js";
@@ -14,6 +14,7 @@ export declare class OpenAIResponsesProvider implements LLMProvider {
     protected baseDelay: number;
     protected readonly responses: OpenAIResponsesAdapter;
     private readonly resolvedRuntimePolicy;
+    private readonly directNativeTokenCounting;
     private resolvedRuntime?;
     constructor(apiKey: string, model?: string, retry?: {
         maxRetries: number;
@@ -24,6 +25,10 @@ export declare class OpenAIResponsesProvider implements LLMProvider {
     createRunState(): OpenAIResponsesRunState;
     private adapterInput;
     complete(context: RenderedContext, tools: ToolSchema[], extensions?: Record<string, unknown>): Promise<Message>;
+    /** spc_024-05: native preflight via the official Responses input-token count endpoint. Counts
+     * the exact create request plan (stateful `previous_response_id` continuation included) —
+     * native measurement belongs to the verified official endpoint, not the wire protocol. */
+    countTokens(context: RenderedContext, tools: ToolSchema[], extensions?: Record<string, unknown>, state?: ProviderRunState): Promise<PromptMeasurement>;
     stream(context: RenderedContext, tools: ToolSchema[], extensions?: Record<string, unknown>, state?: ProviderRunState, signal?: AbortSignal): AsyncIterable<StreamEvent>;
     private builtinTools;
     private requestExtensions;

package/dist/providers/openai-responses.js

@@ -6,6 +6,14 @@ import { endpointProfiles } from "./endpoints.js";
 import { OpenAIResponsesAdapter, } from "./openai-responses-adapter.js";
 import { circuitOpenError, classifyProviderError } from "./provider-error.js";
 export { OpenAIResponsesAdapter } from "./openai-responses-adapter.js";
+const OFFICIAL_OPENAI_RESPONSES_BASE_URL = "https://api.openai.com/v1";
+/** Params the official input-token count endpoint accepts (SDK `InputTokenCountParams`). The
+ * create plan is projected onto this set — remaining keys (max_output_tokens, store, …) cannot
+ * change the input token count — rather than maintaining a second serialization. */
+const INPUT_TOKEN_COUNT_PARAM_KEYS = [
+    "conversation", "input", "instructions", "model", "parallel_tool_calls",
+    "previous_response_id", "reasoning", "text", "tool_choice", "tools", "truncation",
+];
 export class OpenAIResponsesProvider {
     model;
     client;
@@ -14,6 +22,7 @@ export class OpenAIResponsesProvider {
     baseDelay;
     responses = new OpenAIResponsesAdapter();
     resolvedRuntimePolicy;
+    directNativeTokenCounting;
     resolvedRuntime;
     constructor(apiKey, model = "gpt-4.1", retry = { maxRetries: 3, baseDelay: 1000 }, baseURL = "https://api.openai.com/v1", runtimePolicy = {}, authMode = "api_key") {
         this.model = model;
@@ -26,6 +35,7 @@ export class OpenAIResponsesProvider {
         this.maxRetries = retry.maxRetries;
         this.baseDelay = retry.baseDelay;
         this.resolvedRuntimePolicy = runtimePolicy;
+        this.directNativeTokenCounting = baseURL.replace(/\/+$/, "") === OFFICIAL_OPENAI_RESPONSES_BASE_URL;
     }
     runtimePolicy() {
         return this.resolvedRuntimePolicy;
@@ -90,6 +100,29 @@ export class OpenAIResponsesProvider {
         }
         throw classifyProviderError("openai", lastError);
     }
+    /** spc_024-05: native preflight via the official Responses input-token count endpoint. Counts
+     * the exact create request plan (stateful `previous_response_id` continuation included) —
+     * native measurement belongs to the verified official endpoint, not the wire protocol. */
+    async countTokens(context, tools, extensions, state) {
+        const enabled = this.resolvedRuntime
+            ? this.resolvedRuntime.effectiveCapabilities.nativeTokenCounting.state === "supported"
+            : this.directNativeTokenCounting;
+        const inputTokens = this.client.responses.inputTokens;
+        if (!enabled || typeof inputTokens?.count !== "function") {
+            throw new Error("Native token counting is unavailable on this OpenAI-compatible endpoint");
+        }
+        const input = this.adapterInput(context, tools, extensions);
+        const plan = this.responses.buildRequest(input, this.asRunState(state));
+        const body = Object.fromEntries(INPUT_TOKEN_COUNT_PARAM_KEYS
+            .filter(key => key in plan.params)
+            .map(key => [key, plan.params[key]]));
+        const response = await inputTokens.count(body);
+        return {
+            inputTokens: response.input_tokens,
+            source: { kind: "native", provider: "openai" },
+            confidence: "exact",
+        };
+    }
     async *stream(context, tools, extensions, state, signal) {
         try {
             const runState = this.asRunState(state);

package/dist/providers/protocol-adapter.d.ts

@@ -30,5 +30,10 @@ export interface ProtocolAdapter<TRequest, TCompleteResponse, TStreamChunk, TStr
 }
 export declare class ProtocolResponseError extends Error {
     readonly protocol: GenerationProtocol;
-    constructor(protocol: GenerationProtocol, message: string);
+    readonly providerCode?: string;
+    readonly retryable?: boolean;
+    constructor(protocol: GenerationProtocol, message: string, options?: {
+        providerCode?: string;
+        retryable?: boolean;
+    });
 }

package/dist/providers/protocol-adapter.js

@@ -1,9 +1,13 @@
 export { GEMINI_PROTOCOL_CAPABILITIES, OLLAMA_PROTOCOL_CAPABILITIES, } from "./protocol-capabilities.js";
 export class ProtocolResponseError extends Error {
     protocol;
-    constructor(protocol, message) {
-        super(`${protocol} protocol response error: ${message}`);
+    providerCode;
+    retryable;
+    constructor(protocol, message, options = {}) {
+        super(options.providerCode ? message : `${protocol} protocol response error: ${message}`);
         this.name = "ProtocolResponseError";
         this.protocol = protocol;
+        this.providerCode = options.providerCode;
+        this.retryable = options.retryable;
     }
 }

package/dist/providers/provider-error.js

@@ -113,10 +113,14 @@ export function classifyProviderError(provider, error) {
     const httpStatus = errorStatus(error);
     const providerCode = errorCode(error);
     const kind = classifyKind(error, httpStatus, providerCode);
+    const explicitProtocolRetryable = kind === "protocol"
+        && typeof object(error)?.retryable === "boolean"
+        ? object(error).retryable
+        : undefined;
     return new ProviderError({
         provider,
         kind,
-        retryable: retryable(kind, httpStatus),
+        retryable: explicitProtocolRetryable ?? retryable(kind, httpStatus),
         message: errorMessage(error),
         ...(httpStatus !== undefined ? { httpStatus } : {}),
         ...(providerCode !== undefined ? { providerCode } : {}),

package/dist/providers/request-plan.d.ts

@@ -13,6 +13,7 @@ export interface ProviderRequestPlan {
     tools: ToolSchema[];
     options: Record<string, unknown>;
     fingerprint: string;
+    stablePrefixFingerprint: string;
 }
 export interface NormalizedProviderUsage extends ProviderUsage {
     /** Input not accounted as a cache read or write. `inputTokens` remains the full footprint. */
@@ -28,6 +29,8 @@ export interface RecordedPromptMeasurement {
     } | {
         kind: "local_exact";
         tokenizer: string;
+    } | {
+        kind: "postflight";
     } | {
         kind: "heuristic";
     };
@@ -56,7 +59,7 @@ export type CostObservation = {
     source: "unpriced";
     reason: "pricing_snapshot_not_effective" | "pricing_snapshot_expired" | "invalid_pricing_snapshot";
 };
-export declare function createProviderRequestPlan(input: Omit<ProviderRequestPlan, "fingerprint" | "options"> & {
+export declare function createProviderRequestPlan(input: Omit<ProviderRequestPlan, "fingerprint" | "stablePrefixFingerprint" | "options"> & {
     options?: Record<string, unknown>;
 }): ProviderRequestPlan;
 /** Build the plan from a resolved provider when the runner only has the public provider object. */

package/dist/providers/request-plan.js

@@ -13,7 +13,19 @@ export function createProviderRequestPlan(input) {
         tools: clone(input.tools),
         options,
     };
-    return { ...plan, fingerprint: sha256(stableJson(plan)) };
+    const stablePrefix = {
+        providerId: plan.providerId,
+        modelId: plan.modelId,
+        endpoint: plan.endpoint,
+        context: stablePrefixContext(plan.context),
+        tools: plan.tools,
+        options: plan.options,
+    };
+    return {
+        ...plan,
+        fingerprint: sha256(stableJson(plan)),
+        stablePrefixFingerprint: sha256(stableJson(stablePrefix)),
+    };
 }
 /** Build the plan from a resolved provider when the runner only has the public provider object. */
 export function createProviderRequestPlanForProvider(provider, context, tools, options) {
@@ -59,6 +71,8 @@ export function measurementForPlan(plan, recorded) {
         return clone(recorded);
     if (source.kind === "local_exact" && typeof source.tokenizer === "string" && source.tokenizer.length > 0)
         return clone(recorded);
+    if (source.kind === "postflight")
+        return clone(recorded);
     if (source.kind === "heuristic")
         return clone(recorded);
     return undefined;
@@ -155,6 +169,16 @@ function stableJson(value) {
     const object = value;
     return `{${Object.keys(object).sort().map(key => `${JSON.stringify(key)}:${stableJson(object[key])}`).join(",")}}`;
 }
+function stablePrefixContext(context) {
+    const frozenPrefixLen = context.frozenPrefixLen ?? 0;
+    return {
+        systemText: context.systemText,
+        ...(context.systemStable !== undefined ? { systemStable: context.systemStable } : {}),
+        ...(context.systemKnowledge !== undefined ? { systemKnowledge: context.systemKnowledge } : {}),
+        frozenPrefixLen,
+        turns: clone(context.turns.slice(0, frozenPrefixLen)),
+    };
+}
 function sha256(value) {
     return `sha256:${createHash("sha256").update(value).digest("hex")}`;
 }

package/dist/providers/usage-normalizer.js

@@ -1,7 +1,27 @@
 import { openAICachedPromptTokens } from "./base.js";
-function readNumber(obj, key) {
+import { ProtocolResponseError } from "./protocol-adapter.js";
+function readNumber(obj, key, protocol) {
     const value = obj?.[key];
-    return typeof value === "number" ? value : undefined;
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        throw new ProtocolResponseError(protocol, `usage.${key} must be a non-negative safe integer`);
+    }
+    return value;
+}
+function hasOwn(obj, key) {
+    return obj !== undefined && Object.prototype.hasOwnProperty.call(obj, key);
+}
+function openAICacheTelemetry(usage) {
+    const promptDetails = usage?.prompt_tokens_details;
+    const inputDetails = usage?.input_tokens_details;
+    if (hasOwn(usage, "prompt_cache_hit_tokens") || hasOwn(usage, "prompt_cache_miss_tokens")) {
+        return { cacheTelemetryStatus: "measured", cacheTelemetrySource: "deepseek_prompt_cache" };
+    }
+    if (hasOwn(promptDetails, "cached_tokens") || hasOwn(inputDetails, "cached_tokens")) {
+        return { cacheTelemetryStatus: "measured", cacheTelemetrySource: "openai_prompt_details" };
+    }
+    return { cacheTelemetryStatus: "unavailable" };
 }
 /**
  * Covers both OpenAI wire shapes actually in use: Chat Completions (`prompt_tokens`/
@@ -12,20 +32,34 @@ function readNumber(obj, key) {
  */
 export function normalizeOpenAIUsage(usage) {
     const u = usage && typeof usage === "object" ? usage : undefined;
-    const rawInput = readNumber(u, "prompt_tokens") ?? readNumber(u, "input_tokens");
-    const rawOutput = readNumber(u, "completion_tokens") ?? readNumber(u, "output_tokens");
+    const protocol = hasOwn(u, "input_tokens") ? "openai-responses" : "openai-chat";
+    const rawInput = readNumber(u, "prompt_tokens", protocol) ?? readNumber(u, "input_tokens", protocol);
+    const rawOutput = readNumber(u, "completion_tokens", protocol) ?? readNumber(u, "output_tokens", protocol);
     if (rawInput === undefined && rawOutput === undefined)
         return undefined;
     const inputTokens = rawInput ?? 0;
     const outputTokens = rawOutput ?? 0;
+    const promptDetails = u?.prompt_tokens_details;
+    const inputDetails = u?.input_tokens_details;
+    readNumber(promptDetails, "cached_tokens", protocol);
+    readNumber(inputDetails, "cached_tokens", protocol);
+    const cacheHit = readNumber(u, "prompt_cache_hit_tokens", protocol);
+    const cacheMiss = readNumber(u, "prompt_cache_miss_tokens", protocol);
     const cacheReadInputTokens = openAICachedPromptTokens(usage);
     const details = (u?.completion_tokens_details ?? u?.output_tokens_details);
-    const reasoningTokens = readNumber(details, "reasoning_tokens");
+    const reasoningTokens = readNumber(details, "reasoning_tokens", protocol);
+    if (cacheReadInputTokens > inputTokens) {
+        throw new ProtocolResponseError(protocol, "cache token subsets cannot exceed input tokens");
+    }
+    if (cacheHit !== undefined && cacheMiss !== undefined && cacheHit + cacheMiss !== inputTokens) {
+        throw new ProtocolResponseError(protocol, "DeepSeek cache hit and miss tokens must sum to prompt tokens");
+    }
     const providerUsage = {
         inputTokens,
         outputTokens,
         ...(cacheReadInputTokens > 0 ? { cacheReadInputTokens } : {}),
         ...(reasoningTokens !== undefined ? { reasoningTokens } : {}),
+        ...openAICacheTelemetry(u),
     };
     return providerUsage;
 }
@@ -42,10 +76,10 @@ export function normalizeOpenAIUsage(usage) {
  */
 export function normalizeAnthropicUsage(usage) {
     const u = usage && typeof usage === "object" ? usage : undefined;
-    const rawUncachedInput = readNumber(u, "input_tokens");
-    const rawCacheRead = readNumber(u, "cache_read_input_tokens");
-    const rawCacheCreation = readNumber(u, "cache_creation_input_tokens");
-    const rawOutput = readNumber(u, "output_tokens");
+    const rawUncachedInput = readNumber(u, "input_tokens", "anthropic-messages");
+    const rawCacheRead = readNumber(u, "cache_read_input_tokens", "anthropic-messages");
+    const rawCacheCreation = readNumber(u, "cache_creation_input_tokens", "anthropic-messages");
+    const rawOutput = readNumber(u, "output_tokens", "anthropic-messages");
     if (rawUncachedInput === undefined && rawCacheRead === undefined && rawCacheCreation === undefined && rawOutput === undefined)
         return undefined;
     const uncachedInput = rawUncachedInput ?? 0;
@@ -57,6 +91,9 @@ export function normalizeAnthropicUsage(usage) {
         outputTokens,
         ...(cacheReadInputTokens > 0 ? { cacheReadInputTokens } : {}),
         ...(cacheCreationInputTokens > 0 ? { cacheCreationInputTokens } : {}),
+        ...(hasOwn(u, "cache_read_input_tokens") || hasOwn(u, "cache_creation_input_tokens")
+            ? { cacheTelemetryStatus: "measured", cacheTelemetrySource: "anthropic_usage" }
+            : { cacheTelemetryStatus: "unavailable" }),
     };
     return providerUsage;
 }
@@ -67,17 +104,23 @@ export function normalizeAnthropicUsage(usage) {
  */
 export function normalizeGeminiUsage(usage) {
     const u = usage && typeof usage === "object" ? usage : undefined;
-    const rawInput = readNumber(u, "promptTokenCount");
-    const rawOutput = readNumber(u, "candidatesTokenCount");
+    const rawInput = readNumber(u, "promptTokenCount", "gemini");
+    const rawOutput = readNumber(u, "candidatesTokenCount", "gemini");
     if (rawInput === undefined && rawOutput === undefined)
         return undefined;
     const inputTokens = rawInput ?? 0;
     const outputTokens = rawOutput ?? 0;
-    const cacheReadInputTokens = readNumber(u, "cachedContentTokenCount");
+    const cacheReadInputTokens = readNumber(u, "cachedContentTokenCount", "gemini");
+    if ((cacheReadInputTokens ?? 0) > inputTokens) {
+        throw new ProtocolResponseError("gemini", "cache token subsets cannot exceed input tokens");
+    }
     const providerUsage = {
         inputTokens,
         outputTokens,
         ...(cacheReadInputTokens ? { cacheReadInputTokens } : {}),
+        ...(hasOwn(u, "cachedContentTokenCount")
+            ? { cacheTelemetryStatus: "measured", cacheTelemetrySource: "gemini_usage" }
+            : { cacheTelemetryStatus: "unavailable" }),
     };
     return providerUsage;
 }
@@ -88,9 +131,9 @@ export function normalizeGeminiUsage(usage) {
  */
 export function normalizeOllamaUsage(chunk) {
     const u = chunk && typeof chunk === "object" ? chunk : undefined;
-    const rawInput = readNumber(u, "prompt_eval_count");
-    const rawOutput = readNumber(u, "eval_count");
+    const rawInput = readNumber(u, "prompt_eval_count", "ollama-chat");
+    const rawOutput = readNumber(u, "eval_count", "ollama-chat");
     if (rawInput === undefined && rawOutput === undefined)
         return undefined;
-    return { inputTokens: rawInput ?? 0, outputTokens: rawOutput ?? 0 };
+    return { inputTokens: rawInput ?? 0, outputTokens: rawOutput ?? 0, cacheTelemetryStatus: "unavailable" };
 }

package/dist/runtime/provider-replay.d.ts

@@ -1,5 +1,9 @@
 import type { LLMProvider, Message, ProviderDescriptor, ProviderReplay, RenderedContext, ReplayabilityAssessment, ToolCall } from "../types.js";
 import type { SessionEvent } from "./session-log.js";
+export declare class ProviderReplayProtocolMismatchError extends Error {
+    readonly code: "provider_replay_protocol_mismatch";
+    constructor(provider: string, storedProtocol: string, resolvedProtocol: string);
+}
 export declare function assistantReplayKey(message: Pick<Message, "content" | "toolCalls">): string;
 /**
  * A stored replay may only be seeded into a provider speaking the same wire

package/dist/runtime/provider-replay.js

@@ -1,3 +1,11 @@
+export class ProviderReplayProtocolMismatchError extends Error {
+    code = "provider_replay_protocol_mismatch";
+    constructor(provider, storedProtocol, resolvedProtocol) {
+        super(`Stored ${storedProtocol} tool replay is incompatible with resolved ${provider}/${resolvedProtocol}; `
+            + `pin the previous ${storedProtocol} endpoint explicitly to resume this session`);
+        this.name = "ProviderReplayProtocolMismatchError";
+    }
+}
 function sortObjectKeys(val) {
     if (val === null || typeof val !== "object") {
         return val;
@@ -60,8 +68,14 @@ export function seedProviderReplayFromEvents(provider, events) {
             continue;
         const toolCalls = event.tool_calls ?? [];
         const stored = event.provider_replay;
-        if (!stored || !isReplayCompatibleWithProvider(stored, descriptor))
+        if (!stored)
             continue;
+        if (!isReplayCompatibleWithProvider(stored, descriptor)) {
+            if (toolCalls.length > 0 && descriptor) {
+                throw new ProviderReplayProtocolMismatchError(descriptor.provider, stored.protocol, descriptor.protocol);
+            }
+            continue;
+        }
         provider.seedProviderReplay({ content: event.content, toolCalls }, stored);
     }
 }

package/dist/runtime/runner.d.ts

@@ -56,11 +56,7 @@ export interface TurnMetrics {
     inputTokens: number;
     /** Tokens served from the prompt cache this turn (Anthropic `cache_read_input_tokens`). */
     cacheReadTokens: number;
-    /** I1: per-slot attribution of `cacheReadTokens`. Anthropic reports a single cache-read total,
-     *  not a per-block breakdown — this field is a pro-rata estimate over the slots that actually
-     *  carried a `cache_control` breakpoint on the request. Missing / empty when the provider does
-     *  not honor `cache_control` (OpenAI-family auto-cache) or when no breakpoints were placed.
-     *  Useful for diagnosing which slot is buying the cache hit when comparing strategies. */
+    /** Provider-authoritative per-slot attribution, when the endpoint reports one. */
     cacheReadTokensBySlot?: {
         system?: number;
         tools?: number;
@@ -68,6 +64,10 @@ export interface TurnMetrics {
     };
     /** Tokens written to the prompt cache this turn (Anthropic `cache_creation_input_tokens`). */
     cacheCreationTokens: number;
+    cacheTelemetryStatus?: "measured" | "unavailable";
+    cacheTelemetrySource?: "anthropic_usage" | "openai_prompt_details" | "deepseek_prompt_cache" | "gemini_usage";
+    requestFingerprint?: string;
+    stablePrefixFingerprint?: string;
 }
 /** O5: decision returned by `onToolCall` — `block: true` denies this call before it executes; the
  *  `reason` is fed back to the model as a governance-denied tool result (so it can redirect). */