@plurnk/plurnk-providers 1.6.0 → 1.7.0

package/src/providerError.ts

@@ -0,0 +1,139 @@
+import { Problems, type ProblemDetails } from "@plurnk/plurnk-contracts";
+import { providerSource } from "./notices.ts";
+import type { ProviderAttempt, ProviderRequestAccounting, ProviderRequestCapacity } from "./types.ts";
+
+export type ProviderErrorKind =
+    | "rate_limit"
+    | "network_failure"
+    | "deadline_exceeded"
+    | "model_refused"
+    | "invalid_response"
+    | "unauthorized"
+    | "quota_exceeded"
+    | "grammar_invalid"
+    | "capacity_exceeded"
+    | "resource_interrupted";
+
+const defaultStatus = (kind: ProviderErrorKind): number => {
+    switch (kind) {
+        case "unauthorized": return 401;
+        case "quota_exceeded": return 402;
+        case "capacity_exceeded": return 413;
+        case "rate_limit": return 429;
+        case "model_refused":
+        case "grammar_invalid": return 422;
+        case "invalid_response": return 502;
+        case "deadline_exceeded": return 504;
+        case "network_failure":
+        case "resource_interrupted": return 503;
+    }
+};
+
+const retryable = (kind: ProviderErrorKind): boolean => {
+    switch (kind) {
+        case "rate_limit":
+        case "network_failure":
+            return true;
+        case "deadline_exceeded":
+        case "invalid_response":
+        case "grammar_invalid":
+        case "capacity_exceeded":
+        case "resource_interrupted":
+        case "model_refused":
+        case "unauthorized":
+        case "quota_exceeded":
+            return false;
+    }
+};
+
+const buildProblem = (
+    source: string,
+    kind: ProviderErrorKind,
+    message: string,
+    status: number,
+    extensions: Readonly<Record<string, unknown>>,
+    retryableOverride: boolean | undefined,
+): ProblemDetails => {
+    const code: Record<ProviderErrorKind, string> = {
+        rate_limit: "rate-limit",
+        network_failure: "network-failure",
+        deadline_exceeded: "deadline-exceeded",
+        model_refused: "model-refused",
+        invalid_response: "invalid-response",
+        unauthorized: "unauthorized",
+        quota_exceeded: "quota-exceeded",
+        grammar_invalid: "grammar-invalid",
+        capacity_exceeded: "capacity-exceeded",
+        resource_interrupted: "resource-interrupted",
+    };
+    return Problems.create(source, code[kind], status, message, {
+        providerKind: kind,
+        stage: "provider-request",
+        retryable: retryableOverride ?? retryable(kind),
+        ...extensions,
+    });
+};
+
+// A provider operation failed before a completed exchange existed. An
+// interrupted response may still carry attempt evidence for its consumer.
+// The standardized Problem is the public failure contract; kind remains the
+// provider pool's routing discriminator and is repeated as a Problem extension.
+export class ProviderError extends Error {
+    readonly source: string;
+    readonly kind: ProviderErrorKind;
+    readonly problem: ProblemDetails;
+    readonly attempt?: ProviderAttempt;
+    readonly capacity?: ProviderRequestCapacity;
+    #accounting: ProviderRequestAccounting[];
+
+    constructor(
+        source: string,
+        kind: ProviderErrorKind,
+        message: string,
+        options: {
+            status?: number | null;
+            cause?: unknown;
+            retryable?: boolean;
+            extensions?: Readonly<Record<string, unknown>>;
+            attempt?: ProviderAttempt;
+            accounting?: readonly ProviderRequestAccounting[];
+            capacity?: ProviderRequestCapacity;
+        } = {},
+    ) {
+        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = "ProviderError";
+        this.source = providerSource(source);
+        this.kind = kind;
+        this.attempt = options.attempt;
+        this.capacity = options.capacity ?? options.attempt?.capacity;
+        this.#accounting = [...(options.accounting ?? options.attempt?.accounting ?? [])];
+        const status = options.status !== null && options.status !== undefined
+            && Number.isInteger(options.status) && options.status >= 400 && options.status <= 599
+            ? options.status
+            : defaultStatus(kind);
+        this.problem = buildProblem(
+            this.source,
+            kind,
+            message,
+            status,
+            options.extensions ?? {},
+            options.retryable,
+        );
+    }
+
+    get status(): number {
+        return this.problem.status;
+    }
+
+    get accounting(): readonly ProviderRequestAccounting[] {
+        return this.#accounting;
+    }
+
+    // A capacity pool adds the already-settled requests from prior backends as
+    // the same failure crosses that orchestration boundary.
+    prependAccounting(accounting: readonly ProviderRequestAccounting[]): void {
+        if (accounting.length > 0) this.#accounting = [...accounting, ...this.#accounting];
+    }
+}
+
+export type { ProviderAttempt, ProviderRequestAccounting, ProviderRequestCapacity } from "./types.ts";

package/src/sdkModels.test.ts

@@ -19,11 +19,8 @@ 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);
 });

package/src/sdkModels.ts

@@ -7,6 +7,7 @@ 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";
@@ -24,6 +25,7 @@ export type SdkModel = {
     readonly cacheAffinity?: CacheAffinity;
     readonly systemCacheProviderOptions?: AiSdkProviderOptions;
     readonly reasoningResponseProviderOptions?: AiSdkProviderOptions;
+    readonly additiveReasoningProvider?: "anthropic" | "bedrock";
     readonly catalog: ProviderInfo | null;
 };
 
@@ -162,24 +164,19 @@ export const createSdkModel = (
                 },
                 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}` },
-                },
+                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 } } }
                     : {}),
@@ -195,6 +192,7 @@ export const createSdkModel = (
                     apiKey: env.AWS_BEARER_TOKEN_BEDROCK,
                     baseURL: url,
                 }).languageModel(model),
+                additiveReasoningProvider: "bedrock",
                 catalog,
             };
         case "@openrouter/ai-sdk-provider":

package/src/types.ts

@@ -10,10 +10,8 @@ import type {
     PluginAttributionSource,
 } from "@plurnk/plurnk-meta";
 import type {
-    ProviderAccounting,
     ProviderCost,
     ProviderRequestAccounting,
-    ProviderUsage,
 } from "@plurnk/plurnk-contracts";
 
 export type {
@@ -46,8 +44,29 @@ export type PromptTokenMeasurement =
         readonly tokens: number;
         readonly source: string;
         readonly detail: string;
+    }
+    | {
+        readonly kind: "unavailable";
+        readonly source: string;
+        readonly detail: string;
     };
 
+export type ProviderRequestCapacityDecision = "admit" | "defer" | "reject";
+
+// Complete pre-I/O evidence for one logical request. `defer` is intentional:
+// an estimate or incomplete limit set cannot safely veto a request, so the
+// upstream provider remains the capacity oracle.
+export interface ProviderRequestCapacity {
+    readonly decision: ProviderRequestCapacityDecision;
+    readonly contextWindow: number | null;
+    readonly maxInputTokens: number | null;
+    readonly maxOutputTokens: number | null;
+    readonly outputBudget: number | null;
+    readonly reasoningBudget: number | null;
+    readonly inputCapacity: number | null;
+    readonly prompt: PromptTokenMeasurement;
+}
+
 export type ChargedCost = Extract<ProviderCost, { kind: "charged" }>;
 
 // Evidence exposed by the transport to the provider adapter that owns its
@@ -149,6 +168,7 @@ export interface ProviderResponse<TFinish extends ProviderAttemptFinishReason =
     // Ordered physical request evidence, including automatic retries and pool
     // failover that preceded this response. {§provider-request-accounting}
     readonly accounting: readonly ProviderRequestAccounting[];
+    readonly capacity: ProviderRequestCapacity;
     // {§gbnf-response-observation} — evidence only; the consumer owns the verdict.
     readonly grammarEvidence?: GrammarEvidence;
     // Per-turn provider→client metadata bag: the backend's non-standard top-level
@@ -179,7 +199,7 @@ export interface ProviderGenerateArgs {
     readonly primaryWorkerId?: string;
     readonly signal?: AbortSignal;
     readonly grammar?: string;
-    readonly maxTokens?: number;
+    readonly maxOutputTokens?: number;
     readonly attributions?: string[];
     readonly client?: string;
     readonly strikes?: number;
@@ -202,11 +222,9 @@ export interface Provider {
     // to constrain and which root variant to send is consumer policy
     // ({§gbnf-response-observation}).
     //
-    // `maxTokens` is the consumer's per-call output ceiling (wire `max_tokens`).
-    // Without it, most servers generate UNBOUNDED (llama-server n_predict -1) —
-    // under a multi-op grammar that degenerates to the context wall,
-    // so a constrained consumer is expected to pass it. Policy stays the
-    // consumer's; the provider only transports.
+    // `maxOutputTokens` may tighten the provider's configured total output
+    // budget for this call. It includes visible output and hidden reasoning;
+    // the adapter owns projection into each backend's native wire semantics.
     //
     // `workerId` is the REQUIRED, opaque, stable identity of the consumer's work
     // stream (loop/run). Providers MAY key backend affinity on it — e.g.
@@ -255,6 +273,11 @@ export interface Provider {
     // including any stricter operator cap. `null` means unknown; under
     // llama-server parallelism the probed natural value is per slot.
     readonly contextWindow: number | null;
+    readonly maxInputTokens: number | null;
+    readonly maxOutputTokens: number | null;
+    readonly outputBudget: number | null;
+    readonly reasoningBudget: number | null;
+    readonly inputCapacity: number | null;
     readonly model: string;
     // Optional: the backend's self-reported served model id, from a
     // /v1/models-shaped probe (llama-server today; any such backend). For a local
@@ -274,17 +297,16 @@ export interface Provider {
     // clamp an over-ask (fireworks/xai, verified live) never set this; undefined
     // = no claim. Introspectable so a consumer can refuse AT BOOT a local alias
     // with no declared envelope, instead of dying mid-turn in partition math.
-    readonly requiresMaxTokens?: boolean;
-    // Optional generation-envelope reserves ({§provider-generation-envelope}) — the amounts of
-    // the effective window reserved for reasoning and completion: floor
-    // percentages of `contextWindow`, or absolute per-alias pins that win
-    // outright. The consumer's prompt budget is `contextWindow - reasoningReserve
-    // - completionReserve - <its own packing-safety margin>`; the generation cap
-    // is the two pooled. `null` = underivable (window unknown, no absolute pin) →
-    // the consumer's no-cap path. Absent = a bare sibling makes NO claim (treated
-    // as null). All first-party providers claim, so null means genuinely-unknown.
-    readonly reasoningReserve?: number | null;
-    readonly completionReserve?: number | null;
+    readonly requiresOutputBudget?: boolean;
+    // The adapter owns request-specific physical admission. A proven fit may
+    // admit and an exact overflow may reject before I/O. Incomplete limits,
+    // estimates, bounds that do not prove fit, and unavailable measurements
+    // defer to the upstream provider as the capacity oracle.
+    assessRequestCapacity(
+        messages: readonly ChatMessage[],
+        maxOutputTokens?: number,
+        signal?: AbortSignal,
+    ): Promise<ProviderRequestCapacity>;
     // Provider-owned preflight measurement of the complete chat request,
     // including provider/template framing when the adapter can know it.
     // Estimates are explicit and MUST NOT authorize hard context-envelope admission.

package/src/usage.ts

@@ -199,6 +199,7 @@ export const normalizeUsage = (raw: RawUsage | null | undefined): ProviderUsage
 export type TokenRates = {
     input: number;
     output: number;
+    reasoning?: number;
     cacheRead?: number;
     cacheWrite?: number;
 };
@@ -235,17 +236,21 @@ export const calculateCostUsdDecimal = (
 
     const cacheReadRate = rates.cacheRead ?? rates.input;
     const cacheWriteRate = rates.cacheWrite ?? rates.input;
+    const reasoningRate = rates.reasoning ?? rates.output;
     const cacheReadTokens = usage.inputTokenDetails?.cacheReadTokens;
     const cacheWriteTokens = usage.inputTokenDetails?.cacheWriteTokens;
+    const reasoningTokens = usage.outputTokenDetails?.reasoningTokens;
     if (cacheReadRate !== rates.input && cacheReadTokens === undefined) return null;
     if (cacheWriteRate !== rates.input && cacheWriteTokens === undefined) return null;
+    if (reasoningRate !== rates.output && reasoningTokens === undefined) return null;
 
-    const parts = [rates.input, rates.output, cacheReadRate, cacheWriteRate].map(decimalParts);
+    const parts = [rates.input, rates.output, reasoningRate, cacheReadRate, cacheWriteRate].map(decimalParts);
     const rateScale = Math.max(...parts.map(({ scale }) => scale));
-    const [input, output, cacheRead, cacheWrite] = parts.map(({ coefficient, scale }) =>
+    const [input, output, reasoning, cacheRead, cacheWrite] = parts.map(({ coefficient, scale }) =>
         coefficient * 10n ** BigInt(rateScale - scale));
     const coefficient = BigInt(usage.inputTokens) * input!
         + BigInt(usage.outputTokens) * output!
+        + BigInt(reasoningTokens ?? 0) * (reasoning! - output!)
         + BigInt(cacheReadTokens ?? 0) * (cacheRead! - input!)
         + BigInt(cacheWriteTokens ?? 0) * (cacheWrite! - input!);
     if (coefficient < 0n) throw new TypeError("provider token-rate details produced a negative estimate");