@plurnk/plurnk-providers 1.6.0 → 1.7.0

package/src/env.ts

@@ -113,20 +113,14 @@ export function effectiveContextWindow(operatorCap: number | null, naturalWindow
             : Math.min(operatorCap, naturalWindow);
 }
 
-// {§provider-generation-envelope} How much of a
-// effective context window is reserved for reasoning and for completion — the
-// remainder (minus the consumer's own packing-safety margin) is the prompt
-// gauge. Provider-owned: the window is the effective hard envelope and these are
-// amounts OF it. Each knob accepts a percentage of the window
-// ("10%") or an absolute token count ("4096"); the floor ships percentages so
-// every window-advertising endpoint (llama-server n_ctx, the plurnk.ai router,
-// a cataloged cloud model) arrives at sane defaults with ZERO operator tuning.
-// Per-alias suffixes override for measured envelopes; absolutes win over the
-// window derivation entirely.
-export type ReserveSpec = { percent: number } | { tokens: number };
+// {§provider-generation-envelope} Generation has one total output budget. An
+// optional reasoning budget is a subset, never an additive second reserve.
+// Percentages are of the effective context window; absolutes remain useful for
+// measured local deployments. Physical model limits always cap operator policy.
+export type TokenBudgetSpec = { percent: number } | { tokens: number };
 
-const parseReserve = (raw: string | undefined, name: string, label: string): ReserveSpec => {
-    if (raw === undefined || raw.length === 0) throw new Error(`${label} provider: ${name} must be set (a percentage of the window like "10%", or an absolute token count)`);
+const parseTokenBudget = (raw: string | undefined, name: string, label: string): TokenBudgetSpec => {
+    if (raw === undefined || raw.length === 0) throw new Error(`${label} provider: ${name} must be set (a percentage of the context window like "35%", or an absolute token count)`);
     const pct = /^([0-9]+(?:\.[0-9]+)?)%$/.exec(raw);
     if (pct !== null) {
         const p = Number(pct[1]);
@@ -138,37 +132,110 @@ const parseReserve = (raw: string | undefined, name: string, label: string): Res
     return { tokens: n };
 };
 
-export const envelopeFromEnv = (env: NodeJS.ProcessEnv, label: string): { reasoningReserve: ReserveSpec; completionReserve: ReserveSpec } => ({
-    reasoningReserve: parseReserve(env.PLURNK_PROVIDERS_REASONING_RESERVE, "PLURNK_PROVIDERS_REASONING_RESERVE", label),
-    completionReserve: parseReserve(env.PLURNK_PROVIDERS_COMPLETION_RESERVE, "PLURNK_PROVIDERS_COMPLETION_RESERVE", label),
-});
-
-// Resolve a ReserveSpec against a known window: absolutes stand alone; a
+// Resolve a token budget against a known window: absolutes stand alone; a
 // percentage needs the window (null when unknown — the underivable/no-cap case).
-export const resolveReserve = (spec: ReserveSpec, window: number | null): number | null =>
-    "tokens" in spec ? spec.tokens : window === null ? null : Math.round(spec.percent * window);
+export const resolveTokenBudget = (spec: TokenBudgetSpec, window: number | null): number | null =>
+    "tokens" in spec
+        ? spec.tokens
+        : window === null
+            ? null
+            : Math.max(1, Math.round(spec.percent * window));
 
-// TOLERANT envelope read for fixtures + consumers that resolve reserves against
-// a known window and treat ABSENCE as "no claim" (null), never fail-hard —
-// unlike envelopeFromEnv (the REQUIRED provider path, fed by the shipped floor).
-// Mock uses this so the service's partition/budget suite drives the SAME
-// env→reserve resolution a real provider does, without the floor. An invalid
-// value still throws (a malformed reserve is an error, not an absence).
-export const resolveEnvelopeFromEnv = (env: NodeJS.ProcessEnv, window: number | null): { reasoningReserve: number | null; completionReserve: number | null } => {
-    const one = (raw: string | undefined, name: string): number | null =>
-        raw === undefined || raw.length === 0 ? null : resolveReserve(parseReserve(raw, name, "mock"), window);
-    return {
-        reasoningReserve: one(env.PLURNK_PROVIDERS_REASONING_RESERVE, "PLURNK_PROVIDERS_REASONING_RESERVE"),
-        completionReserve: one(env.PLURNK_PROVIDERS_COMPLETION_RESERVE, "PLURNK_PROVIDERS_COMPLETION_RESERVE"),
-    };
+export type GenerationEnvelope = {
+    readonly outputBudget: number | null;
+    readonly reasoningBudget: number | null;
+};
+
+const shedRetiredEnvelope = (env: NodeJS.ProcessEnv, label: string): void => {
+    for (const name of ["PLURNK_PROVIDERS_REASONING_RESERVE", "PLURNK_PROVIDERS_COMPLETION_RESERVE"] as const) {
+        if (env[name] !== undefined && env[name] !== "") {
+            throw new Error(
+                `${label} provider: ${name} is retired; reasoning is now a subset of the total generation envelope. Replace the old pair with PLURNK_PROVIDERS_OUTPUT_BUDGET and optional PLURNK_PROVIDERS_REASONING_BUDGET ({§provider-generation-envelope})`,
+            );
+        }
+    }
+};
+
+const optionalTokenBudget = (
+    raw: string | undefined,
+    name: string,
+    label: string,
+): TokenBudgetSpec | null => raw === undefined || raw.length === 0
+    ? null
+    : parseTokenBudget(raw, name, label);
+
+const resolveGeneration = (
+    outputSpec: TokenBudgetSpec | null,
+    reasoningSpec: TokenBudgetSpec | null,
+    contextWindow: number | null,
+    maxOutputTokens: number | null,
+    label: string,
+): GenerationEnvelope => {
+    const requestedOutput = outputSpec === null ? null : resolveTokenBudget(outputSpec, contextWindow);
+    const physicalCaps = [contextWindow, maxOutputTokens].filter((value): value is number => value !== null);
+    const outputBudget = requestedOutput === null
+        ? null
+        : Math.min(requestedOutput, ...physicalCaps);
+    if (contextWindow !== null && outputBudget !== null && outputBudget >= contextWindow) {
+        throw new Error(
+            `${label} provider: PLURNK_PROVIDERS_OUTPUT_BUDGET (${outputBudget}) must leave positive input capacity inside the context window (${contextWindow})`,
+        );
+    }
+    const reasoningBudget = reasoningSpec === null
+        ? null
+        : resolveTokenBudget(reasoningSpec, contextWindow);
+    if (reasoningBudget !== null && outputBudget === null) {
+        throw new Error(
+            `${label} provider: PLURNK_PROVIDERS_REASONING_BUDGET requires a resolved PLURNK_PROVIDERS_OUTPUT_BUDGET; reasoning is a subset of total output`,
+        );
+    }
+    if (reasoningBudget !== null && outputBudget !== null && reasoningBudget >= outputBudget) {
+        throw new Error(
+            `${label} provider: PLURNK_PROVIDERS_REASONING_BUDGET (${reasoningBudget}) exceeds the effective PLURNK_PROVIDERS_OUTPUT_BUDGET (${outputBudget}); reasoning is a subset of total output`,
+        );
+    }
+    return { outputBudget, reasoningBudget };
+};
+
+// Standard providers receive the shipped OUTPUT_BUDGET floor and fail hard if
+// it is absent. Mock uses the tolerant sibling below so ordinary unit fixtures
+// make no generation claim unless a test deliberately configures one.
+export const generationEnvelopeFromEnv = (
+    env: NodeJS.ProcessEnv,
+    label: string,
+    contextWindow: number | null,
+    maxOutputTokens: number | null,
+): GenerationEnvelope => {
+    shedRetiredEnvelope(env, label);
+    return resolveGeneration(
+        parseTokenBudget(env.PLURNK_PROVIDERS_OUTPUT_BUDGET, "PLURNK_PROVIDERS_OUTPUT_BUDGET", label),
+        optionalTokenBudget(env.PLURNK_PROVIDERS_REASONING_BUDGET, "PLURNK_PROVIDERS_REASONING_BUDGET", label),
+        contextWindow,
+        maxOutputTokens,
+        label,
+    );
+};
+
+export const resolveGenerationEnvelopeFromEnv = (
+    env: NodeJS.ProcessEnv,
+    contextWindow: number | null,
+    maxOutputTokens: number | null = null,
+): GenerationEnvelope => {
+    shedRetiredEnvelope(env, "mock");
+    return resolveGeneration(
+        optionalTokenBudget(env.PLURNK_PROVIDERS_OUTPUT_BUDGET, "PLURNK_PROVIDERS_OUTPUT_BUDGET", "mock"),
+        optionalTokenBudget(env.PLURNK_PROVIDERS_REASONING_BUDGET, "PLURNK_PROVIDERS_REASONING_BUDGET", "mock"),
+        contextWindow,
+        maxOutputTokens,
+        "mock",
+    );
 };
 
 // {§provider-configuration} The side-channel reasoning knobs — activation and budget
 // are separate vars, so a numeric budget can never silently flip wire flags:
 //   PLURNK_PROVIDERS_REASONING           off | adaptive | on   (REQUIRED, fail-hard)
-//   PLURNK_PROVIDERS_REASONING_BUDGET  optional positive int when REASONING=on —
-//     an explicit magnitude for tier/budget mapping. On llama-server it is the
-//     request-scoped allowance and cannot exceed the physical reasoning reserve.
+//   PLURNK_PROVIDERS_REASONING_BUDGET  optional reasoning subset of the total
+//     output budget, used for tier/budget mapping where the backend supports it.
 // The provider maps intent to the backend's mechanism; the consumer states
 // intent, never mechanism. PLAN is a separate public intended-goals record.
 export type ReasoningMode = "off" | "adaptive" | "on";
@@ -189,20 +256,18 @@ export const reasoningResponseStyleFromEnv = (
     return raw;
 };
 
-export const reasoningFromEnv = (env: NodeJS.ProcessEnv, label: string): Reasoning => {
+export const reasoningFromEnv = (
+    env: NodeJS.ProcessEnv,
+    label: string,
+    resolvedBudget: number | null = null,
+): Reasoning => {
     shedRenamed(env, "PLURNK_PROVIDERS_THINKING", "PLURNK_PROVIDERS_REASONING", label, "provider configuration contract"); // lexicon-allow
     shedRenamed(env, "PLURNK_PROVIDERS_THINKING_CAPACITY", "PLURNK_PROVIDERS_REASONING_BUDGET", label, "provider configuration contract"); // lexicon-allow
     const name = "PLURNK_PROVIDERS_REASONING";
     const raw = env[name];
     if (raw === undefined || raw.length === 0) throw new Error(`${label} provider: ${name} must be set (off | adaptive | on)`);
     if (raw !== "off" && raw !== "adaptive" && raw !== "on") throw new Error(`${label} provider: ${name} must be one of "off", "adaptive", "on" (got "${raw}")`);
-    if (raw !== "on") return { mode: raw, budget: null };
-    const capName = "PLURNK_PROVIDERS_REASONING_BUDGET";
-    const capRaw = env[capName];
-    if (capRaw === undefined || capRaw.length === 0) return { mode: "on", budget: null };
-    const n = Number(capRaw);
-    if (!Number.isInteger(n) || n <= 0) throw new Error(`${label} provider: ${capName} must be a positive integer (got "${capRaw}")`);
-    return { mode: "on", budget: n };
+    return { mode: raw, budget: raw === "off" ? null : resolvedBudget };
 };
 
 // ── Per-alias knob scoping (per-alias scoping doctrine, user 2026-07-03): PLURNK_PROVIDERS_<KNOB>[_<alias>] ──
@@ -213,8 +278,7 @@ export const reasoningFromEnv = (env: NodeJS.ProcessEnv, label: string): Reasoni
 // facts (API keys, canonical endpoints) remain vendor-named; the per-alias
 // endpoint override stays PLURNK_BASEURL_<alias> (its existing precedent).
 export const PROVIDERS_KNOBS = Object.freeze([
-    "PLURNK_PROVIDERS_REASONING_RESERVE",
-    "PLURNK_PROVIDERS_COMPLETION_RESERVE",
+    "PLURNK_PROVIDERS_OUTPUT_BUDGET",
     "PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE",
     "PLURNK_PROVIDERS_REASONING_BUDGET",
     "PLURNK_PROVIDERS_REASONING",
@@ -250,10 +314,9 @@ export const PROVIDERS_KNOBS = Object.freeze([
 // single overlay.
 //
 // `knobs` (optional) lets a CONSUMER scope its OWN closed knob list with this
-// same parser — e.g. the service's window-partition vars (PLURNK_SERVICE_CONTEXT_WINDOW/
-// MAX_TURNS/...), so a 64k cloud envelope and a 12k gemma envelope
-// coexist per-alias without the service reimplementing the suffix/collision
-// rules. Default stays the providers-family list; my call sites pass nothing.
+// same parser — e.g. service loop policy or prompt projection — without
+// reimplementing the suffix/collision rules. Default stays the
+// providers-family list; provider call sites pass nothing.
 export const scopeEnvToAlias = (env: NodeJS.ProcessEnv, alias: string, knobs: readonly string[] = PROVIDERS_KNOBS): NodeJS.ProcessEnv => {
     const folded = alias.toLowerCase();
     const out: NodeJS.ProcessEnv = { ...env };

package/src/errors.test.ts

@@ -33,10 +33,29 @@ test("classifyProviderError maps HTTP status to kind", () => {
     assert.equal(k(409), "network_failure");
     assert.equal(k(500), "network_failure");
     assert.equal(k(503), "network_failure");
+    assert.equal(k(413), "capacity_exceeded");
     assert.equal(k(400), "invalid_response");
     assert.equal(k(404), "invalid_response");
 });
 
+test("capacity normalization prefers structured provider codes and keeps generic 400s distinct", () => {
+    const openai = apiError(400, JSON.stringify({
+        error: {
+            type: "invalid_request_error",
+            code: "context_length_exceeded",
+            message: "maximum context length exceeded",
+        },
+    }));
+    assert.equal(classifyProviderError(openai).kind, "capacity_exceeded");
+    const normalized = toProviderError(openai, "provider:openai");
+    assert.equal(normalized.status, 413);
+    assert.equal(normalized.problem.capacityStage, "upstream");
+    assert.equal(normalized.problem.providerStatus, 400);
+    assert.equal(classifyProviderError(apiError(400, JSON.stringify({
+        error: { type: "invalid_request_error", code: "bad_temperature", message: "bad temperature" },
+    }))).kind, "invalid_response");
+});
+
 test("provider retry directives survive HTTP failure normalization", () => {
     const final = new APICallError({
         message: "edge router says not to replay",
@@ -101,6 +120,20 @@ test("#161: ProviderError carries resource-interrupted attempt evidence outside
             usage: { inputTokens: 3, outputTokens: 1, totalTokens: 4 },
             cost: { kind: "unknown", reason: "fixture has no monetary evidence" },
         }],
+        capacity: {
+            decision: "defer",
+            contextWindow: null,
+            maxInputTokens: null,
+            maxOutputTokens: null,
+            outputBudget: null,
+            reasoningBudget: null,
+            inputCapacity: null,
+            prompt: {
+                kind: "unavailable",
+                source: "fixture",
+                detail: "the interrupted fixture has no preflight measurement",
+            },
+        },
     } as ProviderAttempt;
     const error = new ProviderError(
         "provider:deepseek",

package/src/errors.ts

@@ -1,18 +1,10 @@
-import { Problems, type ProblemDetails } from "@plurnk/plurnk-contracts";
 import { APICallError, RetryError } from "ai";
-import { providerSource } from "./notices.ts";
-import type { ProviderAttempt, ProviderRequestAccounting } from "./types.ts";
+import { ProviderError } from "./providerError.ts";
+import type { ProviderErrorKind } from "./providerError.ts";
+import type { ProviderRequestCapacity } from "./types.ts";
 
-export type ProviderErrorKind =
-    | "rate_limit"
-    | "network_failure"
-    | "deadline_exceeded"
-    | "model_refused"
-    | "invalid_response"
-    | "unauthorized"
-    | "quota_exceeded"
-    | "grammar_invalid"
-    | "resource_interrupted";
+export { ProviderError } from "./providerError.ts";
+export type { ProviderErrorKind } from "./providerError.ts";
 
 export interface ClassifiedProviderError {
     kind: ProviderErrorKind;
@@ -54,131 +46,23 @@ export const providerTimeoutOf = (error: unknown): ProviderTimeoutError | null =
     return null;
 };
 
-const defaultStatus = (kind: ProviderErrorKind): number => {
-    switch (kind) {
-        case "unauthorized": return 401;
-        case "quota_exceeded": return 402;
-        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 "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",
-        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;
-    #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[];
-        } = {},
-    ) {
-        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
-        this.name = "ProviderError";
-        this.source = providerSource(source);
-        this.kind = kind;
-        this.attempt = options.attempt;
-        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];
-    }
-}
-
-const wireErrorType = (body: string): string | null => {
+const wireError = (body: string): { type: string | null; code: string | null; message: string | null } => {
     try {
         const { error } = JSON.parse(body) as { error?: { type?: unknown } };
-        return typeof error?.type === "string" ? error.type : null;
+        const record = error as { type?: unknown; code?: unknown; message?: unknown } | undefined;
+        return {
+            type: typeof record?.type === "string" ? record.type : null,
+            code: typeof record?.code === "string" || typeof record?.code === "number" ? String(record.code) : null,
+            message: typeof record?.message === "string" ? record.message : null,
+        };
     } catch {
-        return null;
+        return { type: null, code: null, message: null };
     }
 };
 
+const CAPACITY_CODE = /^(?:context_length_exceeded|context_window_exceeded|input_too_long|prompt_too_long|request_too_large|token_limit_exceeded|max_tokens_exceeded)$/i;
+const CAPACITY_MESSAGE = /(?:maximum context length|context (?:length|window).*(?:exceed|too (?:large|long)|maximum)|(?:input|prompt|request).*(?:token|length|size).*(?:exceed|too (?:large|long)|maximum))/i;
+
 const preview = (value: unknown, limit: number | undefined): string => {
     const text = value instanceof Error ? value.message : String(value);
     return limit !== undefined && text.length > limit
@@ -215,6 +99,7 @@ export const classifyProviderError = (
             ? preview(err.message, detailLimit)
             : "The provider request failed without a diagnostic message.";
         const body = err.responseBody ?? "";
+        const wire = wireError(body);
         if (status === 401 || status === 403) return { kind: "unauthorized", message };
         if (status === 402) return { kind: "quota_exceeded", message };
         if (status === 429) return { kind: "rate_limit", message, retryable: err.isRetryable };
@@ -223,7 +108,21 @@ export const classifyProviderError = (
         }
         if (status === 0 && err.isRetryable) return { kind: "network_failure", message };
         if (status >= 500) return { kind: "network_failure", message, retryable: err.isRetryable };
-        if (status === 422 && wireErrorType(body) === "grammar_invalid") {
+        if (status === 413 || (
+            (status === 400 || status === 422)
+            && (
+                (wire.code !== null && CAPACITY_CODE.test(wire.code))
+                || (wire.type !== null && CAPACITY_CODE.test(wire.type))
+                || CAPACITY_MESSAGE.test(wire.message ?? message)
+            )
+        )) {
+            return {
+                kind: "capacity_exceeded",
+                message,
+                extensions: status === 413 ? undefined : { providerStatus: status },
+            };
+        }
+        if (status === 422 && wire.type === "grammar_invalid") {
             return { kind: "grammar_invalid", message };
         }
         return { kind: "invalid_response", message };
@@ -251,22 +150,27 @@ export const toProviderError = (
     err: unknown,
     source: string,
     detailLimit?: number,
+    capacity?: ProviderRequestCapacity,
 ): ProviderError => {
     if (err instanceof ProviderError) return err;
     const underlying = RetryError.isInstance(err) ? err.lastError : err;
     const classified = classifyProviderError(err, detailLimit);
     const { kind, message } = classified;
-    const status = APICallError.isInstance(underlying) ? underlying.statusCode ?? null : null;
+    const upstreamStatus = APICallError.isInstance(underlying) ? underlying.statusCode ?? null : null;
+    const status = kind === "capacity_exceeded" ? 413 : upstreamStatus;
     return new ProviderError(source, kind, message, {
         status,
         cause: err,
         retryable: classified.retryable,
         extensions: {
             ...(classified.extensions ?? {}),
+            ...(kind === "capacity_exceeded" ? { capacityStage: "upstream" } : {}),
+            ...(capacity === undefined ? {} : { capacity }),
             ...(classified.attempts === undefined ? {} : { attempts: classified.attempts }),
             ...(classified.retryExhausted === undefined
                 ? {}
                 : { retryExhausted: classified.retryExhausted }),
         },
+        capacity,
     });
 };

package/src/index.ts

@@ -16,6 +16,8 @@ export type {
     ProviderCallKind,
     ProviderGenerateArgs,
     ProviderRequestAccounting,
+    ProviderRequestCapacity,
+    ProviderRequestCapacityDecision,
     ProviderRequestIdentity,
     ProviderRequestObserver,
     ProviderRequestSettlement,
@@ -25,6 +27,7 @@ export type {
     TokenAlternative,
 } from "./types.ts";
 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
@@ -50,8 +53,8 @@ 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 { 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 {
     addDecimals,

package/src/ollama.test.ts

@@ -11,8 +11,7 @@ const env = Object.freeze({
     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_CACHE_AFFINITY: "1",

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;
 };