@deepstrike/sdk 0.2.52 → 0.2.60

package/dist/providers/protocol-capabilities.js

@@ -0,0 +1,44 @@
+export const ANTHROPIC_PROTOCOL_CAPABILITIES = {
+    acceptedInputModalities: ["text", "image"],
+    emittedOutputModalities: ["text"],
+    tools: true,
+    parallelToolCalls: true,
+    structuredOutput: false,
+    reasoningReplay: "required",
+    promptCaching: true,
+    mediaForms: { imageUrl: true, imageBase64: true },
+};
+export const GEMINI_PROTOCOL_CAPABILITIES = {
+    acceptedInputModalities: ["text", "image", "audio"],
+    emittedOutputModalities: ["text"],
+    tools: true,
+    reasoningReplay: "none",
+    mediaForms: { imageUrl: true, imageBase64: true, audioBase64: true },
+};
+export const OLLAMA_PROTOCOL_CAPABILITIES = {
+    acceptedInputModalities: ["text", "image"],
+    emittedOutputModalities: ["text"],
+    tools: true,
+    reasoningReplay: "none",
+    mediaForms: { imageBase64: true },
+};
+export const OPENAI_RESPONSES_PROTOCOL_CAPABILITIES = {
+    acceptedInputModalities: ["text", "image", "file"],
+    emittedOutputModalities: ["text"],
+    tools: true,
+    parallelToolCalls: true,
+    structuredOutput: true,
+    reasoningReplay: "optional",
+    promptCaching: true,
+    mediaForms: { imageUrl: true, imageBase64: true, fileId: true },
+};
+export const OPENAI_CHAT_PROTOCOL_CAPABILITIES = {
+    acceptedInputModalities: ["text", "image", "audio"],
+    emittedOutputModalities: ["text"],
+    tools: true,
+    parallelToolCalls: true,
+    structuredOutput: true,
+    reasoningReplay: "optional",
+    promptCaching: true,
+    mediaForms: { imageUrl: true, imageBase64: true, audioBase64: true },
+};

package/dist/providers/provider-error.d.ts

@@ -0,0 +1,31 @@
+export type ProviderErrorKind = "transport" | "auth" | "rate_limit" | "context_overflow" | "invalid_request" | "modality" | "model_unavailable" | "protocol" | "unknown";
+export interface ProviderErrorOptions {
+    provider: string;
+    kind: ProviderErrorKind;
+    retryable: boolean;
+    message: string;
+    httpStatus?: number;
+    providerCode?: string;
+    cause?: unknown;
+}
+/** Stable provider-failure contract. Only the named scalar fields cross the host ABI. */
+export declare class ProviderError extends Error {
+    readonly provider: string;
+    readonly kind: ProviderErrorKind;
+    readonly retryable: boolean;
+    readonly httpStatus?: number;
+    readonly providerCode?: string;
+    readonly cause: unknown;
+    constructor(options: ProviderErrorOptions);
+}
+export declare function classifyProviderError(provider: string, error: unknown): ProviderError;
+export declare function circuitOpenError(provider: string): ProviderError;
+/** Safe scalar projection for runner → canonical-host events. */
+export declare function providerErrorEventFields(error: unknown): {
+    error_kind?: ProviderErrorKind;
+    retryable?: boolean;
+    http_status?: number;
+    provider_code?: string;
+};
+/** Provider errors expose their stable message without serializing the retained SDK cause. */
+export declare function providerErrorMessage(error: unknown, fallback: (value: unknown) => string): string;

package/dist/providers/provider-error.js

@@ -0,0 +1,149 @@
+/** Stable provider-failure contract. Only the named scalar fields cross the host ABI. */
+export class ProviderError extends Error {
+    provider;
+    kind;
+    retryable;
+    httpStatus;
+    providerCode;
+    cause;
+    constructor(options) {
+        super(options.message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "ProviderError";
+        this.provider = options.provider;
+        this.kind = options.kind;
+        this.retryable = options.retryable;
+        this.httpStatus = options.httpStatus;
+        this.providerCode = options.providerCode;
+        this.cause = options.cause;
+    }
+}
+const CONTEXT_OVERFLOW_CODES = new Set([
+    "context_length_exceeded",
+    "prompt_too_long",
+]);
+const NETWORK_CODES = new Set([
+    "ECONNABORTED",
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "ETIMEDOUT",
+]);
+function object(value) {
+    return value && typeof value === "object" ? value : undefined;
+}
+function scalarString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function scalarStatus(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 100 && value <= 599
+        ? value
+        : undefined;
+}
+function errorStatus(error) {
+    const outer = object(error);
+    const response = object(outer?.response);
+    return scalarStatus(outer?.httpStatus)
+        ?? scalarStatus(outer?.status)
+        ?? scalarStatus(response?.status);
+}
+function errorCode(error) {
+    const outer = object(error);
+    const nested = object(outer?.error);
+    const nestedError = object(nested?.error);
+    const body = object(outer?.body);
+    const bodyError = object(body?.error);
+    return scalarString(outer?.providerCode)
+        ?? scalarString(outer?.code)
+        ?? scalarString(outer?.error_code)
+        ?? scalarString(nested?.code)
+        ?? scalarString(nested?.error_code)
+        ?? scalarString(nestedError?.code)
+        ?? scalarString(nestedError?.error_code)
+        ?? scalarString(nestedError?.type)
+        ?? scalarString(bodyError?.code)
+        ?? scalarString(bodyError?.error_code);
+}
+function errorMessage(error) {
+    if (error instanceof Error && error.message)
+        return error.message;
+    return typeof error === "string" ? error : "Provider request failed";
+}
+function classifyKind(error, status, code) {
+    if (status === 413 || (code && CONTEXT_OVERFLOW_CODES.has(code.toLowerCase())))
+        return "context_overflow";
+    const name = error instanceof Error ? error.name : scalarString(object(error)?.name);
+    if (name === "UnsupportedModalityError")
+        return "modality";
+    if (name === "ProtocolResponseError")
+        return "protocol";
+    if (name === "ContentValidationError" || name === "ProviderReplayValidationError") {
+        return "invalid_request";
+    }
+    if (name === "APIConnectionError" || name === "APIConnectionTimeoutError")
+        return "transport";
+    if (status === 401 || status === 403)
+        return "auth";
+    if (status === 429)
+        return "rate_limit";
+    if (code === "model_not_found" || status === 404 || (status !== undefined && status >= 500)) {
+        return "model_unavailable";
+    }
+    if (status === 408 || status === 409)
+        return "transport";
+    if (status === 400 || status === 422)
+        return "invalid_request";
+    const normalizedCode = code?.toUpperCase();
+    if (normalizedCode && NETWORK_CODES.has(normalizedCode))
+        return "transport";
+    if (error instanceof TypeError && status === undefined)
+        return "transport";
+    return "unknown";
+}
+function retryable(kind, status) {
+    if (kind === "transport" || kind === "rate_limit" || kind === "model_unavailable")
+        return true;
+    if (kind === "unknown" && status !== undefined)
+        return status >= 500 && status !== 501;
+    return false;
+}
+export function classifyProviderError(provider, error) {
+    if (error instanceof ProviderError)
+        return error;
+    const httpStatus = errorStatus(error);
+    const providerCode = errorCode(error);
+    const kind = classifyKind(error, httpStatus, providerCode);
+    return new ProviderError({
+        provider,
+        kind,
+        retryable: retryable(kind, httpStatus),
+        message: errorMessage(error),
+        ...(httpStatus !== undefined ? { httpStatus } : {}),
+        ...(providerCode !== undefined ? { providerCode } : {}),
+        cause: error,
+    });
+}
+export function circuitOpenError(provider) {
+    return new ProviderError({
+        provider,
+        kind: "model_unavailable",
+        retryable: true,
+        providerCode: "circuit_open",
+        message: "Circuit breaker open",
+    });
+}
+/** Safe scalar projection for runner → canonical-host events. */
+export function providerErrorEventFields(error) {
+    if (!(error instanceof ProviderError))
+        return {};
+    return {
+        error_kind: error.kind,
+        retryable: error.retryable,
+        ...(error.httpStatus !== undefined ? { http_status: error.httpStatus } : {}),
+        ...(error.providerCode !== undefined ? { provider_code: error.providerCode } : {}),
+    };
+}
+/** Provider errors expose their stable message without serializing the retained SDK cause. */
+export function providerErrorMessage(error, fallback) {
+    return error instanceof ProviderError ? error.message : fallback(error);
+}

package/dist/providers/public.d.ts

@@ -3,8 +3,31 @@ export type { BackendProviderOptions } from "./factories.js";
 export { OpenAIChatProvider } from "./openai.js";
 export { CircuitBreaker } from "./base.js";
 export { OpenAIResponsesAdapter } from "./openai-responses.js";
-export type { OpenAIResponsesRunState } from "./openai-responses.js";
+export type { OpenAIResponsesRequestPlan, OpenAIResponsesRunState, OpenAIResponsesStreamState, } from "./openai-responses.js";
 export { OpenAIChatAdapter } from "./openai-chat.js";
-export { endpointProfiles, modelProfiles, getModelProfile } from "./profiles.js";
-export type { ModelProfileId, ProviderId } from "./profiles.js";
+export { openAIChatDialects } from "./openai-chat-dialects.js";
+export type { OpenAIChatDialectId, OpenAIChatWireDialect } from "./openai-chat-dialects.js";
+export { GeminiAdapter } from "./gemini-adapter.js";
+export { OllamaAdapter, OllamaNdjsonDecoder } from "./ollama-adapter.js";
+export type { GeminiRequestPlan, GeminiStreamState, } from "./gemini-adapter.js";
+export { ProtocolResponseError } from "./protocol-adapter.js";
+export { ProviderError, classifyProviderError, } from "./provider-error.js";
+export type { ProviderErrorKind, ProviderErrorOptions } from "./provider-error.js";
+export type { AdapterDecodeInput, AdapterOutput, AdapterStreamInput, CanonicalStopReason, ProtocolAdapter, } from "./protocol-adapter.js";
+export { endpointProfiles } from "./endpoints.js";
+export type { EndpointProfile, EndpointProfileId, EndpointProtocol, ProviderId } from "./endpoints.js";
+export { ContentPolicyError, contentDispositionFor } from "./content-policy.js";
+export type { ContentDisposition, ContentPlacement } from "./content-policy.js";
+export { CapabilityRouter } from "./capability-router.js";
+export type { CapabilityRequirement, CapabilityRouteResult } from "./capability-router.js";
+export { createProviderRequestPlan, createProviderRequestPlanForProvider, estimateProviderPromptTokens, measurementForPlan, normalizeProviderUsage, priceProviderUsage, recordPromptMeasurement } from "./request-plan.js";
+export type { CostObservation, NormalizedProviderUsage, PricingSnapshot, ProviderRequestEndpoint, ProviderRequestPlan, RecordedPromptMeasurement } from "./request-plan.js";
+export { CredentialResolutionError, OAuthCredentialResolver, redactCredential, resolveCredential } from "./credentials.js";
+export type { CredentialOptions, CredentialRequest, CredentialResolver, OAuthAccessToken, OAuthCredentialResolverOptions, OAuthRefreshRequest, ProviderCredential, } from "./credentials.js";
+export { DynamicModelCatalog, StaticModelCatalog } from "./model-catalog.js";
+export type { ModelCatalog, ModelCatalogRefreshResult, ModelCatalogSource } from "./model-catalog.js";
+export { modelRegistry, resolveEffectiveCapability } from "./model-registry.js";
+export { ContentValidationError, ToolResultProjectionConflictError, normalizeCanonicalContext, normalizeCanonicalAdapterInput, normalizeToolResultPart, projectToolOutputToText, validateCanonicalAdapterInput, } from "./content-normalization.js";
+export type { CanonicalAdapterInput, CanonicalMessage, CanonicalMessageBlock, CanonicalRenderedContext, CanonicalToolResult, } from "./content-normalization.js";
+export type { CapabilityState, EffectiveCapability, EffectiveModelCapabilities, GenerationProtocol, ModelDescriptor, ModelKind, ModelRegistration, ResolvedProviderRuntime, } from "./model-registry.js";
 export type { ProviderRunState, ProviderToolSpec, ProviderReplay, RenderedContext, CacheBreakpointStrategy } from "../types.js";

package/dist/providers/public.js

@@ -8,4 +8,16 @@ export { OpenAIChatProvider } from "./openai.js";
 export { CircuitBreaker } from "./base.js";
 export { OpenAIResponsesAdapter } from "./openai-responses.js";
 export { OpenAIChatAdapter } from "./openai-chat.js";
-export { endpointProfiles, modelProfiles, getModelProfile } from "./profiles.js";
+export { openAIChatDialects } from "./openai-chat-dialects.js";
+export { GeminiAdapter } from "./gemini-adapter.js";
+export { OllamaAdapter, OllamaNdjsonDecoder } from "./ollama-adapter.js";
+export { ProtocolResponseError } from "./protocol-adapter.js";
+export { ProviderError, classifyProviderError, } from "./provider-error.js";
+export { endpointProfiles } from "./endpoints.js";
+export { ContentPolicyError, contentDispositionFor } from "./content-policy.js";
+export { CapabilityRouter } from "./capability-router.js";
+export { createProviderRequestPlan, createProviderRequestPlanForProvider, estimateProviderPromptTokens, measurementForPlan, normalizeProviderUsage, priceProviderUsage, recordPromptMeasurement } from "./request-plan.js";
+export { CredentialResolutionError, OAuthCredentialResolver, redactCredential, resolveCredential } from "./credentials.js";
+export { DynamicModelCatalog, StaticModelCatalog } from "./model-catalog.js";
+export { modelRegistry, resolveEffectiveCapability } from "./model-registry.js";
+export { ContentValidationError, ToolResultProjectionConflictError, normalizeCanonicalContext, normalizeCanonicalAdapterInput, normalizeToolResultPart, projectToolOutputToText, validateCanonicalAdapterInput, } from "./content-normalization.js";

package/dist/providers/registry.d.ts

@@ -1,18 +1,19 @@
-import type { LLMProvider } from "../types.js";
+import type { LLMProvider, RuntimePolicy } from "../types.js";
+import type { EndpointProtocol, ProviderId } from "./endpoints.js";
 export type ProviderRetry = {
     maxRetries: number;
     baseDelay: number;
 };
-/** Constructs a provider for one `(providerId, endpointProtocol)` pair. The lambda absorbs the
- *  per-class constructor-shape differences (e.g. AnthropicProvider takes a `{ baseURL }` options
- *  object, the rest take a positional `baseURL` string). */
-export type ProviderMaker = (apiKey: string, model: string | undefined, retry: ProviderRetry | undefined, baseURL: string | undefined) => LLMProvider;
+/** Constructs a provider for one `(providerId, endpointProtocol)` pair. */
+export type ProviderMaker = (apiKey: string, model: string | undefined, retry: ProviderRetry | undefined, baseURL: string | undefined, runtimePolicy: RuntimePolicy | undefined, authMode?: "api_key" | "bearer") => LLMProvider;
 /** Build the registry key for a `(providerId, endpointProtocol)` pair. */
 export declare function providerRegistryKey(providerId: string, protocol: string): string;
+/** OAuth bearer is opt-in per provider/protocol. Compatible endpoints do not inherit this policy. */
+export declare function supportsBearerCredential(providerId: ProviderId, protocol: EndpointProtocol): boolean;
 /**
  * Single source of truth for which provider class backs each `(vendor, wire)` pair. Consumed by
  * both `createProvider` (catalog) and the per-backend factory functions, so the two can no longer
  * drift. Adding a vendor/wire = add a row here (+ its `vendor-profiles` / `endpointProfiles` data) —
- * no dispatch branch to edit. Values are the same named classes as before, so `instanceof` holds.
+ * no dispatch branch to edit. Compatible rows are generated from dialect/profile data.
  */
 export declare const PROVIDER_REGISTRY: Record<string, ProviderMaker>;

package/dist/providers/registry.js

@@ -1,35 +1,62 @@
 import { AnthropicProvider } from "./anthropic.js";
 import { OpenAIChatProvider } from "./openai.js";
 import { OpenAIResponsesProvider } from "./openai-responses.js";
-import { DeepSeekProvider, DeepSeekAnthropicProvider } from "./deepseek.js";
-import { KimiProvider, KimiAnthropicProvider } from "./kimi.js";
-import { QwenProvider, QwenAnthropicProvider } from "./qwen.js";
-import { GLMProvider, GLMAnthropicProvider } from "./glm.js";
-import { MiniMaxOpenAIProvider, MiniMaxAnthropicProvider } from "./minimax.js";
+import { AnthropicCompatibleProvider } from "./anthropic-compatible.js";
 import { GeminiProvider } from "./gemini.js";
+import { OllamaProvider } from "./ollama.js";
+import { openAIChatDialects } from "./openai-chat-dialects.js";
+import { endpointProfiles } from "./endpoints.js";
+import { anthropicVendorProfiles } from "./vendor-profiles.js";
 /** Build the registry key for a `(providerId, endpointProtocol)` pair. */
 export function providerRegistryKey(providerId, protocol) {
     return `${providerId}:${protocol}`;
 }
+/** OAuth bearer is opt-in per provider/protocol. Compatible endpoints do not inherit this policy. */
+export function supportsBearerCredential(providerId, protocol) {
+    return (providerId === "openai" && (protocol === "openai-chat" || protocol === "openai-responses"))
+        || (providerId === "anthropic" && protocol === "anthropic-messages");
+}
+function openAIChatMaker(dialectId) {
+    const dialect = openAIChatDialects[dialectId];
+    return (apiKey, model, retry, baseURL, runtimePolicy, authMode) => new OpenAIChatProvider({
+        apiKey,
+        model,
+        retry,
+        baseURL: baseURL ?? endpointProfiles[dialect.endpointId].baseURL,
+        runtimePolicy,
+        dialect,
+        authMode,
+    });
+}
+const openAIChatRegistry = Object.fromEntries(Object.values(openAIChatDialects).map(dialect => [
+    providerRegistryKey(dialect.providerId, "openai-chat"),
+    openAIChatMaker(dialect.id),
+]));
+function anthropicCompatibleMaker(vendorId) {
+    return (apiKey, model, retry, baseURL, runtimePolicy) => new AnthropicCompatibleProvider(anthropicVendorProfiles[vendorId], apiKey, model, retry, baseURL, runtimePolicy);
+}
 /**
  * Single source of truth for which provider class backs each `(vendor, wire)` pair. Consumed by
  * both `createProvider` (catalog) and the per-backend factory functions, so the two can no longer
  * drift. Adding a vendor/wire = add a row here (+ its `vendor-profiles` / `endpointProfiles` data) —
- * no dispatch branch to edit. Values are the same named classes as before, so `instanceof` holds.
+ * no dispatch branch to edit. Compatible rows are generated from dialect/profile data.
  */
 export const PROVIDER_REGISTRY = {
-    "anthropic:anthropic-messages": (k, m, r, b) => new AnthropicProvider(k, m, r, { baseURL: b }),
-    "openai:openai-chat": (k, m, r, b) => new OpenAIChatProvider(k, m, r, b),
-    "openai:openai-responses": (k, m, r, b) => new OpenAIResponsesProvider(k, m, r, b),
-    "deepseek:openai-chat": (k, m, r, b) => new DeepSeekProvider(k, m, r, b),
-    "deepseek:anthropic-messages": (k, m, r, b) => new DeepSeekAnthropicProvider(k, m, r, b),
-    "kimi:openai-chat": (k, m, r, b) => new KimiProvider(k, m, r, b),
-    "kimi:anthropic-messages": (k, m, r, b) => new KimiAnthropicProvider(k, m, r, b),
-    "qwen:openai-chat": (k, m, r, b) => new QwenProvider(k, m, r, b),
-    "qwen:anthropic-messages": (k, m, r, b) => new QwenAnthropicProvider(k, m, r, b),
-    "glm:openai-chat": (k, m, r, b) => new GLMProvider(k, m, r, b),
-    "glm:anthropic-messages": (k, m, r, b) => new GLMAnthropicProvider(k, m, r, b),
-    "minimax:openai-chat": (k, m, r, b) => new MiniMaxOpenAIProvider(k, m, r, b),
-    "minimax:anthropic-messages": (k, m, r, b) => new MiniMaxAnthropicProvider(k, m, r, b),
-    "gemini:gemini": (k, m, r, b) => new GeminiProvider(k, m, r, b),
+    "anthropic:anthropic-messages": (k, m, r, b, p, authMode) => new AnthropicProvider({
+        apiKey: k,
+        model: m,
+        retry: r,
+        baseURL: b,
+        ...(p ? { runtimePolicy: p } : {}),
+        ...(authMode === "bearer" ? { authMode: "bearer" } : {}),
+    }),
+    "openai:openai-responses": (k, m, r, b, p, authMode) => new OpenAIResponsesProvider(k, m, r, b, p, authMode),
+    "deepseek:anthropic-messages": anthropicCompatibleMaker("deepseek"),
+    "kimi:anthropic-messages": anthropicCompatibleMaker("kimi"),
+    "qwen:anthropic-messages": anthropicCompatibleMaker("qwen"),
+    "glm:anthropic-messages": anthropicCompatibleMaker("glm"),
+    "minimax:anthropic-messages": anthropicCompatibleMaker("minimax"),
+    "gemini:gemini": (k, m, r, b, p) => new GeminiProvider(k, m, r, b, p),
+    "ollama:ollama-chat": (_k, m, _r, b, p) => new OllamaProvider(m, b, p),
+    ...openAIChatRegistry,
 };

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

@@ -0,0 +1,86 @@
+import type { RenderedContext, ToolSchema, ProviderUsage } from "../types.js";
+export interface ProviderRequestEndpoint {
+    id: string;
+    protocol: string;
+    baseURL: string;
+}
+/** One provider-visible request, deliberately excluding credentials and transport-only retries. */
+export interface ProviderRequestPlan {
+    providerId: string;
+    modelId: string;
+    endpoint: ProviderRequestEndpoint;
+    context: RenderedContext;
+    tools: ToolSchema[];
+    options: Record<string, unknown>;
+    fingerprint: string;
+}
+export interface NormalizedProviderUsage extends ProviderUsage {
+    /** Input not accounted as a cache read or write. `inputTokens` remains the full footprint. */
+    uncachedInputTokens: number;
+}
+/** Durable host fact: a specific logical request was counted before execution. */
+export interface RecordedPromptMeasurement {
+    requestFingerprint: string;
+    inputTokens: number;
+    source: {
+        kind: "native";
+        provider: string;
+    } | {
+        kind: "local_exact";
+        tokenizer: string;
+    } | {
+        kind: "heuristic";
+    };
+    confidence: "exact" | "high_confidence" | "low_confidence";
+}
+export interface PricingSnapshot {
+    version: string;
+    currency: string;
+    region: string;
+    effectiveFrom: string;
+    expiresAt?: string;
+    ratesPerMillion: {
+        input: number;
+        output: number;
+        cacheRead?: number;
+        cacheCreation?: number;
+        reasoning?: number;
+    };
+}
+export type CostObservation = {
+    source: "snapshot";
+    currency: string;
+    amount: number;
+    pricingVersion: string;
+} | {
+    source: "unpriced";
+    reason: "pricing_snapshot_not_effective" | "pricing_snapshot_expired" | "invalid_pricing_snapshot";
+};
+export declare function createProviderRequestPlan(input: Omit<ProviderRequestPlan, "fingerprint" | "options"> & {
+    options?: Record<string, unknown>;
+}): ProviderRequestPlan;
+/** Build the plan from a resolved provider when the runner only has the public provider object. */
+export declare function createProviderRequestPlanForProvider(provider: {
+    descriptor?(): {
+        provider: string;
+        protocol: string;
+        model: string;
+    };
+    requestPlanIdentity?(): {
+        providerId?: string;
+        modelId?: string;
+        endpoint?: {
+            id?: string;
+            protocol?: string;
+            baseURL?: string;
+        };
+    };
+}, context: RenderedContext, tools: ToolSchema[], options?: Record<string, unknown>): ProviderRequestPlan;
+export declare function estimateProviderPromptTokens(context: RenderedContext, tools: ToolSchema[]): number;
+/** Bind a preflight count to its exact provider-visible request. Replay only reuses matching facts. */
+export declare function recordPromptMeasurement(plan: Pick<ProviderRequestPlan, "fingerprint">, measurement: Omit<RecordedPromptMeasurement, "requestFingerprint">): RecordedPromptMeasurement;
+export declare function measurementForPlan(plan: Pick<ProviderRequestPlan, "fingerprint">, recorded: RecordedPromptMeasurement | undefined): RecordedPromptMeasurement | undefined;
+/** Normalize postflight provider facts without turning estimates into actual usage. */
+export declare function normalizeProviderUsage(usage: ProviderUsage): NormalizedProviderUsage;
+/** Cost is derived only from an explicit, time-valid host snapshot; otherwise it stays unknown. */
+export declare function priceProviderUsage(usage: NormalizedProviderUsage, snapshot: PricingSnapshot, observedAt?: string | Date): CostObservation;

package/dist/providers/request-plan.js

@@ -0,0 +1,175 @@
+import { createHash } from "node:crypto";
+const TRANSPORT_ONLY_KEYS = new Set([
+    "apiKey", "api_key", "bearerToken", "bearer_token", "authorization", "credential",
+    "credentials", "retry", "maxRetries", "baseDelay", "timeout", "signal", "access_token", "refresh_token", "token", "secret", "x-api-key",
+]);
+export function createProviderRequestPlan(input) {
+    const options = materialOptions(input.options ?? {});
+    const plan = {
+        providerId: input.providerId,
+        modelId: input.modelId,
+        endpoint: sanitizeEndpoint(input.endpoint),
+        context: clone(input.context),
+        tools: clone(input.tools),
+        options,
+    };
+    return { ...plan, fingerprint: sha256(stableJson(plan)) };
+}
+/** Build the plan from a resolved provider when the runner only has the public provider object. */
+export function createProviderRequestPlanForProvider(provider, context, tools, options) {
+    const descriptor = provider.descriptor?.() ?? { provider: "unknown", protocol: "unknown", model: "unknown" };
+    const identity = provider.requestPlanIdentity?.();
+    return createProviderRequestPlan({
+        providerId: identity?.providerId ?? descriptor.provider,
+        modelId: identity?.modelId ?? descriptor.model,
+        endpoint: {
+            id: identity?.endpoint?.id ?? `${descriptor.provider}.${descriptor.protocol}`,
+            protocol: identity?.endpoint?.protocol ?? descriptor.protocol,
+            baseURL: identity?.endpoint?.baseURL ?? "",
+        },
+        context,
+        tools,
+        options,
+    });
+}
+export function estimateProviderPromptTokens(context, tools) {
+    const bytes = new TextEncoder().encode(stableJson({ context, tools })).byteLength;
+    return Math.max(1, Math.ceil(bytes / 4));
+}
+/** Bind a preflight count to its exact provider-visible request. Replay only reuses matching facts. */
+export function recordPromptMeasurement(plan, measurement) {
+    return {
+        requestFingerprint: plan.fingerprint,
+        inputTokens: requireNonNegativeInteger(measurement.inputTokens, "inputTokens"),
+        source: clone(measurement.source),
+        confidence: measurement.confidence,
+    };
+}
+export function measurementForPlan(plan, recorded) {
+    if (!recorded || recorded.requestFingerprint !== plan.fingerprint)
+        return undefined;
+    if (!Number.isSafeInteger(recorded.inputTokens) || recorded.inputTokens < 0)
+        return undefined;
+    if (recorded.confidence !== "exact" && recorded.confidence !== "high_confidence" && recorded.confidence !== "low_confidence")
+        return undefined;
+    const source = recorded.source;
+    if (!source || typeof source !== "object")
+        return undefined;
+    if (source.kind === "native" && typeof source["provider"] === "string" && source["provider"].length > 0)
+        return clone(recorded);
+    if (source.kind === "local_exact" && typeof source.tokenizer === "string" && source.tokenizer.length > 0)
+        return clone(recorded);
+    if (source.kind === "heuristic")
+        return clone(recorded);
+    return undefined;
+}
+/** Normalize postflight provider facts without turning estimates into actual usage. */
+export function normalizeProviderUsage(usage) {
+    const inputTokens = requireNonNegativeInteger(usage.inputTokens, "inputTokens");
+    const outputTokens = requireNonNegativeInteger(usage.outputTokens, "outputTokens");
+    const cacheReadInputTokens = optionalNonNegativeInteger(usage.cacheReadInputTokens, "cacheReadInputTokens");
+    const cacheCreationInputTokens = optionalNonNegativeInteger(usage.cacheCreationInputTokens, "cacheCreationInputTokens");
+    const reasoningTokens = optionalNonNegativeInteger(usage.reasoningTokens, "reasoningTokens");
+    const cached = (cacheReadInputTokens ?? 0) + (cacheCreationInputTokens ?? 0);
+    if (cached > inputTokens)
+        throw new RangeError("cache token subsets cannot exceed inputTokens");
+    if (reasoningTokens !== undefined && reasoningTokens > outputTokens) {
+        throw new RangeError("reasoningTokens must be a subset of outputTokens");
+    }
+    return {
+        inputTokens,
+        uncachedInputTokens: inputTokens - cached,
+        outputTokens,
+        ...(cacheReadInputTokens !== undefined ? { cacheReadInputTokens } : {}),
+        ...(cacheCreationInputTokens !== undefined ? { cacheCreationInputTokens } : {}),
+        ...(reasoningTokens !== undefined ? { reasoningTokens } : {}),
+    };
+}
+/** Cost is derived only from an explicit, time-valid host snapshot; otherwise it stays unknown. */
+export function priceProviderUsage(usage, snapshot, observedAt = new Date()) {
+    const at = typeof observedAt === "string" ? new Date(observedAt) : observedAt;
+    const from = new Date(snapshot.effectiveFrom);
+    const expires = snapshot.expiresAt ? new Date(snapshot.expiresAt) : undefined;
+    const rates = snapshot.ratesPerMillion;
+    const requiredRates = [rates.input, rates.output];
+    if (!snapshot.version || !snapshot.currency || Number.isNaN(at.valueOf()) || Number.isNaN(from.valueOf())
+        || requiredRates.some(rate => typeof rate !== "number" || !Number.isFinite(rate) || rate < 0)
+        || Object.values(rates).some(rate => typeof rate !== "number" || !Number.isFinite(rate) || rate < 0)) {
+        return { source: "unpriced", reason: "invalid_pricing_snapshot" };
+    }
+    if (at < from)
+        return { source: "unpriced", reason: "pricing_snapshot_not_effective" };
+    if (expires && (Number.isNaN(expires.valueOf()) || at >= expires)) {
+        return { source: "unpriced", reason: "pricing_snapshot_expired" };
+    }
+    const amount = (usage.uncachedInputTokens * rates.input
+        + usage.outputTokens * rates.output
+        + (usage.cacheReadInputTokens ?? 0) * (rates.cacheRead ?? rates.input)
+        + (usage.cacheCreationInputTokens ?? 0) * (rates.cacheCreation ?? rates.input)
+        + (usage.reasoningTokens ?? 0) * (rates.reasoning ?? 0)) / 1_000_000;
+    return { source: "snapshot", currency: snapshot.currency, amount, pricingVersion: snapshot.version };
+}
+function materialOptions(options) {
+    return sanitizeMaterialValue(options);
+}
+function sanitizeEndpoint(endpoint) {
+    try {
+        const url = new URL(endpoint.baseURL);
+        url.username = "";
+        url.password = "";
+        url.search = "";
+        url.hash = "";
+        return { ...clone(endpoint), baseURL: url.toString().replace(/\/$/, "") };
+    }
+    catch {
+        return { ...clone(endpoint), baseURL: "" };
+    }
+}
+function sanitizeMaterialValue(value) {
+    if (value === undefined || typeof value === "function")
+        return undefined;
+    if (Array.isArray(value))
+        return value.map(sanitizeMaterialValue).filter(item => item !== undefined);
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.keys(value).sort().flatMap(key => {
+            if (TRANSPORT_ONLY_KEYS.has(key) || isTransportOnlyKey(key))
+                return [];
+            const sanitized = sanitizeMaterialValue(value[key]);
+            return sanitized === undefined ? [] : [[key, sanitized]];
+        }));
+    }
+    return value;
+}
+function isTransportOnlyKey(key) {
+    const normalized = key.toLowerCase().replace(/[^a-z0-9]/g, "");
+    return normalized.includes("authorization") || normalized.includes("credential")
+        || normalized.includes("accesstoken") || normalized.includes("refreshtoken")
+        || normalized.includes("apikey") || normalized === "bearer" || normalized === "token"
+        || normalized === "secret" || normalized === "xapikey";
+}
+function stableJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    const object = value;
+    return `{${Object.keys(object).sort().map(key => `${JSON.stringify(key)}:${stableJson(object[key])}`).join(",")}}`;
+}
+function sha256(value) {
+    return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+function clone(value) {
+    if (value === undefined || value === null || typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map(clone);
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, clone(item)]));
+}
+function requireNonNegativeInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new RangeError(`${name} must be a non-negative safe integer`);
+    return value;
+}
+function optionalNonNegativeInteger(value, name) {
+    return value === undefined ? undefined : requireNonNegativeInteger(value, name);
+}