@plurnk/plurnk-providers 1.5.0 → 1.6.1

package/src/index.ts

@@ -10,14 +10,24 @@ export type {
     ProviderOptions,
     ProviderResponse,
     ProviderEncryptedReasoningItem,
+    ProviderAccounting,
+    ProviderCost,
+    ProviderCostNormalizer,
+    ProviderCallKind,
+    ProviderGenerateArgs,
+    ProviderRequestAccounting,
+    ProviderRequestCapacity,
+    ProviderRequestCapacityDecision,
+    ProviderRequestIdentity,
+    ProviderRequestObserver,
+    ProviderRequestSettlement,
     ProviderUsage,
     PromptTokenMeasurement,
     TokenLogprob,
     TokenAlternative,
-    AuthoritativeCharge,
 } from "./types.ts";
-export type { ProviderCost } from "@plurnk/plurnk-contracts";
 export { assertPromptTokenMeasurement } from "./promptTokens.ts";
+export { assessRequestCapacity, effectiveInputCapacity, effectiveOutputBudget, requestCapacityDecision } from "./capacity.ts";
 
 // Alias cascade — re-exported from the zero-dep @plurnk/plurnk-aliases, so
 // the "." surface is unchanged for existing importers and there's one source of
@@ -43,16 +53,25 @@ export type { AiSdkProviderConfig, ReasoningStyle, GrammarStyle } from "./AiSdkP
 // DECISION stays the consumer's, by choosing which pool to call.
 export { default as Pool } from "./Pool.ts";
 export type { ProviderFetch } from "./AiSdkProvider.ts";
-export { parseRequiredInt, parseOptionalInt, parseRequiredFloat, parseOptionalFloat, requireEnv, reasoningFromEnv, reasoningResponseStyleFromEnv, scopeEnvToAlias, dataCaptureFromEnv, contextWindowFromEnv, effectiveContextWindow, envelopeFromEnv, resolveReserve, PROVIDERS_KNOBS } from "./env.ts";
-export type { Reasoning, ReasoningMode, ReasoningResponseStyle, ReserveSpec } from "./env.ts";
-export { normalizeUsage, calculateCostUsd, calculateCostUsdDecimal } from "./usage.ts";
+export { parseRequiredInt, parseOptionalInt, parseRequiredFloat, parseOptionalFloat, requireEnv, reasoningFromEnv, reasoningResponseStyleFromEnv, scopeEnvToAlias, dataCaptureFromEnv, contextWindowFromEnv, effectiveContextWindow, generationEnvelopeFromEnv, resolveGenerationEnvelopeFromEnv, resolveTokenBudget, PROVIDERS_KNOBS } from "./env.ts";
+export type { GenerationEnvelope, Reasoning, ReasoningMode, ReasoningResponseStyle, TokenBudgetSpec } from "./env.ts";
+export { normalizeUsage, calculateCostUsdDecimal, validateProviderUsage } from "./usage.ts";
 export {
-    providerCostFor,
+    addDecimals,
+    estimateProviderCost,
     providerCostUsd,
     resolveProviderCost,
-    validateAuthoritativeCharge,
+    sumProviderCostsUsd,
+    validateChargedCost,
+    validateDecimal,
     validateProviderCost,
 } from "./cost.ts";
+export {
+    aggregateProviderAccounting,
+    plurnkCostNormalizer,
+    providerCostNormalizer,
+    validateProviderRequestAccounting,
+} from "./accounting.ts";
 export type { RawUsage, TokenRates } from "./usage.ts";
 export { ProviderError, classifyProviderError, toProviderError } from "./errors.ts";
 export { providerSource } from "./notices.ts";

package/src/ollama.test.ts

@@ -4,16 +4,18 @@ import { ollamaProviderFromEnv } from "./ollama.ts";
 
 const env = Object.freeze({
     PLURNK_PROVIDERS_FETCH_TIMEOUT: "1000",
+    PLURNK_PROVIDERS_OPERATION_TIMEOUT: "3000",
+    PLURNK_PROVIDERS_FIRST_CONTENT_TIMEOUT: "1000",
     PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT: "0",
     PLURNK_PROVIDERS_REASONING: "off",
     PLURNK_PROVIDERS_TEMPERATURE: "0.2",
     PLURNK_PROVIDERS_REPEAT_PENALTY: "1.15",
     PLURNK_PROVIDERS_FREQUENCY_PENALTY: "0",
-    PLURNK_PROVIDERS_REASONING_RESERVE: "10%",
-    PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%",
+    PLURNK_PROVIDERS_OUTPUT_BUDGET: "35%",
     PLURNK_PROVIDERS_RETRY_ATTEMPTS: "0",
     PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT: "512",
-    PLURNK_PROVIDERS_PROMPT_CACHE_KEY: "1",
+    PLURNK_PROVIDERS_CACHE_AFFINITY: "1",
+    PLURNK_PROVIDERS_CACHE_WRITE_POLICY: "stable-system",
 });
 
 test.afterEach(() => mock.restoreAll());

package/src/ollama.ts

@@ -1,5 +1,5 @@
 import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
-import { contextWindowFromEnv, effectiveContextWindow, parseRequiredInt, requireEnv } from "./env.ts";
+import { contextWindowFromEnv, effectiveContextWindow, parseTimeoutMs, requireEnv } from "./env.ts";
 import { providerFromSdkModel } from "./catalogProvider.ts";
 import type { Provider, ProviderOptions } from "./types.ts";
 
@@ -20,7 +20,7 @@ const fetchContextWindow = async ({
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ model }),
-        signal: AbortSignal.timeout(timeout),
+        ...(timeout > 0 ? { signal: AbortSignal.timeout(timeout) } : {}),
     });
     if (!response.ok) throw new Error(`ollama provider: /api/show returned ${response.status}`);
     const data = await response.json() as ShowResponse;
@@ -41,7 +41,7 @@ export const ollamaProviderFromEnv = async (
         "OLLAMA_BASE_URL or OLLAMA_HOST (or a PLURNK_BASEURL_<alias> override)",
         "ollama",
     ).replace(/\/+$/, "").replace(/\/v1$/, "");
-    const timeout = parseRequiredInt(
+    const timeout = parseTimeoutMs(
         env.PLURNK_PROVIDERS_FETCH_TIMEOUT,
         "PLURNK_PROVIDERS_FETCH_TIMEOUT",
         "ollama",

package/src/promptTokens.ts

@@ -4,6 +4,7 @@ const KINDS = new Set<PromptTokenMeasurement["kind"]>([
     "exact",
     "upper_bound",
     "estimate",
+    "unavailable",
 ]);
 
 export const assertPromptTokenMeasurement = (
@@ -13,19 +14,21 @@ export const assertPromptTokenMeasurement = (
     if (typeof value !== "object" || value === null) {
         throw new TypeError(`${owner}: prompt token measurement must be an object`);
     }
-    const candidate = value as Partial<PromptTokenMeasurement>;
-    if (!KINDS.has(candidate.kind as PromptTokenMeasurement["kind"])) {
+    const candidate = value as Record<string, unknown>;
+    const kind = candidate.kind as PromptTokenMeasurement["kind"];
+    if (!KINDS.has(kind)) {
         throw new TypeError(`${owner}: prompt token measurement has invalid kind ${JSON.stringify(candidate.kind)}`);
     }
-    if (!Number.isInteger(candidate.tokens) || candidate.tokens! < 0) {
+    if (kind !== "unavailable"
+        && (!Number.isInteger(candidate.tokens) || (candidate.tokens as number) < 0)) {
         throw new TypeError(`${owner}: prompt token measurement tokens must be a non-negative integer`);
     }
     if (typeof candidate.source !== "string" || candidate.source.length === 0) {
         throw new TypeError(`${owner}: prompt token measurement source must be a non-empty string`);
     }
-    if (candidate.kind === "estimate"
+    if ((kind === "estimate" || kind === "unavailable")
         && (typeof candidate.detail !== "string" || candidate.detail.length === 0)) {
-        throw new TypeError(`${owner}: estimated prompt token measurement requires detail`);
+        throw new TypeError(`${owner}: ${kind} prompt token measurement requires detail`);
     }
     return value as PromptTokenMeasurement;
 };

package/src/sdkModels.test.ts

@@ -19,12 +19,31 @@ test("createSdkModel uses Models.dev provider facts and operator credentials", (
     const sdk = createSdkModel("xai", "grok-build-0.1", { XAI_API_KEY: "test-key" });
     assert.notEqual(sdk, null);
     assert.equal(sdk?.catalog?.npm, "@ai-sdk/xai");
-    assert.equal(sdk?.languageModel, undefined);
-    assert.deepEqual(sdk?.compatible, {
-        url: "https://api.x.ai/v1/chat/completions",
-        headers: { Authorization: "Bearer test-key" },
+    assert.notEqual(sdk?.languageModel, undefined);
+    assert.equal(sdk?.compatible, undefined);
+    assert.deepEqual(sdk?.cacheAffinity, { target: "header", name: "x-grok-conv-id" });
+    assert.notEqual(sdk?.normalizeCost, undefined);
+});
+
+test("createSdkModel constructs Cerebras from Models.dev facts", () => {
+    const sdk = createSdkModel("cerebras", "gemma-4-31b", {
+        CEREBRAS_API_KEY: "test-key",
     });
-    assert.notEqual(sdk?.normalizeCharge, undefined);
+    assert.notEqual(sdk, null);
+    assert.equal(sdk?.catalog?.npm, "@ai-sdk/cerebras");
+    assert.notEqual(sdk?.languageModel, undefined);
+    assert.equal(sdk?.compatible, undefined);
+});
+
+test("the Google SDK adapter owns its readable-reasoning response projection", () => {
+    assert.deepEqual(
+        createSdkModel("google", "gemini-3.7-flash", { GEMINI_API_KEY: "test-key" })?.reasoningResponseProviderOptions,
+        { google: { thinkingConfig: { includeThoughts: true } } },
+    );
+    assert.equal(
+        createSdkModel("cerebras", "gemma-4-31b", { CEREBRAS_API_KEY: "test-key" })?.reasoningResponseProviderOptions,
+        undefined,
+    );
 });
 
 test("createSdkModel attaches DeepInfra's documented response-cost normalizer", () => {
@@ -32,13 +51,12 @@ test("createSdkModel attaches DeepInfra's documented response-cost normalizer",
         DEEPINFRA_API_KEY: "test-key",
     });
     assert.notEqual(sdk?.languageModel, undefined);
-    assert.deepEqual(sdk?.normalizeCharge?.({
+    assert.deepEqual(sdk?.normalizeCost?.({
         usage: { estimated_cost: 5.04e-5 },
         response: { id: "response-1" },
     }), {
-        kind: "authoritative",
+        kind: "estimated",
         amount: { amount: "0.0000504", currency: "USD" },
-        usdEquivalent: "0.0000504",
         source: "DeepInfra response usage.estimated_cost",
     });
 });
@@ -54,6 +72,57 @@ test("createSdkModel expands catalog endpoint variables without treating them as
         url: "https://api.cloudflare.com/client/v4/accounts/account/ai/v1/chat/completions",
         headers: { Authorization: "Bearer token" },
     });
+    assert.deepEqual(sdk?.cacheAffinity, { target: "header", name: "x-session-affinity" });
+});
+
+test("catalog routes own their documented cache-affinity request projection", () => {
+    assert.deepEqual(
+        createSdkModel("openai", "gpt-4.1-mini", { OPENAI_API_KEY: "key" })?.cacheAffinity,
+        { target: "provider-option", provider: "openai", name: "promptCacheKey" },
+    );
+    assert.deepEqual(
+        createSdkModel("deepinfra", "zai-org/GLM-5.2", { DEEPINFRA_API_KEY: "key" })?.cacheAffinity,
+        { target: "provider-option", provider: "deepinfra", name: "prompt_cache_key" },
+    );
+    assert.deepEqual(
+        createSdkModel("openrouter", "openai/gpt-5", { OPENROUTER_API_KEY: "key" })?.cacheAffinity,
+        { target: "header", name: "x-session-id" },
+    );
+    assert.deepEqual(
+        createSdkModel("fireworks", "accounts/fireworks/models/test", { FIREWORKS_API_KEY: "key" })?.cacheAffinity,
+        { target: "body", name: "prompt_cache_key" },
+    );
+});
+
+test("explicit stable-system cache breakpoints exist only on supported Claude routes", () => {
+    const cacheControl = { type: "ephemeral" };
+    assert.deepEqual(
+        createSdkModel("anthropic", "claude-sonnet-4-6", { ANTHROPIC_API_KEY: "key" })?.systemCacheProviderOptions,
+        { anthropic: { cacheControl } },
+    );
+    assert.deepEqual(
+        createSdkModel("openrouter", "anthropic/claude-sonnet-4.6", { OPENROUTER_API_KEY: "key" })?.systemCacheProviderOptions,
+        { openrouter: { cacheControl } },
+    );
+    assert.equal(
+        createSdkModel("openrouter", "openai/gpt-5", { OPENROUTER_API_KEY: "key" })?.systemCacheProviderOptions,
+        undefined,
+    );
+    assert.equal(
+        createSdkModel("deepseek", "deepseek-v4-flash", { DEEPSEEK_API_KEY: "key" })?.systemCacheProviderOptions,
+        undefined,
+    );
+});
+
+test("an operator-declared compatible provider receives no guessed cache extension", () => {
+    const sdk = createSdkModel("acme", "model", {
+        ACME_API_KEY: "key",
+        PLURNK_PROVIDERS_PROVIDER_ACME_NPM: "@ai-sdk/openai-compatible",
+        PLURNK_PROVIDERS_PROVIDER_ACME_BASE_URL: "https://api.acme.test/v1",
+        PLURNK_PROVIDERS_PROVIDER_ACME_API_KEY_ENV: "ACME_API_KEY",
+    });
+    assert.equal(sdk?.cacheAffinity, undefined);
+    assert.equal(sdk?.systemCacheProviderOptions, undefined);
 });
 
 test("#157: a cataloged compatible provider fails before transport when its declared credential is absent", () => {

package/src/sdkModels.ts

@@ -1,27 +1,36 @@
 import { createAmazonBedrock } from "@ai-sdk/amazon-bedrock";
 import { createAnthropic } from "@ai-sdk/anthropic";
+import { createCerebras } from "@ai-sdk/cerebras";
 import { createDeepInfra } from "@ai-sdk/deepinfra";
 import { createGoogle } from "@ai-sdk/google";
 import { createGroq } from "@ai-sdk/groq";
 import { createMistral } from "@ai-sdk/mistral";
 import { createOpenAI } from "@ai-sdk/openai";
 import { createTogetherAI } from "@ai-sdk/togetherai";
+import { createXai } from "@ai-sdk/xai";
 import { createOpenRouter } from "@openrouter/ai-sdk-provider";
 import { lookupProvider, type ProviderInfo } from "@plurnk/plurnk-models";
 import type { LanguageModel } from "ai";
-import { authoritativeChargeNormalizer } from "./accounting.ts";
-import type { AuthoritativeChargeNormalizer } from "./types.ts";
+import { providerCostNormalizer } from "./accounting.ts";
+import type { AiSdkProviderOptions, CacheAffinity } from "./AiSdkProvider.ts";
+import type { ProviderCostNormalizer } from "./types.ts";
 
 export type SdkModel = {
     readonly languageModel?: LanguageModel;
-    readonly normalizeCharge?: AuthoritativeChargeNormalizer;
+    readonly normalizeCost?: ProviderCostNormalizer;
     readonly compatible?: {
         readonly url: string;
         readonly headers: Readonly<Record<string, string>>;
     };
+    readonly cacheAffinity?: CacheAffinity;
+    readonly systemCacheProviderOptions?: AiSdkProviderOptions;
+    readonly reasoningResponseProviderOptions?: AiSdkProviderOptions;
+    readonly additiveReasoningProvider?: "anthropic" | "bedrock";
     readonly catalog: ProviderInfo | null;
 };
 
+const cacheControl = { type: "ephemeral" as const };
+
 const envPrefix = (provider: string): string =>
     provider.replaceAll(/[^a-zA-Z0-9]/g, "_").toUpperCase();
 
@@ -107,12 +116,15 @@ export const createSdkModel = (
     const catalog = lookupProvider(provider) ?? configuredProviderInfo(provider, env);
     if (catalog === null) return null;
     const url = baseUrl(provider, env, catalog, baseUrlOverride);
-    const normalizeCharge = authoritativeChargeNormalizer(catalog.npm);
+    const normalizeCost = providerCostNormalizer(catalog.npm);
 
     switch (catalog.npm) {
         case "@ai-sdk/openai":
             return {
                 languageModel: createOpenAI({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).chat(model),
+                ...(catalog.id === "openai"
+                    ? { cacheAffinity: { target: "provider-option" as const, provider: "openai", name: "promptCacheKey" } }
+                    : {}),
                 catalog,
             };
         case "@ai-sdk/groq":
@@ -120,6 +132,11 @@ export const createSdkModel = (
                 languageModel: createGroq({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).languageModel(model),
                 catalog,
             };
+        case "@ai-sdk/cerebras":
+            return {
+                languageModel: createCerebras({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).languageModel(model),
+                catalog,
+            };
         case "@ai-sdk/mistral":
             return {
                 languageModel: createMistral({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).languageModel(model),
@@ -133,29 +150,36 @@ export const createSdkModel = (
         case "@ai-sdk/deepinfra":
             return {
                 languageModel: createDeepInfra({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).languageModel(model),
-                ...(normalizeCharge === undefined ? {} : { normalizeCharge }),
+                ...(normalizeCost === undefined ? {} : { normalizeCost }),
+                ...(catalog.id === "deepinfra"
+                    ? { cacheAffinity: { target: "provider-option" as const, provider: "deepinfra", name: "prompt_cache_key" } }
+                    : {}),
                 catalog,
             };
         case "@ai-sdk/google":
             return {
                 languageModel: createGoogle({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).languageModel(model),
+                reasoningResponseProviderOptions: {
+                    google: { thinkingConfig: { includeThoughts: true } },
+                },
                 catalog,
             };
-        case "@ai-sdk/xai": {
-            const key = requireApiKey(provider, env, catalog);
-            const compatibleBase = url ?? "https://api.x.ai/v1";
+        case "@ai-sdk/xai":
             return {
-                compatible: {
-                    url: `${compatibleBase}/chat/completions`,
-                    headers: { Authorization: `Bearer ${key}` },
-                },
-                ...(normalizeCharge === undefined ? {} : { normalizeCharge }),
+                languageModel: createXai({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).chat(model),
+                ...(catalog.id === "xai"
+                    ? { cacheAffinity: { target: "header" as const, name: "x-grok-conv-id" } }
+                    : {}),
+                ...(normalizeCost === undefined ? {} : { normalizeCost }),
                 catalog,
             };
-        }
         case "@ai-sdk/anthropic":
             return {
                 languageModel: createAnthropic({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).languageModel(model),
+                additiveReasoningProvider: "anthropic",
+                ...(catalog.id === "anthropic"
+                    ? { systemCacheProviderOptions: { anthropic: { cacheControl } } }
+                    : {}),
                 catalog,
             };
         case "@ai-sdk/amazon-bedrock":
@@ -168,6 +192,7 @@ export const createSdkModel = (
                     apiKey: env.AWS_BEARER_TOKEN_BEDROCK,
                     baseURL: url,
                 }).languageModel(model),
+                additiveReasoningProvider: "bedrock",
                 catalog,
             };
         case "@openrouter/ai-sdk-provider":
@@ -180,7 +205,13 @@ export const createSdkModel = (
                         ...(env.OPENROUTER_X_TITLE === undefined ? {} : { "X-Title": env.OPENROUTER_X_TITLE }),
                     },
                 }).languageModel(model),
-                ...(normalizeCharge === undefined ? {} : { normalizeCharge }),
+                ...(catalog.id === "openrouter"
+                    ? { cacheAffinity: { target: "header" as const, name: "x-session-id" } }
+                    : {}),
+                ...(catalog.id === "openrouter" && model.replace(/^~/, "").startsWith("anthropic/")
+                    ? { systemCacheProviderOptions: { openrouter: { cacheControl } } }
+                    : {}),
+                ...(normalizeCost === undefined ? {} : { normalizeCost }),
                 catalog,
             };
         case "@ai-sdk/openai-compatible":
@@ -194,6 +225,11 @@ export const createSdkModel = (
                         ? {}
                         : { Authorization: `Bearer ${key}` },
                 },
+                ...(catalog.id === "cloudflare-workers-ai"
+                    ? { cacheAffinity: { target: "header" as const, name: "x-session-affinity" } }
+                    : catalog.id === "fireworks-ai"
+                        ? { cacheAffinity: { target: "body" as const, name: "prompt_cache_key" } }
+                        : {}),
                 catalog,
             };
         default: